Scopes y permisos

Cada API Key tiene asociados scopes — permisos granulares por entidad y acción. Esto permite que un cliente te dé solo los permisos mínimos que tu integración necesita.

(Esto no aplica a JWT: el JWT usa el rol del usuario, no scopes.)

---

Formato de scopes

Los scopes se expresan como entidad:acción. Por ejemplo:

• clientes:read — Puede listar y ver clientes.
• productos:write — Puede crear/modificar/eliminar productos.

---

Entidades disponibles

Entidad	Cubre
clientes	Clientes, direcciones y contactos
productos	Catálogo, precios, stock, tarifas
proveedores	Proveedores y sus condiciones
presupuestos	Presupuestos de venta
pedidos	Pedidos de venta
albaranes	Albaranes de entrada y salida
facturas	Facturas de venta y compra
compras	Documentos de compras
tickets	Tickets de soporte
proyectos	Proyectos y asignaciones

---

Acciones disponibles

Acción	Permite
read	Listar y ver detalle
write	Crear, modificar, eliminar

write no implica read. Si tu integración necesita listar Y crear, pide explícitamente ambos.

---

Ejemplos por caso de uso

Chatbot de WhatsApp (Whatafarma)

Solo necesita consultar clientes y productos:

✅ clientes:read
✅ productos:read

Sincronización con sistema contable

Lee facturas y descarga el resumen, sin modificar nada:

✅ facturas:read
✅ clientes:read

Panel de Business Intelligence

Lectura amplia, sin escritura:

✅ clientes:read
✅ productos:read
✅ facturas:read
✅ pedidos:read

Script de migración temporal

Necesita crear datos masivamente:

✅ clientes:read + clientes:write
✅ productos:read + productos:write

(Después de la migración, el cliente revoca esta clave.)

---

Pedirle scopes al cliente

Cuando entregues tu integración, indícale al cliente qué scopes exactos necesitas y por qué. Por ejemplo:

Para conectar Whatafarma con tu cuenta de TPVReady, genera una API Key con los siguientes permisos:

• Clientes → READ (para que el bot pueda buscar al cliente cuando alguien escribe por WhatsApp)
• Productos → READ (para mostrar el catálogo y precios actualizados en las conversaciones)

No marques permisos de escritura ni de otras entidades.

Esto facilita:

• Que el cliente entienda qué accesos te da y por qué.
• Que confíe más en tu integración (principio de mínimo privilegio).
• Que puedas explicar errores 403 sin ambigüedad.

---

Detectar falta de scope

Si tu petición usa una clave sin el scope necesario, recibirás:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "detail": "La API Key no tiene permiso 'productos:read'. Solicita al administrador que añada el permiso o usa una clave con los scopes adecuados."
}

Tu aplicación debe:

1. Capturar el 403.
2. Notificar al cliente (no a tu equipo) que falta un permiso.
3. Indicarle qué permiso concreto debe añadir desde su panel.

Ejemplo de mensaje claro al cliente:

⚠️ Tu integración con Whatafarma no puede acceder al catálogo de productos.

Para arreglarlo, ve a TPVReady → Configuración → API Keys, edita la clave "Whatafarma producción" y marca Productos → READ. Los cambios son inmediatos, no hace falta regenerar la clave.

---

API Keys con "acceso total"

Por compatibilidad con versiones anteriores, una API Key puede tener scopes = NULL en lugar de un listado concreto. Estas claves tienen acceso a todo sin restricciones por entidad.

Si tu cliente te entrega una clave con acceso total, considera pedirle que la convierta a permisos personalizados con solo los scopes que necesitas. Es más seguro para ambas partes.

---

Resumen

	JWT humano	API Key
Sistema de permisos	Rol fijo del usuario	Scopes granulares por entidad
Personalizable por endpoint	❌ No	✅ Sí
Cambios en tiempo real	El usuario tiene que volver a logearse	Inmediato, sin tocar la clave
Quién lo controla	Admin de la empresa (alta usuarios)	Admin de la empresa (gestión claves)