API de entradas: enviar entradas a Ágora desde una ticketera

La API de entradas de Connect Manager recibe las entradas que vende una ticketera y las crea en el Ágora del local como entradas canjeables. La ticketera hace un POST a https://hub.connectmanager.es/api/v1/tickets con el token del local por cada entrada y por cada cambio de estado; Connect Manager responde al momento y crea, mantiene o anula la entrada en Ágora.

Esta guía es para los desarrolladores de la ticketera (Speakeasy, por ejemplo). La configuración del local en Connect Manager y en Ágora la hace el técnico de FOS o del distribuidor, y está en la guía de la integración de Speakeasy.

Qué necesitas#

Autenticación#

El token va en la cabecera Authorization como Bearer. Sin token, con uno que no existe o con la integración del local desactivada, la respuesta es un 401.

POST /api/v1/tickets HTTP/1.1
Host: hub.connectmanager.es
Authorization: Bearer <token del local>
Content-Type: application/json
Accept: application/json

Enviar una entrada#

Un aviso por entrada y por cada cambio de estado. El mismo entry.id identifica siempre la misma entrada: el segundo aviso no crea otra, la actualiza.

{
  "event_type": "ticket.updated",
  "sent_at": "2026-07-22T18:05:00+02:00",
  "entry": {
    "id": "el7yuiyep0006msyw2pri1tem1LpJwSc",
    "code": "P6J21FF2S",
    "name": "Entrada general",
    "quantity": 1,
    "status": "activated",
    "status_updated_at": "2026-07-22T18:04:30+02:00"
  },
  "workplace": { "id": 11, "name": "Discoteca" },
  "validity": {
    "valid_from": "2026-07-22T18:00:00+02:00",
    "valid_until": "2026-07-23T04:00:00+02:00",
    "timezone": "Europe/Madrid"
  },
  "included_products": { "included_drinks_quantity": 2 },
  "amounts": {
    "currency": "EUR",
    "net_amount": 9.09,
    "tax_rate": 10.0,
    "tax_amount": 0.91,
    "gross_amount": 10.0,
    "total_amount": 10.0
  },
  "payment": {
    "payment_id": "Cl7yuiyhy0007msyw4vfl5ai6YF4WZRn",
    "payment_method": "card",
    "payment_status": "completed"
  }
}

Campos#

Estados#

Una entrada que ya se ha canjeado en barra no se puede anular.

Respuestas#

Orden, repeticiones y reintentos#

• Repetir un aviso no duplica nada: la entrada se identifica por entry.id. Si el aviso no cambia lo que hay en Ágora, no se vuelve a mandar.
• Los avisos pueden llegar desordenados: uno con status_updated_at anterior al último aplicado se guarda en el histórico pero no cambia la entrada. Así, un «activated» que llega tarde no resucita una entrada cancelada.
• Un Ágora apagado no frena la venta: el 200 llega aunque el local no tenga conexión. Connect Manager reintenta crear la entrada en Ágora y, si sigue fallando, la deja en error para reenviarla desde el panel.

sequenceDiagram
    participant T as Ticketera
    participant CM as Connect Manager
    participant AG as Ágora del local
    T->>CM: POST /api/v1/tickets (Bearer)
    CM->>CM: Valida el token, los campos y el workplace
    CM-->>T: 200 recibida
    CM->>AG: Crea, mantiene o anula la entrada
    AG-->>CM: Correcto o error (se reintenta)

Modo prueba#

Las integraciones nuevas empiezan en modo prueba: los avisos se validan, se guardan y responden igual que en producción, pero nada se crea en Ágora. FOS revisa las entradas recibidas y apaga el modo prueba cuando todo llega bien. Las entradas que se mandaron en modo prueba no pasan a Ágora al apagarlo: si alguna era una venta de verdad, hay que volver a mandarla.

Errores frecuentes#

Preguntas frecuentes#

¿Hay que esperar a que la entrada esté en Ágora para responder al cliente?#

No. El 200 llega en cuanto Connect Manager guarda el aviso; crear la entrada en Ágora va por detrás y tarda unos segundos.

¿Puedo mandar el mismo aviso dos veces?#

Sí. La entrada se identifica por entry.id y un aviso que no cambia nada no se vuelve a mandar a Ágora.

¿Qué datos personales llegan a Ágora?#

Ninguno. A Ágora solo van el tipo de entrada, el código y la validez. El cliente, los importes y el pago se guardan en Connect Manager para conciliar.

¿Un token sirve para varios locales?#

No. Cada local tiene su integración y su token, y el workplace tiene que ser el de ese local.

¿Cómo se anula una entrada?#

Mandando el mismo entry.id con el estado cancelled o refunded. Si ya estaba en Ágora, deja de valer.

Fuentes#

• Connect Manager: especificación «Envío de entradas a Ágora» que se entrega a las ticketeras y comportamiento de la API de entradas, versión del 04-11-2026.
• Guía del integrador de Ágora, apartado «Entradas»: importación de entradas con su tipo, su código y su validez.
• Connect Manager: guía de la integración de Speakeasy.