Vende entradas, reservas y listas desde tu propia plataformaSell tickets, bookings and lists from your own platform

La API key se obtiene en autoservicio desde FV Pro, una vez que tu organización está activada. Si eres una organización nueva que solo quiere integrarse por API, antes nos envías un business case breve. Todas las peticiones se autentican con la key en la cabecera X-Api-Key.You get the API key through self-service in FV Pro, once your organization is activated. If you are a new organization that only wants to integrate via API, send us a short business case first. Every request is authenticated with the key in the X-Api-Key header.

El proceso completo: business case (solo organizaciones nuevas) → organización en FV Pro → datos fiscales → activación → solicitud de la clave → prueba con GET/auth.The full process: business case (new organizations only) → organization in FV Pro → tax details → activation → key request → test with GET/auth.

Paso 1. Envía tu business case (solo organizaciones nuevas)Step 1. Send your business case (new organizations only)

Si aún no trabajas con Fourvenues y quieres integrarte solo por API, envía una propuesta breve a integrations@fourvenues.com. Con una página basta:If you don't work with Fourvenues yet and want to integrate via API only, send a short proposal to integrations@fourvenues.com. One page is enough:

• Venues: con qué venues trabajas o quieres trabajar.Venues: which venues you work with or want to work with.
• Volumen: cuánto vendes al año (entradas, reservas o facturación aproximada).Volume: how much you sell per year (tickets, bookings or approximate revenue).
• Canales: en qué otras plataformas o ticketeras vendes hoy.Channels: which other platforms or ticketing providers you sell on today.
• Propuesta de valor: qué aporta la colaboración a los venues y a Fourvenues. Por ejemplo, nuevos públicos, mercados o tipos de cliente a los que llegas.Value proposition: what the partnership brings to the venues and to Fourvenues. For example, new audiences, markets or customer types you reach.

Paso 2. Crea tu organización en FV ProStep 2. Create your organization in FV Pro

Cada entorno es independiente: tendrás una organización y una API key en alpha, y otra organización y otra key en producción. Repite los pasos 2 a 6 en cada entorno, incluidos los datos fiscales y la activación.Each environment is independent: you will have one organization and API key in alpha, and another organization and key in production. Repeat steps 2 to 6 in each environment, including tax details and activation.

Paso 3. Rellena los datos fiscalesStep 3. Fill in your tax details

Completa los datos fiscales de la organización en FV Pro. Sin ellos no se puede activar la cuenta.Complete your organization's tax details in FV Pro. Without them the account cannot be activated.

Paso 4. Solicita la activación de la cuentaStep 4. Request account activation

Pide la activación por email a integrations@fourvenues.com o al equipo de soporte. Fourvenues revisa la solicitud y activa la organización.Request activation by email at integrations@fourvenues.com or through the support team. Fourvenues reviews the request and activates the organization.

Indica en la solicitud si necesitas alta en la pasarela de pagos de Fourvenues. La necesitas en dos casos:State in your request whether you need to be onboarded onto the Fourvenues payment gateway. You need it in two cases:

• Vas a vender con la pasarela de pagos de Fourvenues.You will sell using the Fourvenues payment gateway.
• Quieres comprar entradas de prueba con la pasarela de Fourvenues.You want to buy test tickets with the Fourvenues gateway.

Paso 5. Solicita tu API keyStep 5. Request your API key

Con la cuenta activa, entra en Ajustes > Developer Portal > Solicitar clave. Fourvenues aprueba la solicitud y recibes la key automáticamente por email.Once the account is active, go to Settings > Developer Portal > Request key. Fourvenues approves the request and you receive the key automatically by email.

Si pierdes la key, desde el Developer Portal puedes:If you lose the key, from the Developer Portal you can:

• Reenviarla: recibes una key nueva y la anterior queda cancelada.Resend it: you get a new key and the previous one is cancelled.
• Solicitar una nueva.Request a new one.
• Eliminar las que ya no uses.Delete the ones you no longer use.

Paso 6. Comprueba que funcionaStep 6. Check that it works

Llama siempre desde tu backend. Nunca expongas la key en el navegador ni en una app móvil. Solo se acepta HTTPS.Always call from your backend. Never expose the key in the browser or in a mobile app. Only HTTPS is accepted.

curl --request GET \
  --url 'https://channels-service-alpha.fourvenues.com/auth' \
  --header 'X-Api-Key: TU_API_KEY'

{
  "success": true,
  "data": {
    "message": "Authed",
    "channel": {
      "_id": "ch_abc123",
      "name": "Mi Marketplace",
      "slug": "mi-marketplace",
      "currency": "EUR",
      "hosts": [
        { "_id": "org_xyz789", "name": "Club Ejemplo", "slug": "club-ejemplo", "created_at": "2023-06-01T00:00:00.000Z" }
      ],
      "created_at": "2024-10-01T00:00:00.000Z"
    }
  }
}

• hosts son los venues que te han añadido como partner. Usa su _id como organization_id en el resto de llamadas. Si la lista sale vacía, ningún venue te ha añadido todavía.hosts are the venues that have added you as a partner. Use their _id as organization_id in every other call. If the list is empty, no venue has added you yet.
• anfitrions es un campo antiguo con el mismo contenido y está deprecado. Usa hosts.anfitrions is a legacy field with the same content and is deprecated. Use hosts.
• Si un venue te quita como partner, desaparece de hosts y sus eventos dejan de aparecer. Tu catálogo debe reflejarlo (flujo 2).If a venue removes you as a partner, it disappears from hosts and its events stop appearing. Your catalog must reflect this (flow 2).

Consigue tus venues partnerGet your partner venues

Tener una API key no te da acceso a ningún venue. Cada venue tiene que aceptar la colaboración contigo.Having an API key does not give you access to any venue. Each venue has to accept the partnership with you.

1. Tu equipo contacta con los venues. Fourvenues no puede facilitar los contactos directos de los venues. La relación comercial es tuya.Your team contacts the venues. Fourvenues cannot share venues' direct contacts. The commercial relationship is yours.
2. El venue activa la colaboración. Lo hace desde su panel de configuración en FV Pro o a través de su Account Manager en Fourvenues.The venue activates the partnership. It does so from its settings panel in FV Pro or through its Account Manager at Fourvenues.
3. Compruébalo con GET/auth. En cuanto la colaboración está activa, el venue aparece en hosts.Check it with GET/auth. As soon as the partnership is active, the venue appears in hosts.

Permisos y ciclo de vida de la keyKey permissions and lifecycle

Límites y erroresLimits and errors

No pases de 10 peticiones por segundo por key. Si recibes 429, reintenta con backoff exponencial.Do not exceed 10 requests per second per key. If you get 429, retry with exponential backoff.

El catálogo se lee de arriba abajo: venue, ubicación, evento y, dentro del evento, lo que se puede vender. Todo es de solo lectura: los venues crean y editan sus eventos en FV Pro.The catalog is read top-down: venue, location, event and, inside the event, what can be sold. Everything is read-only: venues create and edit their events in FV Pro.

• Organización (venue o host)Organization (venue or host)
• UbicacionesLocations
• Grupos de eventos (opcional, agrupan varios eventos)Event groups (optional, group several events)
• Eventos, cada uno en una ubicación:Events, each at a location:
• Tarifas de entradaTicket rates
• Tarifas de listaList rates
• Zonas de reserva, con sus mesas y tarifas de mesaBooking zones, with their tables and table rates

Un evento puede pertenecer a un grupo de eventos, que agrupa varias fechas o eventos relacionados.An event can belong to an event group, which groups several dates or related events.

EndpointsEndpoints

populate añade información a cada evento en la misma llamada: ticket-rates, list-rates, event-groups, preregister o * para todo. Sin populate, la respuesta ya trae la ubicación, los artistas y la configuración de preregistro.populate adds information to each event in the same call: ticket-rates, list-rates, event-groups, preregister or * for everything. Without populate, the response already includes the location, artists and pre-registration settings.

Paso 1. Carga los eventos de cada venueStep 1. Load each venue's events

curl --request GET \
  --url 'https://channels-service-alpha.fourvenues.com/events?organization_id=org_xyz789&start_date=2026-10-01&end_date=2026-10-31&populate=ticket-rates&limit=50&offset=0' \
  --header 'X-Api-Key: TU_API_KEY'

Pagina con offset (0, 50, 100…) hasta que la respuesta traiga menos elementos que limit.Paginate with offset (0, 50, 100…) until the response returns fewer items than limit.

Paso 2. Guarda los campos que necesitas para mostrar el eventoStep 2. Store the fields you need to display the event

Paso 3. Lee qué se puede vender en cada eventoStep 3. Read what can be sold at each event

Tarifas de entrada. Estos son los campos que deciden si se puede comprar y cómo:Ticket rates. These are the fields that decide whether and how a purchase can be made:

Zonas de reserva. Cada zona indica si está a la venta (available), si está llena (is_full) y si el comprador puede elegir mesa (can_select_client). Si tiene mesas, vienen en spaces, cada una con capacity, available y sus tarifas. Si no tiene mesas, las tarifas vienen directamente en rates. background_image es el plano de la zona.Booking zones. Each zone shows whether it is on sale (available), whether it is full (is_full) and whether the buyer can choose a table (can_select_client). If it has tables, they come in spaces, each with capacity, available and its rates. If it has no tables, rates come directly in rates. background_image is the zone's floor plan.

Usa GET/bookings/availability?event_id=...&quantity=N para mostrar solo las zonas y mesas con sitio para N personas.Use GET/bookings/availability?event_id=...&quantity=N to show only zones and tables with room for N people.

Paso 4. Mantén el catálogo al díaStep 4. Keep the catalog up to date

Comprueba la tarifa (GET/ticket-rates/{id}) o la zona de reserva en tres momentos:Check the rate (GET/ticket-rates/{id}) or the booking zone at three moments:

Si algo ha cambiado, enseña al comprador las condiciones nuevas antes de continuar.If anything has changed, show the buyer the new conditions before continuing.

Además:Also:

• Sincroniza periódicamente los eventos de cada host, sin pasar de 10 peticiones por segundo.Periodically sync each host's events, without exceeding 10 requests per second.
• Si un evento o un venue deja de aparecer, retira el evento de la venta en tu plataforma.If an event or venue stops appearing, take the event off sale on your platform.

El precio que ve el comprador es el precio del tramo activo más los gastos de gestión. Si compra varias entradas, cada una puede caer en un tramo distinto. GET/ticket-rates/{id}/pricing-info te da el desglose exacto.The price the buyer sees is the active tier price plus service fees. If they buy several tickets, each can fall into a different tier. GET/ticket-rates/{id}/pricing-info gives you the exact breakdown.

El número de decimales depende de la moneda. El euro tiene 2 decimales (12.5 son 12,50 €), pero otras monedas no tienen decimales (por ejemplo, el yen japonés o el peso chileno). Valida y redondea cada importe según los decimales de su currency (estándar ISO 4217) antes de mostrarlo, cobrarlo o enviarlo.The number of decimals depends on the currency. The euro has 2 decimals (12.5 is €12.50), but other currencies have none (for example, the Japanese yen or the Chilean peso). Validate and round each amount to its currency decimals (ISO 4217 standard) before displaying, charging or sending it.

Tramos de precioPrice tiers

Una tarifa de entrada puede tener varios precios (prices), pero solo uno está activo cada vez: current_price. Cuando se agota su cupo (quantity) o pasa su fecha (valid_until), entra el siguiente.A ticket rate can have several prices (prices), but only one is active at a time: current_price. When its allocation (quantity) sells out or its date (valid_until) passes, the next one kicks in.

Si la tarifa tiene show_all_prices: true, el venue quiere que se vean todos los tramos, también los futuros. Si no, muestra solo current_price.If the rate has show_all_prices: true, the venue wants all tiers shown, including future ones. Otherwise, show only current_price.

Orden de cálculoCalculation order

Fourvenues calcula cada entrada siempre en este orden. Con la pasarela de Fourvenues lo hace por ti. Con pasarela externa (flujo 5) tienes que seguir el mismo orden para que tus importes cuadren.Fourvenues always calculates each ticket in this order. With the Fourvenues payment gateway it does it for you. With an external gateway (flow 5) you must follow the same order so your amounts match.

1. Descuento (flujo 12).Discount on the ticket price.
2. Gastos de gestión de la entrada.Ticket service fee, on the discounted price.
3. Complementos y sus gastos de gestión (flujo 10).Add-ons and their fee (the ticket's fee rules).
4. Garantía de cancelación y sus gastos de gestión (flujo 13).Warranty and its fee.
5. Envío por WhatsApp, si aplica.WhatsApp delivery, if applicable.
6. Impuestos y tasas personalizadas, si el venue los tiene.Custom fees.
7. Total de la entrada.Totals.

Gastos de gestión de la entradaTicket service fee

• Con fee_type: fixed = fee_quantity, una vez por entrada.With fee_type: fixed = fee_quantity, once per ticket.
• Con fee_type: percentage = (price − descuento de esa entrada) × fee_quantity / 100. La base es el precio del tramo con el descuento ya aplicado.With fee_type: percentage = (price − that ticket's discount) × fee_quantity / 100. The base is the tier price with the discount already applied.

Los gastos de gestión totales de una entrada son la suma de tres partes: los de la entrada, los de sus complementos y los de su garantía.A ticket's total service fee is the sum of three parts: the ticket's own fee, its add-ons' fees and its warranty's fee.

Envío por WhatsAppWhatsApp delivery

Si las entradas se envían por WhatsApp, el envío cuesta 0,99 € por entrada. Solo está disponible para eventos en euros. Si el venue lo repercute al comprador, se suma al total de cada entrada. Si no, lo asume el venue.If the event sends tickets by WhatsApp, delivery costs €0.99 per ticket (EUR events only). If the venue passes it on to the buyer, add it to the total. If not, the venue absorbs it. Fourvenues never covers it.

Ejemplo completoFull example

Entrada de 20,00 € con gastos del 10 % (percentage), un código de descuento del 10 %, un complemento de 5,00 € sin gastos propios y garantía del 20 %:A €20.00 ticket with a 10% service fee (percentage), a 10% discount code, a €5.00 add-on with no fee of its own and a 20% warranty:

Compras de varias entradasMulti-ticket purchases

Si quedan 2 entradas en el tramo actual y el comprador quiere 3, la tercera va al tramo siguiente. Pide el desglose antes de mostrar el total:If 2 tickets are left in the current tier and the buyer wants 3, the third goes to the next tier. Request the breakdown before showing the total:

curl --request GET \
  --url 'https://channels-service-alpha.fourvenues.com/ticket-rates/tr_111/pricing-info?quantity=3' \
  --header 'X-Api-Key: TU_API_KEY'

La respuesta trae una línea por entrada con price_id, price, fee_type y fee_quantity. Suma las líneas para el total.The response returns one line per ticket with price_id, price, fee_type and fee_quantity. Add up the lines for the total.

Al comprar, envía en cada entrada el price_id que has mostrado. Si el precio ha cambiado entre medias, la respuesta del checkout lo indica con conditions_changed, y debes enseñar el precio nuevo al comprador antes de cobrar.When buying, send in each ticket the price_id you displayed. If the price changed in the meantime, the checkout response flags it with conditions_changed, and you must show the new price to the buyer before charging.

Otros importes que afectan al totalOther amounts that affect the total

Cada uno se detalla en su flujo. Aquí solo lo que tienes que tener en cuenta al calcular precios.Each one is detailed in its own flow. Here is only what you need to consider when calculating prices.

Qué mostrar al compradorWhat to show the buyer

• Precio de la entrada y gastos de gestión por separado, y el total.Ticket price and service fees separately, plus the total.
• Nombre del tramo, includes y additional_info.Tier name, includes and additional_info.
• Complementos y garantía como opciones, con su precio.Add-ons and guarantee as options, with their price.
• El total final antes de enviarlo a pagar.The final total before sending to payment.

Creas una sesión de pago con POST/tickets/checkout, rediriges al comprador a la payment_url y Fourvenues cobra. La venta se confirma cuando recibes el webhook payment.success. No gestionas datos de tarjeta ni reembolsos de pasarela.You create a payment session with POST/tickets/checkout, redirect the buyer to the payment_url and Fourvenues charges. The sale is confirmed when you receive the payment.success webhook. You don't handle card data or gateway refunds.

Resumen del flujoFlow summary

1. Validas la tarifa y el precio (flujos 2 y 3).You validate the rate and price (flows 2 and 3).
2. Creas la sesión con POST/tickets/checkout.You create the session with POST/tickets/checkout.
3. Rediriges al comprador a la payment_url.You redirect the buyer to the payment_url.
4. El comprador paga en Fourvenues.The buyer pays on Fourvenues.
5. Recibes payment.success y das la venta por buena.You receive payment.success and consider the sale complete.
6. El comprador vuelve a tu redirect_url (o a error_url si falla).The buyer returns to your redirect_url (or error_url if it fails).
7. Entregas las entradas, o lo hace Fourvenues si pediste send_resources.You deliver the tickets, or Fourvenues does if you asked for send_resources.

Paso 1. Valida la tarifa justo antes de comprarStep 1. Validate the rate right before buying

Lee la tarifa (GET/ticket-rates/{id}) y comprueba:Read the rate (GET/ticket-rates/{id}) and check:

• available es true y hay stock (availability.available) para la cantidad elegida.available is true and there is stock (availability.available) for the chosen quantity.
• La cantidad está entre min y max.The quantity is between min and max.
• El precio que vas a enviar coincide con el que ha visto el comprador. Para varias entradas, usa pricing-info (flujo 3).The price you will send matches the one the buyer saw. For several tickets, use pricing-info (flow 3).
• Tienes todos los datos obligatorios del comprador y las respuestas a las questions con required: true.You have all the buyer's required data and answers to questions with required: true.

Paso 2. Crea la sesión de pagoStep 2. Create the payment session

curl --request POST \
  --url 'https://channels-service-alpha.fourvenues.com/tickets/checkout' \
  --header 'X-Api-Key: TU_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "ticket_rate_id": "tr_111",
    "redirect_url": "https://tuapp.com/pedido/987/ok",
    "error_url": "https://tuapp.com/pedido/987/error",
    "send_resources": true,
    "metadata": { "order_id": "987" },
    "tickets": [
      {
        "price_id": "price_early",
        "full_name": "Ana García",
        "email": "ana@example.com",
        "phone": "+34600000000",
        "warranty": false,
        "answers": [ { "question_id": "q_1", "answer": "Sí" } ]
      }
    ]
  }'

Paso 3. Revisa la respuesta antes de redirigirStep 3. Check the response before redirecting

{
  "success": true,
  "data": {
    "payment_id": "pay_123",
    "payment_url": "https://...",
    "total_amount": 13.2,
    "conditions_changed": false,
    "tickets": [ { "_id": "tk_1", "status": "pending_payment", "qr_code": "ABCDE12345", "total_price": 13.2 } ]
  }
}

• Guarda payment_id y los _id de las entradas junto a tu pedido.Store payment_id and the tickets' _id with your order.
• Si conditions_changed es true, el precio ha cambiado desde que lo mostraste. Enseña al comprador el nuevo total_amount y pide confirmación antes de redirigir.If conditions_changed is true, the price changed since you displayed it. Show the buyer the new total_amount and ask for confirmation before redirecting.
• Comprueba que total_amount coincide con el total que has mostrado.Check that total_amount matches the total you displayed.

Paso 4. Redirige al compradorStep 4. Redirect the buyer

Envía al comprador a payment_url. Al terminar vuelve a redirect_url o a error_url.Send the buyer to payment_url. When done they return to redirect_url or error_url.

Paso 5. Confirma con el webhookStep 5. Confirm with the webhook

Cuando llega payment.success (flujo 16):When payment.success arrives (flow 16):

1. Verifica la firma.Verify the signature.
2. Localiza tu pedido con metadata o payment_id.Find your order with metadata or payment_id.
3. Para cada id de resource_ids, consulta GET/tickets/{id} y guarda el qr_code y el status.For each id in resource_ids, query GET/tickets/{id} and store the qr_code and status.
4. Marca el pedido como pagado.Mark the order as paid.

Paso 6. Entrega las entradasStep 6. Deliver the tickets

Estados de la entradaTicket statuses

Errores habitualesCommon errors

Cobras al comprador con tu propia pasarela y después creas las entradas en Fourvenues con POST/tickets. Las entradas se crean ya activas y la respuesta de la llamada es la confirmación: no hay webhook de pago. Como cobras tú, también eres responsable del importe que envías y de devolver el dinero si algo falla.You charge the buyer with your own gateway and then create the tickets in Fourvenues with POST/tickets. Tickets are created already active and the call's response is the confirmation: there is no payment webhook. Since you charge, you are also responsible for the amount you send and for refunding if something fails.

Resumen del flujoFlow summary

1. Validas la tarifa y calculas el precio (flujos 2 y 3).You validate the rate and calculate the price (flows 2 and 3).
2. Cobras al comprador en tu pasarela. Si puedes, solo autoriza el cargo.You charge the buyer on your gateway. If you can, only authorize the charge.
3. Validas la tarifa otra vez, justo antes de crear las entradas.You validate the rate again, right before creating the tickets.
4. Creas las entradas con POST/tickets.You create the tickets with POST/tickets.
5. Si la creación va bien, capturas el cargo. Si falla, anulas o devuelves el cargo.If creation succeeds, you capture the charge. If it fails, you void or refund the charge.
6. Entregas las entradas, o lo hace Fourvenues si pediste send_resources.You deliver the tickets, or Fourvenues does if you asked for send_resources.

Paso 1. Calcula el importe de cada entradaStep 1. Calculate each ticket's amount

Aquí Fourvenues no calcula nada por ti. Aplica las reglas del flujo 3 con el tramo vigente:Here Fourvenues calculates nothing for you. Apply the rules from flow 3 with the current tier:

• total_price = precio con descuento + gastos de gestión + garantía y sus gastos (si la compra), calculados en el orden del flujo 3. No incluye los complementos, que van aparte.total_price = discounted price + service fee + warranty and its fee (if bought), calculated in the order from flow 3. It does not include add-ons, which go separately.
• fee = los gastos de gestión incluidos en total_price.fee = the service fees included in total_price.
• price_id = el _id del tramo que has cobrado.price_id = the _id of the tier you charged.
• Si el comprador compra varias entradas, usa pricing-info para saber qué tramo corresponde a cada una.If the buyer buys several tickets, use pricing-info to know which tier applies to each.

Paso 2. Cobra primero, crea despuésStep 2. Charge first, create after

El orden importa, porque entre tu cobro y la creación de las entradas la tarifa puede agotarse o cambiar.Order matters, because between your charge and ticket creation the rate can sell out or change.

No crees entradas antes de cobrar. POST/tickets las crea activas y válidas para entrar desde ese momento.Don't create tickets before charging. POST/tickets creates them active and valid for entry from that moment.

Paso 3. Crea las entradasStep 3. Create the tickets

curl --request POST \
  --url 'https://channels-service-alpha.fourvenues.com/tickets' \
  --header 'X-Api-Key: TU_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "ticket_rate_id": "tr_111",
    "send_resources": false,
    "tickets": [
      {
        "price_id": "price_early",
        "total_price": 13.2,
        "fee": 1.2,
        "full_name": "Ana García",
        "email": "ana@example.com",
        "phone": "+34600000000",
        "warranty": { "enabled": false },
        "supplements": [ { "supplement_id": "sup_1", "price": 5, "quantity": 1 } ]
      }
    ]
  }'

Los campos son los del checkout (flujo 4) con estas diferencias:The fields are those of checkout (flow 4) with these differences:

Paso 4. Guarda la respuestaStep 4. Store the response

La respuesta devuelve un array con las entradas creadas, cada una con su _id, qr_code, status (active) y el desglose de importes. Guarda los _id y qr_code junto a tu pedido.The response returns an array with the created tickets, each with its _id, qr_code, status (active) and amount breakdown. Store the _id and qr_code with your order.

Paso 5. Gestiona los fallos sin duplicar entradasStep 5. Handle failures without duplicating tickets

Si la llamada falla con un error (400, 422), no se ha creado ninguna entrada. Corrige los datos o anula el cargo.If the call fails with an error (400, 422), no ticket was created. Fix the data or void the charge.

Si la llamada da un timeout o no recibes respuesta, no sabes si las entradas se han creado. Antes de reintentar, comprueba si ya existen:If the call times out or you get no response, you don't know whether the tickets were created. Before retrying, check whether they already exist:

• Si dejas que Fourvenues asigne el QR (lo habitual): consulta GET/tickets?event_id=...&ticket_rate_id=... y busca entradas con el email, el teléfono y el nombre de los asistentes de tu pedido.If you let Fourvenues assign the QR (the usual case): query GET/tickets?event_id=...&ticket_rate_id=... and look for tickets with the email, phone and name of your order's attendees.
• Si envías tu propio qr_code: consulta GET/tickets/by-code/{code} con cada código.If you send your own qr_code: query GET/tickets/by-code/{code} with each code.

Si las entradas existen, no las vuelvas a crear: guárdalas en tu pedido y continúa.If the tickets exist, don't create them again: store them in your order and continue.

Paso 6. Entrega las entradasStep 6. Deliver the tickets

Igual que en el flujo 4: con send_resources: true las envía Fourvenues. Con false, entregas tú el qr_code de cada entrada.Same as flow 4: with send_resources: true Fourvenues sends them. With false, you deliver each ticket's qr_code.

ReembolsosRefunds

Como el dinero lo has cobrado tú, el reembolso también lo haces tú en tu pasarela. Fourvenues te avisa con el webhook ticket.request_refund cuando hay que devolver una entrada, y procesarlo es obligatorio: devuelves el dinero y lo registras en Fourvenues para anular la entrada. Se detalla en el flujo 14.Since you took the money, you also refund it on your gateway. Fourvenues notifies you with the ticket.request_refund webhook when a ticket has to be refunded, and processing it is required: you refund the money and record it in Fourvenues to void the ticket. See flow 14.

Errores habitualesCommon errors

El comprador elige zona, tarifa y, si el venue lo permite, mesa. Creas la sesión de pago con POST/bookings/checkout y Fourvenues cobra el depósito o el importe completo. El proceso es el mismo que en la venta de tickets con checkout (flujo 4), pero con los datos de la reserva.The buyer chooses a zone, rate and, if the venue allows it, a table. You create the payment session with POST/bookings/checkout and Fourvenues charges the deposit or the full amount. The process is the same as ticket sales with checkout (flow 4), but with booking data.

Resumen del flujoFlow summary

1. Consultas la disponibilidad para el número de personas.You check availability for the number of people.
2. El comprador elige zona, tarifa y, si se permite, mesa.The buyer chooses zone, rate and, if allowed, table.
3. Calculas y muestras lo que paga ahora y sus condiciones.You calculate and show what they pay now and the conditions.
4. Creas la sesión con POST/bookings/checkout.You create the session with POST/bookings/checkout.
5. Rediriges al comprador a la payment_url.You redirect the buyer to the payment_url.
6. Confirmas el pago y el estado de la reserva.You confirm the payment and the booking status.

Paso 1. Consulta la disponibilidadStep 1. Check availability

curl --request GET \
  --url 'https://channels-service-alpha.fourvenues.com/bookings/availability?event_id=ev_abc123&quantity=6' \
  --header 'X-Api-Key: TU_API_KEY'

La respuesta es una lista de zonas con sitio para ese número de personas. En cada zona:The response is a list of zones with room for that number of people. In each zone:

Como con las entradas, la disponibilidad cambia con cada reserva. Vuelve a consultarla al iniciar la compra y justo antes de crear la sesión.As with tickets, availability changes with every booking. Check it again when starting the purchase and right before creating the session.

Paso 2. Muestra la tarifa y sus condicionesStep 2. Show the rate and its conditions

Cada tarifa de mesa trae:Each table rate includes:

Muestra con claridad qué paga ahora (depósito o total, más gastos y propina) y qué queda pendiente según las condiciones de la tarifa. Cómo se cobra el resto lo decide el venue.Show clearly what they pay now (deposit or total, plus fees and tip) and what remains pending under the rate's conditions. How the rest is charged is up to the venue.

Propinas. Si el venue las usa, GET/tip-rates?organization_id=... devuelve los porcentajes disponibles. is_default marca el que va preseleccionado. Envía el elegido como tip_rate_id.Tips. If the venue uses them, GET/tip-rates?organization_id=... returns the available percentages. is_default marks the preselected one. Send the chosen one as tip_rate_id.

Descuentos. Valida el código antes de crear la sesión con POST/discount-codes/bookings/validate/{code} y envíalo como discount_code.Discounts. Validate the code before creating the session with POST/discount-codes/bookings/validate/{code} and send it as discount_code.

Paso 3. Crea la sesión de pagoStep 3. Create the payment session

curl --request POST \
  --url 'https://channels-service-alpha.fourvenues.com/bookings/checkout' \
  --header 'X-Api-Key: TU_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_id": "ev_abc123",
    "zone_slug": "vip",
    "rate_slug": "mesa-vip",
    "table_id": "tb_12",
    "full_payment": false,
    "tip_rate_id": "tip_10",
    "redirect_url": "https://tuapp.com/reserva/555/ok",
    "error_url": "https://tuapp.com/reserva/555/error",
    "send_resources": true,
    "metadata": { "order_id": "555" },
    "observations_client": "Celebramos un cumpleaños",
    "marketing_consent": false,
    "info": {
      "full_name": "Ana García",
      "email": "ana@example.com",
      "phone": "+34600000000",
      "quantity": 6
    }
  }'

Paso 4. Revisa la respuesta y redirigeStep 4. Check the response and redirect

La respuesta trae payment_id, payment_url, total_amount y la reserva creada (booking), con su _id y status.The response includes payment_id, payment_url, total_amount and the created booking (booking), with its _id and status.

• Guarda el _id de la reserva y el payment_id junto a tu pedido.Store the booking _id and payment_id with your order.
• Comprueba que total_amount coincide con lo que has mostrado.Check that total_amount matches what you displayed.
• Redirige al comprador a payment_url. Al terminar vuelve a redirect_url o a error_url.Redirect the buyer to payment_url. When done they return to redirect_url or error_url.

Paso 5. Confirma la reservaStep 5. Confirm the booking

La vuelta a redirect_url no confirma el pago. Cuando el pago se completa, la reserva pasa a accepted. Consulta la reserva con GET/bookings/{bookingId} y comprueba que está en accepted antes de darla por confirmada.Returning to redirect_url does not confirm payment. When payment completes, the booking moves to accepted. Query the booking with GET/bookings/{bookingId} and check that it is accepted before considering it confirmed.

Para dejar notas de tu canal al venue (por ejemplo, «cliente VIP»), usa PATCH/bookings/{bookingId}/observations con observations_referral.To leave notes from your channel for the venue (for example, "VIP customer"), use PATCH/bookings/{bookingId}/observations with observations_referral.

Estados de una reservaBooking statuses

Envías una solicitud con POST/bookings/request y el venue la revisa en FV Pro para aceptarla o rechazarla. No se cobra nada al reservar. Úsalo cuando el venue gestiona las reservas a mano, por ejemplo en zonas VIP o para grupos grandes.You send a request with POST/bookings/request and the venue reviews it in FV Pro to accept or reject it. Nothing is charged at booking. Use it when the venue handles bookings manually, for example in VIP areas or for large groups.

Resumen del flujoFlow summary

1. Consultas disponibilidad y tarifa (flujo 6, pasos 1 y 2).You check availability and rate (flow 6, steps 1 and 2).
2. Envías la solicitud con POST/bookings/request.You send the request with POST/bookings/request.
3. El venue la revisa en FV Pro.The venue reviews it in FV Pro.
4. Consultas el estado hasta que el venue la acepte o la rechace.You check the status until the venue accepts or rejects it.
5. Informas al comprador del resultado.You inform the buyer of the outcome.

Paso 1. Envía la solicitudStep 1. Send the request

Los campos de zona, tarifa, mesa, titular y facturación son los mismos que en el flujo 6. No se envían redirect_url, error_url, full_payment ni tip_rate_id.Zone, rate, table, holder and billing fields are the same as in flow 6. redirect_url, error_url, full_payment and tip_rate_id are not sent.

curl --request POST \
  --url 'https://channels-service-alpha.fourvenues.com/bookings/request' \
  --header 'X-Api-Key: TU_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "event_id": "ev_abc123",
    "zone_slug": "vip",
    "rate_slug": "mesa-vip",
    "observations_client": "Somos 12, ¿podéis juntar dos mesas?",
    "info": {
      "full_name": "Ana García",
      "email": "ana@example.com",
      "phone": "+34600000000",
      "quantity": 12
    }
  }'

• send_resources es true por defecto: Fourvenues envía al cliente un aviso de que ha recibido su solicitud. Envía false si prefieres avisarle tú.send_resources is true by default: Fourvenues sends the customer a notice that their request was received. Send false if you prefer to notify them yourself.
• Usa observations_client para lo que el venue necesita saber para decidir.Use observations_client for what the venue needs to know to decide.
• Guarda el _id de la reserva que devuelve la respuesta.Store the booking _id returned in the response.

Paso 2. Consulta el estadoStep 2. Check the status

Apuntas a una persona (y a sus acompañantes) en una lista del evento con POST/lists. No hay pago en la API: la lista da acceso en las condiciones que haya configurado el venue. Cada alta genera un QR con el que entra el grupo.You add a person (and their companions) to an event list with POST/lists. There is no payment in the API: the list grants entry on the conditions the venue has set. Each sign-up generates a QR the group enters with.

Resumen del flujoFlow summary

1. Lees las tarifas de lista del evento.You read the event's list rates.
2. Compruebas que la tarifa está disponible y qué datos pide.You check the rate is available and what data it requires.
3. Das de alta la lista con POST/lists.You create the list entry with POST/lists.
4. Entregas el QR, o lo envía Fourvenues.You deliver the QR, or Fourvenues sends it.

Paso 1. Lee las tarifas de listaStep 1. Read the list rates

curl --request GET \
  --url 'https://channels-service-alpha.fourvenues.com/list-rates?event_id=ev_abc123' \
  --header 'X-Api-Key: TU_API_KEY'

Cada elemento de prices describe una franja de la lista:Each item in prices describes a list time slot:

Como en el resto de tarifas, las listas pueden cambiar o cerrarse en cualquier momento. Vuelve a leer la tarifa justo antes de dar el alta.As with other rates, lists can change or close at any time. Read the rate again right before the sign-up.

Paso 2. Da de alta la listaStep 2. Create the list entry

curl --request POST \
  --url 'https://channels-service-alpha.fourvenues.com/lists' \
  --header 'X-Api-Key: TU_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "list_rate_id": "lr_888",
    "send_notification": true,
    "list": {
      "full_name": "Ana García",
      "email": "ana@example.com",
      "for": 3,
      "language": "es"
    }
  }'

Paso 3. Guarda la respuesta y entrega el QRStep 3. Store the response and deliver the QR

La respuesta devuelve la lista creada con su _id, qr_code, for (personas apuntadas) y enter (personas que ya han entrado). Guarda _id y qr_code junto a tu pedido.The response returns the created list with its _id, qr_code, for (people signed up) and enter (people who have already entered). Store _id and qr_code with your order.

Para consultar tus listas más tarde, usa GET/lists?event_id=... (o filtra por list_rate_id), GET/lists/{id} o GET/lists/by-code/{code}.To look up your lists later, use GET/lists?event_id=... (or filter by list_rate_id), GET/lists/{id} or GET/lists/by-code/{code}.

Registras a un interesado en el preregistro de un evento con POST/events/{id}/preregister. Se usa antes de que salgan las entradas a la venta, para captar público y avisarle cuando abra la venta. No crea entradas ni tiene pago.You register someone interested in an event's pre-registration with POST/events/{id}/preregister. It is used before tickets go on sale, to capture an audience and notify them when sales open. It creates no tickets and has no payment.

Resumen del flujoFlow summary

1. Compruebas que el evento tiene el preregistro activo y abierto.You check the event has pre-registration active and open.
2. Muestras el formulario con los campos que pide el evento.You show the form with the fields the event requires.
3. Registras al usuario con POST/events/{id}/preregister.You register the user with POST/events/{id}/preregister.

RequisitosRequirements

• Tu key necesita la capability preregister:write (o all:write). Sin ella la llamada devuelve 403.Your key needs the preregister:write capability (or all:write). Without it the call returns 403.
• El evento tiene que tener el preregistro activo, seguir a la venta y estar dentro del periodo de preregistro.The event must have pre-registration active, still be on sale and be within the pre-registration period.

Paso 1. Lee la configuración del preregistroStep 1. Read the pre-registration settings

La configuración viene por defecto en GET/events y GET/events/{id}, en el campo preregister. Es null si el evento no tiene preregistro.The settings come by default in GET/events and GET/events/{id}, in the preregister field. It is null if the event has no pre-registration.

Paso 2. Construye el formularioStep 2. Build the form

Pide siempre nombre completo y email. Añade los campos de fields y marca como obligatorios los que tengan is_required: true.Always ask for full name and email. Add the fields from fields and mark as required those with is_required: true.

Paso 3. Registra al usuarioStep 3. Register the user

curl --request POST \
  --url 'https://channels-service-alpha.fourvenues.com/events/ev_abc123/preregister' \
  --header 'X-Api-Key: TU_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "fullname": "Ana García",
    "email": "ana@example.com",
    "phone": "+34600000000",
    "remarketing": true
  }'

La respuesta (201) devuelve el _id del registro. Guárdalo junto a tu usuario.The response (201) returns the registration _id. Store it with your user.

Errores habitualesCommon errors

Los complementos son extras que se añaden a una entrada en el momento de la compra: copas, packs de consumición, parking… Se envían por entrada en tickets[].supplements. El comportamiento cambia según la pasarela: en el checkout de Fourvenues los precios y los complementos automáticos los resuelve Fourvenues; con pasarela externa lo haces tú.Add-ons (supplements) are extras added to a ticket at purchase: drinks, drink packs, parking… They are sent per ticket in tickets[].supplements. Behaviour depends on the gateway: in the Fourvenues checkout, Fourvenues resolves prices and automatic add-ons; with an external gateway you do.

Paso 1. Lee los complementos de la tarifaStep 1. Read the rate's add-ons

Vienen en supplements de cada tarifa de entrada (flujo 2).They come in each ticket rate's supplements (flow 2).

Paso 2. Calcula el importeStep 2. Calculate the amount

• Importe del complemento = price × cantidad de packs.Add-on amount = price × number of packs.
• Gastos de gestión: los complementos usan los gastos de la tarifa de entrada. Si son porcentaje (fee_type: percentage), se aplica el mismo porcentaje al importe del complemento. Si son fijos (fixed), no se suma nada más: el importe fijo se cobra una sola vez por entrada.Service fee: add-ons use the ticket rate's fee. If it is a percentage (fee_type: percentage), the same percentage applies to the add-on amount. If it is fixed (fixed), nothing more is added: the fixed amount is charged only once per ticket.

El importe de los complementos y sus gastos se suman al de la entrada, después del descuento y de los gastos de la entrada (orden de cálculo en el flujo 3).The add-on amount and its fees are added to the ticket's, after the discount and the ticket's fee (calculation order in flow 3).

Paso 3. Envíalos en la compraStep 3. Send them with the purchase

En los dos casos:In both cases:

• Si envías el mismo supplement_id varias veces en una entrada, se juntan en una línea y se suman las cantidades antes de validar los límites.If you send the same supplement_id several times in a ticket, they are merged into one line and quantities are added before validating limits.
• Solo se permite un tipo de complemento gratuito por entrada.Only one type of free add-on is allowed per ticket.

"tickets": [
  {
    "price_id": "price_early",
    "full_name": "Ana García",
    "email": "ana@example.com",
    "supplements": [
      { "supplement_id": "sup_1", "quantity": 2 }
    ]
  }
]

Paso 4. Comprueba los complementos de la entradaStep 4. Check the ticket's add-ons

Cada entrada devuelve sus complementos en supplements, con supplement_units (packs comprados), product_quantity (unidades por pack) y total_price de la línea. En la entrada, total_supplements y supplements_service_charge_total dan el total de complementos y de sus gastos.Each ticket returns its add-ons in supplements, with supplement_units (packs bought), product_quantity (units per pack) and the line's total_price. On the ticket, total_supplements and supplements_service_charge_total give the add-on total and their fees.

Errores habitualesCommon errors

El comprador añade complementos a una entrada que ya tiene. Consultas qué complementos puede comprar con GET/tickets/{id}/upselling y creas una sesión de pago con POST/tickets/{id}/upselling/checkout. El cobro lo hace siempre la pasarela de Fourvenues.The buyer adds add-ons to a ticket they already have. You check which add-ons they can buy with GET/tickets/{id}/upselling and create a payment session with POST/tickets/{id}/upselling/checkout. Payment is always handled by the Fourvenues gateway.

Resumen del flujoFlow summary

1. Compruebas que el evento permite upselling.You check the event allows upselling.
2. Consultas el catálogo de complementos disponibles para esa entrada.You query the catalog of add-ons available for that ticket.
3. Creas la sesión de pago con los complementos elegidos.You create the payment session with the chosen add-ons.
4. Rediriges al comprador a la payment_url.You redirect the buyer to the payment_url.
5. Confirmas con el webhook payment.success.You confirm with the payment.success webhook.

Paso 1. Comprueba que el evento lo permiteStep 1. Check the event allows it

El evento tiene que tener is_upselling_enabled: true (flujo 2). Si es false, no ofrezcas añadir complementos después de la compra.The event must have is_upselling_enabled: true (flow 2). If false, don't offer adding add-ons after purchase.

Paso 2. Consulta el catálogoStep 2. Query the catalog

curl --request GET \
  --url 'https://channels-service-alpha.fourvenues.com/tickets/tk_1/upselling' \
  --header 'X-Api-Key: TU_API_KEY'

Devuelve los complementos que se pueden comprar para esa entrada, con los mismos campos que en la tarifa (flujo 10) y dos más:Returns the add-ons that can be bought for that ticket, with the same fields as the rate (flow 10) plus two more:

También devuelve los gastos de gestión de la operación (fee_type, fee_quantity), que se aplican al checkout de upselling.It also returns the operation's service fees (fee_type, fee_quantity), which apply to the upselling checkout.

Paso 3. Crea la sesión de pagoStep 3. Create the payment session

curl --request POST \
  --url 'https://channels-service-alpha.fourvenues.com/tickets/tk_1/upselling/checkout' \
  --header 'X-Api-Key: TU_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "redirect_url": "https://tuapp.com/pedido/987/extras/ok",
    "error_url": "https://tuapp.com/pedido/987/extras/error",
    "send_resources": false,
    "metadata": { "order_id": "987-extras-1" },
    "supplements": [ { "supplement_id": "sup_1", "quantity": 2 } ]
  }'

La respuesta trae payment_id, payment_url, el total de cada línea de complemento y los gastos. Comprueba el total y redirige al comprador a payment_url.The response includes payment_id, payment_url, each add-on line total and the fees. Check the total and redirect the buyer to payment_url.

Paso 4. Confirma el pagoStep 4. Confirm the payment

Igual que en la venta de tickets (flujo 4): no des el upselling por bueno al volver a redirect_url. Espera al webhook payment.success, localiza la operación con metadata o payment_id y vuelve a consultar la entrada (GET/tickets/{id}) para ver sus complementos actualizados.Same as ticket sales (flow 4): don't consider the upsell complete on return to redirect_url. Wait for the payment.success webhook, find the operation with metadata or payment_id and query the ticket again (GET/tickets/{id}) to see its updated add-ons.

Errores habitualesCommon errors

El comprador introduce un código, lo validas con Fourvenues para esa tarifa y esa cantidad, y envías el código en la compra como discount_code. Los códigos los crea el venue. El canal solo los valida y los aplica.The buyer enters a code, you validate it with Fourvenues for that rate and quantity, and you send the code with the purchase as discount_code. Codes are created by the venue. The channel only validates and applies them.

Paso 1. Muestra el campo de código solo si aplicaStep 1. Show the code field only when it applies

En tickets, la tarifa trae has_discount_codes_enabled. Si es false, no muestres el campo de código de descuento.For tickets, the rate includes has_discount_codes_enabled. If false, don't show the discount code field.

Paso 2. Valida el códigoStep 2. Validate the code

Valida el código cada vez que cambie la tarifa, la cantidad o los complementos elegidos. Los parámetros van en la URL.Validate the code every time the rate, quantity or chosen add-ons change. Parameters go in the URL.

curl --request POST \
  --url 'https://channels-service-alpha.fourvenues.com/discount-codes/tickets/validate/VERANO10?rate_id=tr_111&quantity=2&supplements_total_price=10' \
  --header 'X-Api-Key: TU_API_KEY'

Si el código es válido, la respuesta trae sus condiciones:If the code is valid, the response includes its conditions:

Si no es válido, la llamada devuelve 400 o 404. Muestra al comprador que el código no es válido y deja que siga sin descuento.If it isn't valid, the call returns 400 or 404. Tell the buyer the code is invalid and let them continue without a discount.

Cómo se aplica el descuentoHow the discount is applied

El descuento es el primer paso del cálculo (flujo 3): los gastos de gestión y la garantía se calculan sobre el precio ya descontado.The discount is the first step of the calculation (flow 3): service fees and the warranty are calculated on the discounted price.

• En porcentaje: se aplica al precio del tramo de cada entrada. No se aplica a los complementos.Percentage: applied to each ticket's tier price. It does not apply to add-ons.
• Fijo: se aplica una sola vez por compra y se reparte entre las entradas en proporción a su precio. Por ejemplo, con dos entradas de 20,00 € y 30,00 € y un descuento de 10,00 €, la primera recibe el 40 % (4,00 €) y queda en 16,00 €, y la segunda el 60 % (6,00 €) y queda en 24,00 €.Fixed: applied only once per purchase and split across tickets in proportion to their price. For example, with two tickets of €20.00 and €30.00 and a €10.00 discount, the first gets 40% (€4.00) and ends at €16.00, and the second gets 60% (€6.00) and ends at €24.00.
• Céntimos sobrantes: si al repartir un descuento fijo sobran o faltan céntimos, se asignan a la primera entrada del mismo tipo con descuento mayor que cero (o a la primera entrada, si ninguna tiene descuento).Leftover cents: if splitting a fixed discount leaves cents over or short, they go to the first ticket of the same type with a discount greater than zero (or to the first ticket, if none has a discount).

Paso 3. Envíalo en la compraStep 3. Send it with the purchase

Añade discount_code al checkout de tickets (flujo 4), a la creación de entradas (flujo 5) o al checkout de reserva (flujo 6). En tickets se aplica a todas las entradas de la compra.Add discount_code to ticket checkout (flow 4), ticket creation (flow 5) or booking checkout (flow 6). For tickets it applies to all tickets in the purchase.

• Con la pasarela de Fourvenues: Fourvenues aplica el descuento. Comprueba que el total_amount de la respuesta coincide con el total con descuento que has mostrado.With the Fourvenues gateway: Fourvenues applies the discount. Check that the response's total_amount matches the discounted total you displayed.
• Con pasarela externa: cobra el total con el descuento ya aplicado y envía total_price en consecuencia. Cada entrada devuelve el descuento aplicado en discount_amount.With an external gateway: charge the total with the discount already applied and send total_price accordingly. Each ticket returns the discount applied in discount_amount.

Dos extras opcionales que elige el comprador: la garantía de cancelación en las entradas y la propina en las reservas. Los dos los configura el venue. Si no están activos, no los muestres.Two optional extras the buyer chooses: the cancellation guarantee on tickets and the tip on bookings. Both are configured by the venue. If they aren't active, don't show them.

Garantía de cancelación (tickets)Cancellation guarantee (tickets)

La garantía permite al comprador cancelar su entrada hasta unas horas antes del evento. Viene en warranty de cada tarifa de entrada:The guarantee lets the buyer cancel their ticket up to a few hours before the event. It comes in each ticket rate's warranty:

La garantía también lleva gastos de gestión, que siempre son un porcentaje sobre el coste de la garantía.The warranty also carries a service fee, which is always a percentage of the warranty cost.

Ejemplo: entrada con precio con descuento de 18,00 €, un complemento de 5,00 €, garantía del 20 % y gastos de la entrada del 10 %. La garantía cuesta (18,00 + 5,00) × 20 % = 4,60 €, más 4,60 × 10 % = 0,46 € de gastos de gestión.Example: a ticket with a discounted price of €18.00, a €5.00 add-on, a 20% warranty and a 10% ticket fee. The warranty costs (18.00 + 5.00) × 20% = €4.60, plus 4.60 × 10% = €0.46 in service fee.

Cómo se envía:How to send it:

Si la tarifa tiene garantía, envía siempre el campo en cada entrada, aunque el comprador no la quiera (false o enabled: false). En la entrada comprada, warranty devuelve total (lo que ha costado) y hours.If the rate has a guarantee, always send the field in each ticket, even if the buyer doesn't want it (false or enabled: false). On the purchased ticket, warranty returns total (what it cost) and hours.

Muestra la garantía como una opción desmarcada, con su precio y el plazo en el que se puede usar.Show the guarantee as an unchecked option, with its price and the window in which it can be used.

Propinas (reservas)Tips (bookings)

La propina solo existe en las reservas con pasarela de Fourvenues (flujo 6).Tips only exist in bookings with the Fourvenues gateway (flow 6).

curl --request GET \
  --url 'https://channels-service-alpha.fourvenues.com/tip-rates?organization_id=org_xyz789' \
  --header 'X-Api-Key: TU_API_KEY'

Muestra las opciones activas con la de is_default preseleccionada, y permite al comprador no dejar propina.Show the active options with the is_default one preselected, and let the buyer leave no tip.

Quién devuelve el dinero depende de quién lo cobró. Si vendiste con tu pasarela, devuelves tú el dinero y lo registras en Fourvenues con PUT/tickets/{id}/refund. Si vendiste con la pasarela de Fourvenues, el reembolso lo gestiona el venue desde FV Pro.Who refunds depends on who charged. If you sold with your gateway, you refund and record it in Fourvenues with PUT/tickets/{id}/refund. If you sold with the Fourvenues gateway, the venue handles the refund from FV Pro.

Paso 1. Devuelve el dinero en tu pasarelaStep 1. Refund on your gateway

Solo para entradas vendidas con pasarela externa. Las ventas con pasarela de Fourvenues las reembolsa el venue desde FV Pro: no uses este endpoint para ellas. Haz primero la devolución en tu pasarela y, cuando se confirme, regístrala en Fourvenues.Only for tickets sold with an external gateway. Sales with the Fourvenues gateway are refunded by the venue from FV Pro: don't use this endpoint for them. Refund on your gateway first and, once confirmed, record it in Fourvenues.

Paso 2. Registra el reembolsoStep 2. Record the refund

curl --request PUT \
  --url 'https://channels-service-alpha.fourvenues.com/tickets/tk_1/refund' \
  --header 'X-Api-Key: TU_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "amount": 13.2 }'

• amount es el importe devuelto en esta operación, en la moneda de la entrada.amount is the amount refunded in this operation, in the ticket's currency.
• Puedes registrar reembolsos parciales varias veces, hasta completar el importe de la entrada.You can record partial refunds several times, up to the ticket amount.
• La respuesta devuelve la entrada actualizada, con refunded (total devuelto) y refunds (cada devolución, con amount y fecha at).The response returns the updated ticket, with refunded (total refunded) and refunds (each refund, with amount and date at).

Paso 3. Atiende las solicitudes de reembolsoStep 3. Handle refund requests

Cuando hay que devolver el dinero de una entrada, Fourvenues envía el webhook ticket.request_refund (flujo 16) con ticket_id, qr_code, amount_to_refund y currency. Si tienes que procesarlo depende de quién cobró:When money has to be returned for a ticket, Fourvenues sends the ticket.request_refund webhook (flow 16) with ticket_id, qr_code, amount_to_refund and currency. Whether you must process it depends on who took the payment:

Con pasarela externa, sigue estos pasos:With an external gateway, follow these steps:

1. Verifica la firma del webhook.Verify the webhook signature.
2. Devuelve amount_to_refund al comprador en tu pasarela.Refund amount_to_refund to the buyer on your gateway.
3. Registra el reembolso con PUT/tickets/{ticket_id}/refund.Record the refund with PUT/tickets/{ticket_id}/refund.

Paso 4. Refleja los reembolsos que hace el venueStep 4. Reflect refunds made by the venue

Para ventas con pasarela de Fourvenues y para reservas, consulta la entrada (GET/tickets/{id}) o la reserva (GET/bookings/{bookingId}). Una entrada reembolsada aparece como voided y con refunded mayor que cero. Una reserva cancelada o rechazada cambia de status (flujo 6).For sales with the Fourvenues gateway and for bookings, query the ticket (GET/tickets/{id}) or booking (GET/bookings/{bookingId}). A refunded ticket appears as voided with refunded greater than zero. A cancelled or rejected booking changes status (flow 6).

Errores habitualesCommon errors

Concilia periódicamente tus pedidos con lo que hay en Fourvenues: pagos, entradas, reservas y listas. Así detectas webhooks que no llegaron, compras que fallaron a medias y reembolsos que hizo el venue.Periodically reconcile your orders with what is in Fourvenues: payments, tickets, bookings and lists. This way you catch webhooks that didn't arrive, half-failed purchases and refunds the venue made.

Qué puedes consultarWhat you can query

Campos para conciliarFields for reconciliation

Pagos (ventas con pasarela de Fourvenues):Payments (sales with the Fourvenues gateway):

Entradas:Tickets:

Rutina recomendadaRecommended routine

1. Cada día, por evento con ventas: recorre GET/payments?event_id=... y comprueba que cada pago pagado tiene su pedido confirmado en tu sistema. Si falta alguno, es un webhook que no llegó: procesa el pago como si hubiera llegado.Every day, per event with sales: go through GET/payments?event_id=... and check each paid payment has its order confirmed in your system. If one is missing, it's a webhook that didn't arrive: process the payment as if it had.
2. Pedidos pendientes: para cada pedido que siga pendiente en tu sistema, consulta GET/payments/{payment_id}. Si la sesión ha caducado (expires_at) sin pagarse, cancela el pedido.Pending orders: for each order still pending in your system, query GET/payments/{payment_id}. If the session expired (expires_at) unpaid, cancel the order.
3. Reembolsos: compara refunded de tus entradas con los reembolsos de tu sistema, para reflejar los que haya hecho el venue.Refunds: compare your tickets' refunded with the refunds in your system, to reflect any the venue made.
4. Después del evento: enter y entry_time te dan la asistencia real de cada entrada y lista.After the event: enter and entry_time give you actual attendance for each ticket and list.

Pagina siempre con offset hasta el final y respeta el límite de 10 peticiones por segundo (flujo 1).Always paginate with offset to the end and respect the 10 requests per second limit (flow 1).

Los webhooks confirman los pagos y avisan de las solicitudes de reembolso. Son la única confirmación fiable de un pago: no des una compra por buena solo porque el comprador ha vuelto a tu redirect_url.Webhooks confirm payments and notify refund requests. They are the only reliable payment confirmation: don't consider a purchase complete just because the buyer returned to your redirect_url.

1. Tu backend crea el checkout (POST/tickets/checkout) y recibe una payment_url.Your backend creates the checkout (POST/tickets/checkout) and receives a payment_url.
2. Rediriges al comprador a la payment_url.You redirect the buyer to the payment_url.
3. El comprador paga en Fourvenues.The buyer pays on Fourvenues.
4. Fourvenues envía el webhook payment.success a tu endpoint.Fourvenues sends the payment.success webhook to your endpoint.
5. Tu backend verifica la firma, guarda el evento y responde 200.Your backend verifies the signature, stores the event and responds 200.
6. Fourvenues redirige al comprador a tu redirect_url.Fourvenues redirects the buyer to your redirect_url.

Paso 1. Registra tu endpointStep 1. Register your endpoint

curl --request POST \
  --url 'https://channels-service-alpha.fourvenues.com/webhooks/endpoints' \
  --header 'X-Api-Key: TU_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Producción", "url": "https://tuapp.com/webhooks/fourvenues" }'

{
  "success": true,
  "data": { "_id": "wh_123", "name": "Producción", "url": "https://tuapp.com/webhooks/fourvenues", "sign_secret": "..." }
}

• Guarda sign_secret como secreto en cuanto lo recibas. Lo necesitas para verificar cada evento.Store sign_secret as a secret as soon as you receive it. You need it to verify every event.
• El endpoint recibe todos los eventos de tu canal. name es solo una etiqueta y no filtra nada.The endpoint receives all events for your channel. name is just a label and filters nothing.
• La URL tiene que ser HTTPS y pública. Para probar en local, expón tu servidor con una herramienta como ngrok.The URL must be HTTPS and public. To test locally, expose your server with a tool such as ngrok.
• GET/webhooks/endpoints lista tus endpoints y DELETE/webhooks/endpoints/{id} borra uno.GET/webhooks/endpoints lists your endpoints and DELETE/webhooks/endpoints/{id} deletes one.

Paso 2. Verifica la firma de cada eventoStep 2. Verify each event's signature

Cada evento llega como un POST con JSON y dos cabeceras:Each event arrives as a JSON POST with two headers:

const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/webhooks/fourvenues', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.header('X-Webhook-Signature') || '';
  const expected = crypto
    .createHmac('sha256', process.env.FV_SIGN_SECRET)
    .update(req.body) // cuerpo tal cual llega, sin parsear
    .digest('hex');

  const valid = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!valid) return res.status(403).send('Invalid signature');

  const event = JSON.parse(req.body);
  queue.push(event); // procesa en segundo plano
  res.status(200).send();
});

Calcula la firma sobre el cuerpo tal cual llega. Si lo parseas antes y lo vuelves a serializar, la firma puede no coincidir. Rechaza con 403 cualquier evento con firma incorrecta y regístralo.Compute the signature over the body exactly as received. If you parse and re-serialize it first, the signature may not match. Reject any event with an incorrect signature with 403 and log it.

Paso 3. Procesa el eventoStep 3. Process the event

Todos los eventos tienen la misma estructura: id, event (tipo) y payload (datos del evento).All events share the same structure: id, event (type) and payload (event data).

{
  "id": "5f7b1b3b-7b7b-4b7b-8b7b-9b7b1b3b7b7b",
  "event": "payment.success",
  "payload": {
    "payment_id": "pay_123",
    "resource_type": "ticket",
    "resource_ids": ["tk_1", "tk_2"],
    "metadata": { "order_id": "tu-pedido-987" },
    "send_resources": true
  }
}

• Usa metadata para enlazar el pago con tu pedido. Envía tu identificador interno al crear el checkout (máximo 1 KB, sin datos personales).Use metadata to link the payment to your order. Send your internal identifier when creating the checkout (max 1 KB, no personal data).
• Con resource_ids, consulta cada recurso (p. ej. GET/tickets/{id}) para obtener el QR y el estado final.With resource_ids, query each resource (e.g. GET/tickets/{id}) to get the QR and final status.
• resource_type indica qué se ha pagado. Si llega un valor que no reconoces, responde 200 y regístralo.resource_type indicates what was paid. If you get a value you don't recognize, respond 200 and log it.
• Responde 200 también a los tipos de evento que no uses. Pueden añadirse eventos nuevos.Also respond 200 to event types you don't use. New events may be added.

Paso 4. Reintentos e idempotenciaStep 4. Retries and idempotency

Si tu endpoint no responde con un 2xx, Fourvenues reintenta el envío hasta 40 veces. La espera antes del reintento n es n^1,5 segundos más hasta 1 segundo aleatorio. En total los reintentos cubren unos 70 minutos. Después, el evento queda marcado como fallido.If your endpoint doesn't respond with a 2xx, Fourvenues retries delivery up to 40 times. The wait before retry n is n^1.5 seconds plus up to 1 random second. In total retries cover about 70 minutes. After that, the event is marked as failed.

• Responde en menos de 5 segundos. Encola el trabajo y procésalo aparte.Respond in under 5 seconds. Queue the work and process it separately.
• Un mismo evento puede llegar más de una vez. Guarda el id de cada evento procesado e ignora los repetidos.The same event can arrive more than once. Store each processed event's id and ignore duplicates.
• Si tu sistema ha estado caído más tiempo, concilia con GET/payments y GET/tickets.If your system was down longer, reconcile with GET/payments and GET/tickets.