API v1
Autenticación
Una llave por socio. El programa sale de la llave, no de la URL ni del cuerpo — por eso no puedes elegirlo, y por eso el socio número dos no cuesta desarrollo.
La cabecera
POST https://app.gzanalytics.com/api/v1/ping
Authorization: Bearer gz_live_ehyjhn45u7d34uk7zq7qc4ugbaskjmt5Si tu terminal no puede mandar Authorization —pasa más de lo que parece en
puntos de venta viejos— también aceptamos X-GZ-Key: <llave>.
El prefijo dice el modo
| Prefijo | Qué hace |
|---|---|
gz_live_… | Escribe de verdad: mueve el ledger y el saldo del pase |
gz_test_… | Guarda la transacción para que la veas, pero no mueve el ledger |
La respuesta de ping te lo confirma en modo, y la de
tx en prueba: true. Nadie debería descubrir a media integración
que estuvo escribiendo en producción.
Guardamos solo el SHA-256 de la llave. Se muestra una vez, al crearla, y ni nosotros podemos releerla. Si se pierde, se rota — no hay forma de recuperarla.
Rotar y revocar no son lo mismo
| Acción | La llave anterior | Cuándo |
|---|---|---|
| Rotar | Sigue viva 7 días | Mantenimiento. Sin esa ventana, rotar sería cortarte el servicio hasta que despliegues — y entonces nadie rota nunca |
| Revocar | Muere de inmediato | El botón del incidente. Si crees que la llave se filtró, es este |
Permisos
Cada llave lleva solo lo que el socio necesita.
| Permiso | Habilita | ¿Recibe nombre y correo? | Estado |
|---|---|---|---|
fan:leer |
POST /api/v1/fan/resolve |
Sí | En producción |
tx:escribir |
POST /api/v1/tx |
No | En producción |
redeem:escribir |
POST /api/v1/redeem |
No | En producción |
codigos:escribir |
POST /api/v1/codes |
No | En producción |
roster:leer |
GET /api/v1/roster |
Sí | En producción |
Los permisos que exponen identidad son una transferencia de datos personales. Bajo la LFPDPPP, cada socio que reciba nombre y correo tiene que estar nombrado en el aviso de privacidad del venue — y tiene que estarlo antes del primer dato que se le mande. Un aviso que no lo nombra no se arregla después: los consentimientos ya recabados quedaron sellados contra la versión que la persona aceptó.
Por eso el panel no deja crear una llave con fan:leer o
roster:leer sin que el administrador del venue confirme que su aviso ya te
nombra. Si tu integración necesita identidad, cuenta con ese paso en el calendario.
Sin llave válida, siempre 401
Sin llave, con llave desconocida, revocada, o de un programa desactivado:
401 no_autorizado. Fail-closed, sin excepciones y sin pistas sobre cuál de los
casos fue. El catálogo de errores.