☰ Menú · Claves y permisos
Claves y permisos
Cada petición lleva una clave secreta en la cabecera Authorization. Una clave pertenece a un solo local y se puede limitar a lo que necesita la integración.
curl https://loyaltyfy.io/api/v1/account \
-H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"Envía la clave como Authorization: Bearer <key>. Las peticiones sin clave, con una clave desconocida o con una clave revocada reciben 401.
Claves de prueba y reales
Las claves empiezan por sk_test_ o sk_live_. Ambas trabajan sobre el mismo local y los mismos datos. La diferencia es el indicador livemode en todo lo que crea una clave, para que los informes y los webhooks distingan el tráfico de prueba. Usa claves de prueba mientras desarrollas y cambia a una clave real en el primer turno de verdad.
Permisos
Puedes limitar una clave a ciertos permisos (scopes). Una llamada que necesita un permiso que la clave no tiene recibe 403 con el código missing_scope. Una clave creada sin permisos tiene acceso completo; solo lo recomendamos para los scripts del propio local.
| Permiso | Permite |
|---|---|
| members:read | Buscar socios, listarlos, leer el historial y escanear códigos. |
| members:write | Inscribir socios, actualizar perfiles y asignar números de tarjeta. |
| members:adjust | Sumar o restar cashback a mano indicando un motivo, si el local lo permite. |
| transactions:write | Aplicar y anular tickets, registrar visitas, canjear recompensas y listar transacciones. |
| menu:read | Leer la carta y los platos. |
| menu:write | Crear platos, cambiar precios y gestionar los productos agotados. |
| orders:read | Leer los pedidos de mesa. |
| orders:write | Aceptar, rechazar y hacer avanzar los pedidos por los estados. |
| devices:write | El paquete para quioscos y escáneres: escaneos, visitas, inscripciones y canje de recompensas, sin acceso a la lista de socios ni a los tickets. |
| catalog:read | Leer los productos y las reglas de las categorías. |
| catalog:write | Subir productos y poner nombre a las categorías. Las reglas de dinero de las categorías las decide el propietario. |
| webhooks:write | Gestionar los endpoints de webhook. |
Combinaciones habituales: una caja necesita members:read, members:write y transactions:write. Un escáner en la puerta solo necesita devices:write. Una sincronización de la carta necesita menu:read y menu:write; añade orders:read y orders:write si el TPV recibe pedidos de mesa.
Cómo proteger las claves
- Las claves son secretas. Llama a la API desde tu servidor o desde el back office de la caja, nunca desde un navegador ni desde una app móvil pública.
- Solo guardamos un hash de cada clave. Si pierdes una, revócala en el panel y crea otra nueva; el cambio es inmediato.
- Si puedes, usa una clave por instalación (por caja, por quiosco). Así, al revocar una no se detienen las demás, y Último uso en el panel te dice qué dispositivo está llamando.