API v1

Conecta tu punto de venta en una tarde

Tres llamadas y ya estás acreditando puntos: ping para saber que tu llave sirve, fan/resolve para saber quién trae el QR, y tx para registrar la venta. Todo con curl y nada más.

Esta API nunca crea fans. El alta es siempre el portal cautivo — es lo que hace que el Fan ID tenga un solo origen. Un socio resuelve, referencia y registra; nunca inventa una identidad. Si fan/resolve devuelve fan_no_encontrado, lo correcto en la caja es invitar a la persona a conectarse al WiFi.

Quickstart de 5 minutos

1 Pide una llave de prueba

Escríbenos desde contacto diciendo qué vas a integrar. Te mandamos una llave gz_test_…, que guarda las transacciones para que veas que llegaron pero no mueve el ledger: integrar un viernes no debe poder ensuciarle los saldos a nadie.

Guárdala en el entorno, nunca en el código:

export GZ_KEY=gz_test_ehyjhn45u7d34uk7zq7qc4ugbaskjmt5

2 Comprueba que sirve

curl -X POST https://app.gzanalytics.com/api/v1/ping \
  -H "Authorization: Bearer $GZ_KEY" \
  -H "Content-Type: application/json"

Te contesta quién eres, a qué programa apuntas y qué puedes hacer:

{
  "ok": true,
  "data": {
    "integracion": "Punto de venta",
    "programa": "Fan Pass · Estadio Metropolitano",
    "modo": "vivo",
    "permisos": [
      "fan:leer",
      "tx:escribir"
    ],
    "hora": "2026-08-21T05:15:22.282Z"
  }
}

Si ves "modo": "prueba", estás donde debes. Nadie debería descubrir a media integración que llevaba rato escribiendo en producción.

3 Resuelve al fan

Manda lo que sea que te dio el escáner — Fan ID, token del QR, la URL completa, un código de cupón o el correo. Nosotros lo desciframos.

curl -X POST https://app.gzanalytics.com/api/v1/fan/resolve \
  -H "Authorization: Bearer $GZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fan":"GZM26-2T69D"}'

4 Registra la venta

curl -X POST https://app.gzanalytics.com/api/v1/tx \
  -H "Authorization: Bearer $GZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"TICKET-9001","fan":"GZM26-2T69D","importe":"1,500.50"}'

id_externo es tu identificador de la venta y es obligatorio. Es también la llave de idempotencia: mándalo dos veces y la segunda te contesta "duplicado": true con cero puntos, no un error que tendrías que aprender a interpretar. Cómo funciona.

5 Revisa la bitácora, y pasa a vivo

Cada llamada queda registrada con ruta, código, latencia y un resumen, visible en el panel del venue (⚙️ Configuración → 🔌 Integraciones). Cuando digas "se los mandamos y no llegó", la respuesta está ahí en cinco segundos.

Cuando todo cuadre, pídenos la llave gz_live_…. Tu código no cambia: solo la variable de entorno.

Qué hay disponible hoy

Endpoint	Qué hace	Estado
`POST /api/v1/ping`	¿mi llave sirve?	En producción
`POST /api/v1/fan/resolve`	el momento de la venta	En producción
`POST /api/v1/tx`	venta cerrada	En producción
`POST /api/v1/redeem`	cupón quemado	En producción
`GET /api/v1/promos`	qué promociones hay	En producción
`POST /api/v1/codes`	depositar inventario	En producción
`GET /api/v1/roster`	espejo del padrón	En producción

Todo lo de arriba responde hoy — no hay nada diseñado que aún no esté expuesto. Si te falta algo para tu integración, dinos: lo que pidan los socios es lo que decide qué se construye después.