Autenticación — Visión general
TPVReady soporta dos modelos de autenticación que conviven en la misma API:
- JWT — Para usuarios humanos que inician sesión.
- API Key — Para servicios externos sin humano (chatbots, scripts, automatizaciones).
Ambos coexisten: el mismo endpoint puede aceptar JWT y API Key indistintamente (cuando está habilitado para integración).
Comparativa rápida
| Aspecto | JWT | API Key |
|---|---|---|
| Cómo se obtiene | POST /auth/login con email/password | Generada desde el panel de TPVReady |
| Caducidad | 8 h (renovable con refresh token) | No caduca hasta revocarse |
| Header HTTP | Authorization: Bearer <token> | X-API-Key: <clave> |
| Identidad | Un usuario humano concreto | Una integración (sin humano) |
| Permisos | Los del usuario (admin, vendedor, etc.) | Los scopes asignados a la clave |
| Caso típico | App propia, panel del cliente | Whatafarma, Zapier, scripts |
| Trazabilidad | Qué usuario hizo qué | Qué integración hizo cuántas llamadas |
¿Cuándo usar JWT?
Usa JWT si tu aplicación:
- Tiene usuarios humanos que se registran o inician sesión.
- Necesita actuar en nombre del usuario que está usando la aplicación.
- Es una app móvil propia, un portal web o cualquier producto user-facing.
- Es tu propio frontend consumiendo tu propia API.
¿Cuándo usar API Key?
Usa API Key si tu aplicación:
- Es un servicio backend sin interfaz humana.
- Necesita actuar en nombre de la empresa, no de un usuario concreto.
- Hace llamadas automatizadas (sincronizaciones, chatbots, integraciones).
- Necesita permisos restringidos a ciertas entidades (solo leer clientes, por ejemplo).
- Se distribuye a terceros (un partner, una farmacia que contrata Whatafarma).
¿Y si mi app necesita las dos?
Es perfectamente válido. Casos comunes:
- Webapp con backend propio: el frontend usa JWT de su usuario, y el backend hace llamadas adicionales con API Key para tareas programadas.
- App móvil con sincronización: JWT mientras el usuario navega, API Key para un worker que sincroniza cada hora.
Endpoints públicos (sin autenticación)
Algunos endpoints no requieren auth:
| Endpoint | Para qué |
|---|---|
POST /auth/login | Iniciar sesión y obtener JWT |
POST /auth/registro | Registrar empresa nueva |
POST /auth/google | Login/registro con Google |
POST /auth/refresh | Renovar JWT con refresh token |
GET /auth/verificar-email | Verificar email tras registro |
POST /auth/reset-password | Solicitar reset de contraseña |
GET /sistema/health | Healthcheck público |
Todo lo demás requiere autenticación.