POST /v1/partner/tickets/void

Marca un boleto como void. Es idempotente: anular dos veces responde already_void. Si el boleto ya fue redimido en puerta, la anulación se rechaza: la redención no se pisa.

Método y ruta	POST /v1/partner/tickets/void
Auth	Authorization: Bearer agk_…
Content-Type	application/json
Rate limit	60 req/min por llave

Body

Campo	Tipo	Obligatorio	Límite	Descripción
experienceId	string (UUID)	Sí		Experiencia enlazada a tu proveedor.
externalRef	string	Sí	1 – 200 chars	Tu ID del boleto (el que enviaste en el bulk).

Solo se puede anular por externalRef: un boleto cargado sin externalRef se anula reenviándolo al bulk con status: "void".

Respuesta 200

status	Significado
voided	Anulado ahora. La puerta responderá VOID.
already_void	Ya estaba anulado. No cambia nada.

{ "status": "voided" }

Errores

HTTP	code	Cuándo
400	VALIDATION_FAILED	Body fuera de schema.
401	KEY_INVALID	Llave inválida.
403	EXPERIENCE_NOT_LINKED	La experiencia no está enlazada a tu proveedor.
404	TICKET_NOT_FOUND	No existe ese externalRef en esa experiencia (para tu proveedor).
409	REDEEMED_CONFLICT	El boleto ya entró por la puerta; no se anula desde este endpoint.
429	RATE_LIMITED	Más de 60 requests por minuto.
500	INTERNAL	Error nuestro; reintenta con backoff.

{ "error": { "code": "REDEEMED_CONFLICT", "message": "Ticket already redeemed" } }

No uses void para “invalidar el QR viejo” de una reemisión

void anula por externalRef, es decir, el boleto entero, QR nuevo incluido. Si reemitiste el QR de un boleto (transferencia con QR nuevo), el QR viejo ya quedó invalidado por la reemisión. Ver Transferencias.

Reactivar un boleto anulado

No hay endpoint de “unvoid”. Reenvía la fila al bulk con status: "valid" (o sin status, que equivale a valid).

Ejemplo

curl -s -X POST "https://gate-partners.alpadevs.com/v1/partner/tickets/void" \
  -H "Authorization: Bearer $GATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "experienceId": "22222222-2222-4222-8222-222222222222", "externalRef": "TG-1002" }'

{ "status": "voided" }

Segunda llamada idéntica:

{ "status": "already_void" }