EMPEZAR
Autenticación
Consigue un token de API y autentica tus peticiones.
La API REST (/api/v1/*) usa autenticación por token opaco vía cabecera Authorization: Bearer <token> — independiente de la cookie de sesión que usa la propia app web, nunca se mezclan en la misma ruta. El token se obtiene registrando una cuenta nueva o iniciando sesión en una existente.
Registrar una cuenta nueva
403 registro_cerrado): el alta es por invitación de un despacho o por la web, con verificación del correo. Solo responde si el administrador del servidor define GUILDA_REGISTRO_API=1 (instalaciones propias y desarrollo).curl -X POST https://tu-hostname/api/v1/auth/registro \
-H "Content-Type: application/json" \
-d '{
"email": "dev@tuempresa.com",
"contrasena": "una-contrasena-de-8-caracteres-o-mas",
"nombre_dispositivo": "Mi integración"
}'
{
"ok": true,
"data": {
"token": "kf83h2n...",
"usuario": { "id": 42, "email": "dev@tuempresa.com" }
}
}
Iniciar sesión con una cuenta existente
curl -X POST https://tu-hostname/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "dev@tuempresa.com", "contrasena": "..."}'
Cada llamada a /auth/registro o /auth/login emite un token nuevo — puedes tener varios tokens activos a la vez (uno por dispositivo/integración), y revocar uno concreto sin afectar a los demás con POST /api/v1/auth/logout (revoca el token que viaja en la propia petición).
Usar el token
curl https://tu-hostname/api/v1/auth/me \
-H "Authorization: Bearer kf83h2n..."
Errores de autenticación
| HTTP | Cuándo |
|---|---|
| 400 | Email inválido, contraseña de menos de 8 caracteres, o campos obligatorios ausentes. |
| 401 | Token ausente, revocado o incorrecto — /auth/login con credenciales erróneas también devuelve 401. |
| 409 | /auth/registro con un email que ya tiene cuenta. |
| 429 | Límite de intentos superado (ver aviso de abajo). |
/auth/registro y /auth/login están limitados a 10 peticiones por minuto por IP (protección de fuerza bruta) — si automatizas la creación de cuentas, ten en cuenta ese límite.Tokens de solo lectura, por áreas y con caducidad
Para una integración que solo debe consultar (un panel, un informe), crea un token con permisos: "solo_lectura": puede hacer GET pero cualquier otro método responde 403 Este token es de solo lectura.. Se crea desde Mis dispositivos en la web o con POST /tokens ({"nombre": "...", "permisos": "completo|solo_lectura"}); el token en claro solo se devuelve en ese momento. GET /tokens los lista (con areas, caduca_en, ultimo_uso_en, ultima_ip y llamadas_30d), GET /tokens/{id}/uso da las llamadas y errores por día y DELETE /tokens/{id} revoca uno.
Principio de mínimo privilegio. Al crear un token puedes limitarlo a áreas con areas (notas, tareas, correo, fiscal, fichaje, tiquets, ia, avisos): fuera de ellas responde 403 con codigo: "token_area_no_permitida". Un token con áreas no puede usar las rutas transversales (/historial, /dashboard, /export, /papelera, /buscar, /sync, que mezclan datos de varias áreas) ni gestionar tokens (no puede crear uno más amplio). Siempre puede leer /auth/me, el perfil y /openapi.json. Con caduca_dias (1-3650) o caduca_en el token caduca solo (401, token_caducado); sin caducidad se desconecta tras 90 días sin uso. Combina con permisos: "solo_lectura": p. ej. un panel que solo lee el calendario fiscal.
Paginación opcional
Los listados de historial, tareas, tiques, clientes y vencimientos fiscales y mensajes de correo aceptan limit (1–1000) y offset. Sin ellos devuelven todo, como siempre. La cabecera X-Total-Count lleva el total sin paginar.