Checklist de integración

Repasa cada punto antes del primer evento. Todo lo que está aquí tiene su detalle en las páginas enlazadas.

Credenciales y configuración

• La llave agk_… está guardada solo en el servidor (gestor de secretos), nunca en clientes ni repositorios. → Autenticación
• Tienes el experienceId de cada evento y alpadevs confirmó el enlace al proveedor (una petición de prueba no responde 403 EXPERIENCE_NOT_LINKED). → Conceptos
• Sabes a quién pedir la revocación y una llave nueva, y probaste la rotación.

Inventario (push)

• externalRef es estable por boleto y único dentro de tu proveedor. → Conceptos
• holderRef es estable (userId/teléfono, no nombre ni email) y se envía en cada fila; holderName acompaña. → Transferencias
• qrContent se envía tal cual está en el QR (sin pre-procesar). → Normalización
• Haces push al bulk al vender y void al anular, no solo en syncs periódicos.
• En syncs completos incluyes el status real de cada boleto (un void sin status se reactiva). → Semántica del upsert
• Procesas rejected[] por index y alertas ante reason codes inesperados. → Reason codes
• Haces push al aceptar transferencias (Caso A o B) y nunca envías void tras reemitir un QR. → Transferencias
• Si usas maxUses > 1, nunca lo reduces por debajo de lo consumido. → Multi-usos

Webhook

• Tu endpoint es HTTPS público (no localhost, IP privada ni host interno). → Requisitos de la URL
• Verificas la firma sobre el body crudo con whsec_…, comparación en tiempo constante y tolerancia de 5 min. → Verificación
• Deduplicas por eventId y respondes 2xx a los repetidos.
• Respondes 2xx en menos de 10 s (encolas el procesamiento pesado).
• Manejas uses/max_uses si tienes boletos multi-uso (un evento por uso). → Multi-usos
• Toleras campos nuevos en payload y tipos de evento desconocidos.

Resiliencia

• Reintentas 429 y 500 con backoff exponencial; no reintentas 4xx de configuración. → Errores comunes
• Agrupas en bulk (hasta 1000 filas) en lugar de una petición por boleto.
• Haces pull periódico de GET /v1/partner/redemptions con cursor since guardado, además del webhook. → GET /redemptions
• Registras x-request-id de las respuestas de error.

Opcional

• Publicas un feed { "rows": [...] } (≤ 5000 filas, experienceId por fila, status real) y entregaste a alpadevs la URL y, si aplica, el header Authorization. → Feed de reconciliación