Glosario

Actores

Crowder : Plataforma de ticketing que define este protocolo. Expone el slot de aplicación embebida, llama al GET de estado y dispara los webhooks de eventos. Autentica al partner con api_key.

Ticketera : Operador comercial que opera sobre Crowder. Merchant of record: cobra al usuario final con su propio gateway y le paga al partner según contrato bilateral. Es la contraparte comercial del partner; también es quien da de alta al partner en su instancia de Crowder.

Partner : Tercero que construye una aplicación embebida (vos). Provee iframe, endpoint de estado y endpoint de eventos. Emite las interaction y los partnerItems.

Superficie de integración

Slot : Espacio dentro del checkout de la ticketera donde se renderiza el iframe del partner. Vive solo en el flujo pre-orden.

Aplicación embebida : El producto del partner ejecutándose dentro del slot. Compuesto por el iframe (front) y los dos endpoints HTTP server-to-server (estado y eventos).

api_key : Credencial server-to-server que la ticketera provisiona al partner. Viaja en Authorization: Bearer en el GET de estado y en los webhooks de eventos. Debe validarse en tiempo constante.

Identificadores y datos

interaction : Identificador opaco emitido por el partner. Identifica una operación del partner extremo a extremo. Aparece en postMessage y en las responses HTTP. En los endpoints HTTP server-to-server viaja solo en la URL, nunca en el body.

items : Array de tickets de Crowder presente en el context. Shape: sectorName, rateName, sectionName, etc. (TicketItem). Solo lectura para el partner.

partnerItems : Array de items que el partner ofrece. Shape: uuid, type, description, price, quantity, refundable (PartnerItem). Aditivos al ticket; nunca descuentan del precio base.

refundable (por item) : Boolean obligatorio en cada partnerItem desde confirmed. Declara si el item admite devolución consensuada (pedido del fan, decisión comercial). Crowder solo pide devolver items refundable: true vía purchaseRefunded. Casos no consensuados (chargeback, fraud) bypasean el flag.

context : Mensaje parent → iframe (postMessage, status: "context") con el evento, los items y el usuario. Puede repetirse si cambian los items.

type (objeto padre) : Campo raíz del objeto padre en mensajes postMessage. Hoy se usa solo para la familia visual type: "display" (autosize), donde es obligatorio porque es el único discriminador. Los mensajes del protocolo de negocio (ready, context, selected, submit, submitted, cleared, error) no llevan type: se discriminan por status. No aplica a mensajes HTTP.

type: "display" (autosize) : Mensaje iframe → parent que informa al host la altura del contenido del iframe vía sizes.iframeHeight (px). El host ajusta el <iframe> haciendo clamp con el min-height del slot. El iframe lo emite al montar y en cada cambio de altura (típicamente con ResizeObserver).

sizes.iframeHeight : Altura del contenido del iframe, en píxeles. Único campo de sizes hoy. Viaja solo en mensajes type: "display".

Obligatoriedad del slot : Si la app embebida es obligatoria para avanzar el checkout o es opcional/aditiva es un acuerdo configurado en el dashboard de Crowder, no un campo del protocolo. El iframe nunca lo recibe por wire. La consecuencia: el partner es responsable de habilitar/deshabilitar Continuar emitiendo selected (con todos los obligatorios completos) o cleared (cuando se invalida). En ambos modos el click en Continuar dispara el handshake submit / submitted.

expiresAt / TTL : Timestamp ISO 8601 que el partner devuelve en el ack de purchaseReserved. Marca cuándo vence el hold de stock. Mientras el TTL corre, la interaction está en reserved; al vencer sin pago, transiciona a expired. Crowder dispara purchaseExpired para sincronizar la liberación, pero el TTL local del partner sigue siendo autoritativo (el webhook es complementario).

Lifecycle

Lifecycle : Cadena de estados de una interaction. Estados transitorios: valid, reserved, confirmed. Estados terminales: expired, refunded.

Cotización · valid : Estado inicial. Sin compromiso de stock, sin TTL. La selección del usuario está cotizada pero nada está reservado.

Reserva · reserved : Hold real de stock con expiresAt. Arranca cuando Crowder dispara purchaseReserved y el partner confirma con un expiresAt en el ack.

Expirada · expired : El hold venció sin pago. Solo se llega desde reserved. Crowder notifica vía webhook purchaseExpired; el GET responde HTTP 410.

Confirmada · confirmed : Pago capturado por la ticketera. Fulfillment del partner en curso. La devolubilidad la declara el partner por item con refundable. Devoluciones parciales mantienen la interacción en este estado con partnerItems reducido.

Devuelta · refunded : Terminal. Solo desde confirmed, cuando purchaseRefunded abarca todos los items vigentes de la compra. refund.amount === purchase.amount.

Mensajes postMessage (iframe ↔ parent)

ready : iframe → parent. El iframe avisa que cargó y registró su listener. Debe emitirse después de registrar addEventListener('message').

selected : iframe → parent. Preview de la selección actual. Trae partnerItems para alimentar el resumen del checkout y habilita Continuar. Puede emitirse N veces (cada cambio del usuario). No persiste nada en el backend del partner ni genera interaction.

cleared : iframe → parent. El usuario vació la selección. Limpia el resumen del checkout.

submit : parent → iframe. Crowder le pide al iframe que persista la oferta actual y devuelva la interaction. Se dispara cuando el usuario presiona Continuar.

submitted : iframe → parent. Respuesta a submit. Trae la interaction opaca generada por el partner y ya persistida en lifecycle valid, junto con los partnerItems y la currency.

error : iframe → parent. El iframe falló al construir o concretar la oferta. Puede usarse en cualquier momento, incluyendo como respuesta a submit cuando el partner no puede persistir la cotización.

HTTP server-to-server

Endpoint de estado (GET) : GET {endpoint}/{interaction}. Devuelve el snapshot del lifecycle. Crowder lo llama antes de generar la compra, antes de cada webhook que muta lifecycle, y cuando necesita estado actualizado.

Endpoint de eventos (POST) : POST {endpoint}/{interaction}/events. Recibe los webhooks que disparan transiciones. El body no repite la interaction: vive solo en el path.

Webhook de evento : POST que Crowder le hace al partner para notificar transiciones del lifecycle (purchaseReserved, purchasePaid, purchaseRefunded).

Ack : Respuesta HTTP del partner a un webhook. No hay envelope acknowledged: el código HTTP carga el significado y el body lleva solo el output del evento.

deferred (202) : Ack que indica “recibido, procesamiento async”. Crowder no espera callback posterior: el siguiente GET refleja la realidad cuando el partner termine. Solo aplicable a webhooks; no al GET de estado.

Convenciones del protocolo

Status como discriminador : Todas las interacciones del protocolo —postMessage e HTTP— usan un objeto padre único con status. Cada valor identifica el paso del protocolo y, cuando aplica, el estado o evento.

Modelo unificado : Encoding UTF-8 / JSON. Naming camelCase. Timestamps ISO 8601 UTC. Moneda ISO 4217 a nivel raíz (no por item). Locale BCP 47. IDs internos de Crowder numéricos; IDs opacos externos como string.