Embedded App — Guía para partners

Estado: Draft · Audiencia: equipos técnicos de partners.

Crowder es la plataforma de ticketing sobre la que operan distintas ticketeras. Crowder expone un slot dentro del flujo de compra donde se puede embeber un iframe de un tercero. Ese tercero —vos, el partner— ofrece un producto adicional cuyo precio se suma al total de la orden y se cobra junto con los tickets en un único checkout operado por la ticketera.

Ejemplos típicos: una agencia de viajes que vende paquetes hotel + traslado asociados a un show; una tienda oficial de un club que vende merch junto con la entrada; una empresa que ofrece un seguro de cancelación; una organización deportiva que vende kits de inscripción con extras.

Lo que vas a construir

1. Un iframe hosteado en tu dominio, embebido dentro del checkout de la ticketera. Implementa un protocolo postMessage con la página parent.
2. Un endpoint HTTP de estado (GET) que Crowder llama server-to-server para consultar el lifecycle de una interaction.
3. Un endpoint HTTP de eventos (POST) que recibe los webhooks de Crowder a lo largo del lifecycle (purchaseReserved, purchasePaid, purchaseExpired, purchaseRefunded).
4. Un conjunto de datos de configuración que le entregás a la ticketera para que te de de alta en su instancia de Crowder.

Lo que NO hacés

• No cobrás vos al usuario. La ticketera es merchant of record: cobra con su gateway y te paga después según el contrato comercial bilateral.
• No manejás el branding del checkout. Tu iframe convive dentro del look & feel de la ticketera.
• No hablás directamente con Crowder para el onboarding ni para el contrato comercial. Tu contraparte operativa y comercial es la ticketera. Crowder es la infraestructura sobre la que ella opera y la que define este protocolo.

Quién te llama

Tu entregable	Quién lo invoca
Iframe (front)	Frontend de Crowder, dentro del dominio de la ticketera
Endpoint de estado (GET)	Backend de Crowder
Endpoint de eventos (POST)	Backend de Crowder

Modelo de mensajes

Todos los mensajes del protocolo —tanto los postMessage del iframe como los HTTP— comparten una misma forma: un único objeto con un campo status que indica de qué mensaje se trata. Cada status usa el subconjunto de campos que le aplica; el resto se omite. Así, una sola estructura cubre todo el lifecycle y podés reutilizar el mismo parser/serializer en cliente y servidor.

Aspecto	Valor
Encoding	UTF-8 / JSON
Naming	camelCase
IDs internos de Crowder	Numéricos (event, channel, partner)
IDs opacos externos	Strings (interaction lo emite el partner, uuid por item)
Timestamps	ISO 8601 UTC
Moneda	ISO 4217 a nivel raíz (no por item)
Locale	BCP 47

Lifecycle de una interaction

                   purchaseReserved        purchasePaid           purchaseRefunded (total)
   submitted →  valid  ─────────────→  reserved  ─────────→  confirmed  ────────────────→  refunded
                                          │
                                          │  purchaseExpired (TTL vence)
                                          ▼
                                       expired

• valid: cotización vigente. Sin compromiso de stock, sin TTL.
• reserved: hold real con expiresAt.
• expired: el hold venció sin pago. Crowder dispara purchaseExpired para sincronizar la liberación; el partner igual debe liberar por su cuenta al vencer el TTL local.
• confirmed: pago capturado. Fulfillment del partner en curso. La devolubilidad la declara el partner por item con refundable.
• refunded: terminal. Se alcanza cuando purchaseRefunded abarca todos los items vigentes. Devoluciones parciales mantienen la interacción en confirmed con partnerItems reducido.

Flujo end-to-end

1. El usuario selecciona tickets en el checkout de la ticketera.
2. La página monta tu iframe; vos emitís ready y Crowder responde con context (evento, tickets, usuario).
3. El usuario arma una selección en tu iframe. Vos emitís selected con los partnerItems (podés emitirlo N veces); el resumen del checkout se actualiza. Todavía no se persiste nada.
4. El usuario presiona Continuar. Crowder te envía submit por postMessage. Persistís la oferta en tu backend (lifecycle valid), generás la interaction opaca y respondés con submitted.
5. Crowder hace GET {endpoint}/{interaction} para revalidar (status: valid).
6. Crowder dispara POST {endpoint}/{interaction}/events con status: purchaseReserved. Vos reservás stock real y devolvés expiresAt en el ack — ahí arranca el TTL.
7. Cobro en Crowder. Llega purchasePaid → confirmed.
8. (Opcional, según escenario) purchaseRefunded con los items a devolver (parcial o total).

El punto crítico

La separación entre cotización (valid, sin TTL) y reserva (reserved, con TTL) es deliberada. El compromiso de stock arranca recién cuando recibís purchaseReserved, no cuando el usuario selecciona. Esto evita reservas zombies por sesiones abandonadas.

Alcance

Lo que no está cubierto por el protocolo:

• Descuentos o modificaciones al precio base del ticket. Solo partnerItems aditivos.
• Múltiples partners simultáneos en el mismo evento.
• Slot post-compra (tipo “ya compraste, ¿querés un hotel?”). El iframe vive solo en el flujo pre-orden.
• Multi-currency dentro de una misma interaction. La moneda vive a nivel raíz.
• Notificación posterior al deferred. Si respondés 202 deferred, Crowder no espera callback: el siguiente GET refleja la realidad cuando el partner termine de procesar.

Por dónde seguir

Configuración inicial Qué datos tenés que entregarle a la ticketera para activar tu integración.

Implementación del iframe Protocolo postMessage: ready, context, selected, submit/submitted, cleared, error.

Lineamientos de UI Contrato visual del slot, tipografía, tokens y componentes recomendados.

Endpoint de estado (GET) Snapshot del lifecycle: valid, reserved, expired, confirmed, refunded.

Webhooks de eventos (POST) purchaseReserved, purchasePaid, purchaseExpired, purchaseRefunded.

Tipos compartidos Objeto padre y subobjetos reusados (EventInfo, Venue, User, Purchase, Refund...).

Cuadro maestro de interacciones Mapa único con todas las interacciones del protocolo y qué pasa cuando cada una falla.

Sandbox e integración Cómo testear, checklist de onboarding, validador y template de referencia.

Glosario Términos del protocolo: interaction, partnerItems, lifecycle, ack.

Contacto y soporte

Tu interlocutor primario es la ticketera. Crowder se involucra solo si hay un problema del protocolo mismo o de la plataforma (bug, incidente de seguridad, evolución del protocolo).

Nota

Si encontrás ambigüedades en el protocolo o casos no cubiertos, planteáselo a tu contraparte de la ticketera o al equipo de Crowder por el canal acordado en tu onboarding.