Skip to content

Documentación de la API de Billetto y guía de webhooks

Cómo autenticarte, qué endpoints llamar y cómo los webhooks de Billetto envían datos de venta de entradas a tus sistemas en tiempo real. Guías técnicas para desarrolladores que construyen sobre Billetto.
CENTRO PARA DESARROLLADORES

Qué puedes construir con la API de Billetto

La API de Billetto es una API REST que devuelve JSON. Da a tu propio código acceso a los mismos datos con los que funciona tu venta de entradas: eventos, tipos de entrada, pedidos, asistentes, asientos contables, preguntas de reserva y audiencias. Los webhooks te envían los cambios en cuanto ocurren, sin que tengas que pedirlos.

Los equipos la usan para sincronizar compradores con un CRM, cargar ventas en un data warehouse, mostrar eventos en su propia web, añadir miembros a audiencias de preventa y conciliar los pagos en su sistema financiero. Esta página explica cómo está estructurada la API y cómo funcionan los webhooks. El esquema completo de cada endpoint está en la referencia de la API.

Empieza aquí

AUTENTICACIÓN

Autentícate con un par de claves API u OAuth 2.0

Pares de claves API para tu propia cuenta

Usa un par de claves cuando tus propios sistemas llamen a la API en nombre de tu cuenta de organizador. Créalo en Billetto en Integrations → Developers → API - Key pairs, dale un nombre que describa su uso (por ejemplo "Sincronización CRM" o "Data warehouse") y envíalo en cada llamada en la cabecera Api-Keypair.

  • Crea un par de claves por sistema para poder revocar uno sin afectar a los demás
  • Guarda el secreto en tu servidor. Nunca lo incluyas en un navegador, una app móvil o un repositorio público
  • Revoca y sustituye un par de claves de inmediato si sospechas que se ha filtrado

OAuth 2.0 para apps que usan otros organizadores

Usa OAuth cuando desarrolles un producto al que otros organizadores de Billetto conectan su cuenta, como una herramienta de marketing, una plataforma de eventos o un panel de agencia. OAuth usa el flujo authorization code: el organizador inicia sesión en Billetto, aprueba tu app y recibes un token para su cuenta. Nunca ves su contraseña y puede desconectar tu app en cualquier momento.

Ambos métodos se describen paso a paso en la guía de inicio.

Eventos y tipos de entrada

Obtén los eventos de tu cuenta con fecha, lugar, estado y tipos de entrada.

  • GET /organiser/events lista tus eventos
  • Tipos de entrada, precios y disponibilidad por evento
  • Preguntas de reserva que haces a los compradores en el checkout

Uso típico

Muestra tus próximos eventos con disponibilidad en directo en tu propia web o app y envía a los compradores al checkout de Billetto.

Pedidos y asistentes

Consulta quién compró qué, cuándo y para qué evento.

  • GET /organiser/orders lista los pedidos de todos tus eventos
  • GET /organiser/events/{event_id}/attendees lista los asistentes de un evento
  • Los resultados llegan por páginas: pide la siguiente página hasta que no haya más

Uso típico

Mantén actualizados los datos de compradores en tu CRM o envía listas de asistentes a un sistema de control de acceso o acreditación.

Asientos contables e informes

Obtén el detalle financiero de tus ventas de entradas.

  • GET /organiser/ledger_entries lista ventas, reembolsos, comisiones y pagos
  • Un informe BI por evento con las principales cifras de venta

Uso típico

Carga los ingresos en tu contabilidad o data warehouse y concilíalos con tus pagos.

Audiences y miembros

Escribe datos en Billetto en lugar de solo leerlos.

  • Crear, actualizar y eliminar miembros de audiencias
  • Importar listas completas y seguir el estado de la importación
  • Obtener una audiencia y su número de miembros

Uso típico

Sincroniza miembros, suscriptores o listas de socios desde tu CRM con Audiences para preventas y ofertas exclusivas.

Suscripciones de webhooks

Gestiona los webhooks con código en lugar de en la interfaz de Billetto.

  • POST /organiser/webhooks registra una URL de endpoint
  • Actualizar o eliminar un webhook existente
  • Generar un nuevo secreto de firma para un webhook

Uso típico

Registra webhooks automáticamente al dar de alta un nuevo cliente o entorno, y rota los secretos según un calendario.

Public Event Search

Busca eventos publicados en Billetto de todos los organizadores.

  • Parámetros de consulta para filtrar resultados, descritos en la referencia
  • Cada resultado enlaza a la página del evento y al checkout

Uso típico

Medios, guías de ciudad y plataformas asociadas muestran así lo que está pasando, con entradas vendidas a través de Billetto.

EN LA PRÁCTICA

La API y los webhooks de Billetto, paso a paso

APIPaso 1: acceso

Crea un par de claves y haz tu primera llamada

Abre Integrations, ve a la pestaña Developers y crea un par de claves para el sistema que vas a conectar. Copia el secreto, añádelo a las cabeceras de tu petición y llama a un endpoint como /organiser/orders. La respuesta es JSON que puedes llevar directamente a tu propio modelo de datos.

  • Un par de claves por integración, con el nombre del sistema que lo usa
  • Respuestas JSON para eventos, pedidos, asistentes y asientos contables
  • Revoca un par de claves en cualquier momento sin afectar a los demás
Abrir la referencia de la API

AUDIENCESPaso 2: escribir en Billetto

Añade contactos a una audiencia mediante la API

Los endpoints de Audiences son la forma principal de escribir datos en Billetto. Envía contactos de tu CRM a una audiencia, o importa una lista completa y consulta su estado hasta que esté lista. Después, el grupo está listo para invitaciones, preventas y ofertas exclusivas.

  • Añade, actualiza y elimina miembros uno a uno
  • Importaciones masivas con un estado que puedes consultar
  • Los grupos aparecen al instante en Audiences

WEBHOOKSPaso 3: webhooks de Billetto

Registra un webhook y ve los envíos en directo

Añade la URL de tu endpoint en la pestaña Developers y Billetto genera un secreto de firma para ella. A partir de ahí, cada pedido, reembolso, cambio de asistente o publicación de evento se envía a tu URL como un HTTP POST con un cuerpo JSON.

  • Configuración en la interfaz o mediante POST /organiser/webhooks
  • Un secreto de firma por webhook, que puedes regenerar
  • La tarjeta Webhooks muestra la URL y la versión de API de cada webhook
Leer la referencia de webhooks
WEBHOOKS DE BILLETTO

Qué son los webhooks de Billetto y cuándo usarlos

Un webhook es una URL en tu servidor a la que Billetto llama cuando algo cambia en tu cuenta. En lugar de preguntar a la API cada pocos minutos si hay pedidos nuevos, recibes una llamada en el momento en que un pedido se crea, se reembolsa o cambia.

Por eso los webhooks son la herramienta adecuada cuando el tiempo importa: una confirmación en tu CRM en segundos, un mensaje de Slack cuando se vende una entrada VIP o un sistema de control de acceso que debe saber de una entrada cancelada antes de que se abran las puertas.

¿Webhooks o API?

  • Usa webhooks para reaccionar a los cambios en cuanto ocurren: pedidos nuevos, reembolsos, cambios de asistentes y eventos publicados
  • Usa la API para cargar el histórico, hacer una sincronización completa cada noche u obtener detalles que un webhook no incluye
  • Usa ambos para la solución más fiable: webhooks para la rapidez y una sincronización programada por API que recoja todo lo que se haya perdido
CÓMO FUNCIONA

Cómo se entrega un webhook de Billetto

Desde la venta de una entrada hasta su procesamiento en tu sistema.
1
REGISTRA TU ENDPOINT
Añade una URL HTTPS pública en la pestaña Developers o mediante la API y guarda el secreto de firma que te da Billetto.
2
ALGO CAMBIA
Un comprador hace un pedido, se reembolsa una entrada, cambian los datos de un asistente o publicas un evento.
3
BILLETTO ENVÍA UN POST
Billetto envía a tu URL un HTTP POST con un cuerpo JSON que describe el cambio.
4
VERIFICA Y RESPONDE
Verifica la llamada con tu secreto de firma, responde con un estado 2xx y procesa los datos en segundo plano.
BUENAS PRÁCTICAS DE WEBHOOKS

Construye un receptor de webhooks fiable

Seguridad

  • Verifica cada llamada con el secreto de firma del webhook antes de confiar en su contenido. La referencia de webhooks explica cómo
  • Acepta solo HTTPS y guarda el secreto en la configuración del servidor, no en el código
  • Genera un nuevo secreto si ha podido quedar expuesto y después actualiza tu receptor

Fiabilidad

  • Responde rápido. Devuelve un estado 2xx en cuanto la llamada esté verificada y haz el trabajo pesado en una cola
  • Gestiona los duplicados. Guarda los ID procesados para que el mismo pedido nunca se cree dos veces
  • No dependas del orden. Si importa, obtén el estado actual del pedido mediante la API
  • Concilia con regularidad. Una sincronización programada por API recoge lo que tu endpoint perdió durante una caída
Documentación completa de endpoints

Referencia de la API de Billetto

La referencia de la API documenta cada endpoint con sus parámetros, llamadas de ejemplo y objetos de respuesta. Úsala junto con esta guía cuando empieces a programar: encuentra arriba el recurso adecuado y consulta después los campos exactos en la referencia.

El recurso webhook

Referencia de webhooks

El recurso webhook contiene la configuración de un endpoint: su URL, la versión de API que usa y su secreto de firma. Te recomendamos crear tu primer webhook en Billetto en Integrations → Developers y gestionarlo mediante la API a medida que crezca tu configuración.

Eventos públicos de todos los organizadores

Public Event Search API

La Public Event Search API devuelve los eventos que los organizadores han publicado en Billetto, de todos los organizadores. Es adecuada para medios, guías de ciudad, organismos de turismo y apps asociadas que quieren mostrar lo que está pasando, y cada resultado enlaza a la página del evento en Billetto donde se compran las entradas.

FAQ DE API Y WEBHOOKS

Preguntas sobre la API y los webhooks de Billetto

Preguntas técnicas de desarrolladores que trabajan con la API de Billetto. ¿No encuentras tu respuesta? Habla con nuestro equipo.

¿Dónde encuentro mi clave API de Billetto?

Inicia sesión en Billetto, abre Integrations y ve a la pestaña Developers. En API - Key pairs puedes crear un nuevo par de claves, ver a quién pertenece cada uno y revocar los que ya no uses.

¿Qué diferencia hay entre un par de claves API y OAuth?

Un par de claves da a tus propios sistemas acceso a tu propia cuenta de organizador. OAuth 2.0 es para apps a las que otros organizadores conectan su cuenta de Billetto, para que actúes en su nombre sin conocer sus credenciales.

¿Qué eventos pueden enviar los webhooks de Billetto?

Los webhooks cubren cambios en pedidos, asistentes y eventos, como pedidos nuevos, reembolsos, cambios de asistentes y eventos publicados. La referencia de webhooks lista todos los eventos y su contenido.

¿Cómo verifico que una llamada de webhook viene de Billetto?

Cada webhook tiene su propio secreto de firma. Úsalo para verificar cada llamada entrante antes de procesarla y rechaza las que no superen la verificación. Puedes generar un nuevo secreto para un webhook en cualquier momento.

¿Puedo crear webhooks mediante la API?

Sí. Puedes registrar, actualizar y eliminar webhooks con los endpoints de webhooks, y generar un nuevo secreto de firma para un webhook existente. La mayoría de los equipos empiezan en la interfaz y pasan a la API cuando gestionan varios entornos.

¿Qué hago ante una respuesta HTTP 429?

Un 429 significa que estás enviando demasiadas llamadas. Espera y vuelve a intentarlo con pausas cada vez más largas, y usa webhooks en lugar de consultas frecuentes para mantener bajo el número de llamadas.

¿Puedo mostrar eventos de Billetto en mi propia web o plataforma?

Sí. Usa la Public Event Search API para eventos publicados en Billetto, o el endpoint de eventos del organizador para tus propios eventos. Los compradores completan la compra en el checkout de Billetto.

No soy desarrollador. ¿Puedo conectar Billetto con otras herramientas?

Sí. Google Analytics 4, el Meta Pixel, Zapier y tu propio proveedor de pagos se conectan sin código. En integraciones de Billetto puedes ver lo que puedes configurar en pocos minutos.

¿Listo para tu primera llamada?

Crea un par de claves en Integrations, abre la referencia y llama a tu primer endpoint. Si prefieres conectar Google Analytics, el Meta Pixel o Zapier sin código, empieza por las integraciones de Billetto.