Espejo de Boletos Externos

Espejo de Boletos Externos es la forma en que una ticketera externa conecta sus boletos con el escáner de Gate. Tú cargas tu inventario (el contenido de cada QR, tu identificador del boleto, el titular y los datos que quieras mostrar en puerta) a través de una API con llave; nosotros lo guardamos en un espejo local por evento.

En la puerta, el operador de Gate escanea el QR y la validación ocurre 100 % contra ese espejo: no llamamos a tu API en el momento de la lectura, así que la fila no depende de tu disponibilidad ni de tu latencia. Duplicados, anulaciones, boletos reemitidos y boletos multi-uso se resuelven localmente y de forma atómica.

Cada redención se te devuelve por webhook firmado (ticket.redeemed) con entrega “al menos una vez”, y además puedes consultar las redenciones con un pull paginado para reconciliar. Opcionalmente, un feed programado desde tu lado detecta ventas que nunca nos pusheaste.

Cómo fluye

Tu ticketera                              Gate                           Puerta
────────────                              ────                           ──────
venta / anulación / transferencia
   │
   │  POST /v1/partner/tickets/bulk
   │  POST /v1/partner/tickets/void        ┌──────────────────────┐
   ├──────────────────────────────────────►│  Espejo de boletos   │
   │                                       │  (inventario local   │   escaneo del QR
   │  GET tu feed (cron, opcional)         │   por experiencia)   │◄──────────────────
   │◄──────────────────────────────────────┤                      │
   │                                       │  Validación 100 %    │   OK · DUPLICATE
   │  POST tu notify_url  ticket.redeemed  │  local: nunca llama  │   VOID · NOT_FOUND
   │◄──────────────────────────────────────┤  a tu API en puerta  │   HOLDER_MISMATCH
   │  (HMAC-SHA256, al menos una vez)      └──────────────────────┘
   │
   │  GET /v1/partner/redemptions  (pull con cursor, para reconciliar)
   ├──────────────────────────────────────►

Empezá en 5 pasos

Consigue tu llave y el enlace del evento. El equipo de alpadevs emite tu API key agk_… y enlaza cada experiencia (evento) a tu proveedor. → Autenticación
Carga tu inventario. Un POST /v1/partner/tickets/bulk idempotente por externalRef, hasta 1000 boletos por request. → Guía rápida · Referencia del bulk
Recibe las redenciones. Expón una URL HTTPS, verifica la firma y deduplica por eventId. → Webhooks
Reconcilia. Usa el pull de redenciones y, si quieres, publica un feed para que detectemos drift. → GET /redemptions · Feed de reconciliación
Cubre transferencias y multi-usos. Una sola regla (externalRef y holderRef estables) resuelve ambos casos. → Transferencias · Multi-usos

Antes de salir a producción repasa el checklist de integración.

Datos de conexión

Dato	Valor
Base URL	`https://gate-partners.alpadevs.com`
Health check	`GET /status` → `{ "status": "ok" }` (sin autenticación)
Autenticación	`Authorization: Bearer agk_…`
Formato de errores	`{ "error": { "code": "…", "message": "…" } }`
Rate limit	60 requests por minuto por llave y ruta → `429 RATE_LIMITED`