| Espejo | Copia local, por experiencia, del inventario de boletos de un proveedor. La puerta valida contra el espejo, nunca contra la API del proveedor. |
| Proveedor | Una ticketera registrada en Gate. Dueña de sus llaves, sus boletos, su webhook y su feed. |
| Experiencia | Un evento en Gate, identificado por un UUID (experienceId). Cada experiencia valida contra un único proveedor enlazado. |
| Enlace de experiencia | Configuración, hecha por el admin de Gate, que autoriza a un proveedor a operar sobre una experiencia. Sin enlace: 403 EXPERIENCE_NOT_LINKED. |
| API key / llave | Credencial agk_ + 48 hex, enviada como Bearer token. Se muestra una vez; en Gate solo vive su hash. |
externalRef | Identidad estable del boleto en el sistema del proveedor. Clave de idempotencia del bulk y de void/consulta. |
qrContent | Credencial: contenido del QR que se escanea. Se normaliza (trim, parámetro chl de URLs). Puede cambiar por reemisión. |
holderRef / holderName | Titular actual: id estable en el proveedor y nombre para mostrar en puerta. |
| Normalización | Transformación determinista de qrContent aplicada al importar y al escanear, para que ambos lados comparen lo mismo. |
| Upsert | Inserta o actualiza según exista o no el boleto. El bulk y el feed son upserts idempotentes. |
inserted / updated / reissued / rejected | Contadores de la respuesta del bulk: nuevos, actualizados (mismo QR), reemitidos (QR nuevo) y filas rechazadas con motivo. |
| Reason code | Motivo estable de rechazo de una fila del bulk (EMPTY_CODE, REDEEMED_CONFLICT, QR_TAKEN…). No es un error HTTP. |
| Redención | Uso válido de un boleto en puerta. En boletos multi-uso, cada uso es una redención; la última deja el boleto en redeemed. |
valid / redeemed / void | Estados del boleto. redeemed solo lo produce la puerta y es inmutable desde la API. |
maxUses / uses / usesLeft | Cupo de entradas del boleto, usos consumidos y usos restantes tras una lectura. |
| Sello (multi-uso) | Vínculo del boleto multi-uso con el holderRef de su primer uso. Con la política activa, otro titular recibe HOLDER_MISMATCH. |
| Reemisión | Mismo externalRef con un qrContent nuevo. El QR viejo deja de valer (“no existe (reemitido)”). Cuenta en reissued. |
| Transferencia | Cambio de holderRef de un boleto, con (Caso B) o sin (Caso A) reemisión del QR. |
Webhook / notify_url | URL HTTPS pública del proveedor a la que Gate envía ticket.redeemed firmado con HMAC-SHA256. |
whsec_… | Secreto de firma del webhook (whsec_ + 48 hex). Se comparte una vez por rotación. |
eventId | UUID único y estable de un evento de webhook. Clave de deduplicación. |
| Al menos una vez | Garantía de entrega del webhook: puede llegar repetido, nunca perderse silenciosamente (tras 10 fallos pasa a dead-letter). |
| Dead-letter | Evento cuya entrega falló 10 veces. Deja de reintentarse solo; el admin de Gate puede relanzarlo. |
| Pull de redenciones | GET /v1/partner/redemptions: lectura paginada por cursor since, para reconciliar. |
| Feed de reconciliación | URL del proveedor que Gate consulta periódicamente (5 min – 24 h) para sincronizar inventario y detectar drift. |
| Drift | Boletos que existen en el proveedor pero nunca llegaron al espejo por push. Se detectan e importan desde el feed. |
| Rate limit | 60 requests por minuto por llave y ruta. Exceso: 429 RATE_LIMITED. |
| Códigos de puerta | Respuesta del escáner: OK, DUPLICATE, VOID, NOT_FOUND (con marca de reemitido si aplica), HOLDER_MISMATCH. |
