Documentação da API Billetto e guia de webhooks
O que pode construir com a API Billetto
A API Billetto é uma API REST que devolve JSON. Dá ao seu próprio código acesso aos mesmos dados que fazem funcionar a sua bilheteira: eventos, tipos de bilhete, encomendas, participantes, lançamentos contabilísticos, perguntas de reserva e audiências. Os webhooks enviam-lhe as alterações assim que acontecem, sem ter de as pedir.
As equipas usam-na para sincronizar compradores com um CRM, carregar vendas num data warehouse, mostrar eventos no seu próprio site, adicionar membros a audiências de pré-venda e reconciliar pagamentos no sistema financeiro. Esta página explica como a API está estruturada e como funcionam os webhooks. O esquema completo de cada endpoint está na referência da API.
Comece aqui
- Guia de introdução: crie as suas credenciais e faça a primeira chamada
- Referência da API: todos os endpoints, parâmetros e objetos de resposta
- Referência de webhooks: o recurso webhook e os seus campos
- Public Event Search: obtenha os eventos públicos disponíveis na Billetto
Autentique-se com um par de chaves API ou OAuth 2.0
Pares de chaves API para a sua própria conta
Use um par de chaves quando os seus próprios sistemas chamam a API em nome da sua conta de organizador. Crie-o na Billetto em Integrations → Developers → API - Key pairs, dê-lhe um nome que descreva a sua finalidade (por exemplo "Sincronização CRM" ou "Data warehouse") e envie-o em cada chamada no cabeçalho Api-Keypair.
- Crie um par de chaves por sistema, para poder revogar um sem afetar os outros
- Guarde o segredo no seu servidor. Nunca o coloque num browser, numa app móvel ou num repositório público
- Revogue e substitua um par de chaves de imediato se suspeitar que foi exposto
OAuth 2.0 para apps usadas por outros organizadores
Use OAuth quando desenvolve um produto ao qual outros organizadores da Billetto ligam a sua conta, como uma ferramenta de marketing, uma plataforma de eventos ou um painel de agência. O OAuth usa o fluxo authorization code: o organizador inicia sessão na Billetto, aprova a sua app e recebe um token para a conta dele. Nunca vê a palavra-passe e ele pode desligar a sua app a qualquer momento.
Ambos os métodos são descritos passo a passo no guia de introdução.
- Eventos
- Encomendas e participantes
- Finanças e relatórios
- Audiences
- Webhooks
- Eventos públicos
Eventos e tipos de bilhete
Obtenha os eventos da sua conta com data, local, estado e tipos de bilhete.
GET /organiser/eventslista os seus eventos- Tipos de bilhete, preços e disponibilidade por evento
- Perguntas de reserva feitas aos compradores no checkout
Utilização típica
Mostre os seus próximos eventos com disponibilidade em tempo real no seu site ou app e encaminhe os compradores para o checkout da Billetto.
Encomendas e participantes
Veja quem comprou o quê, quando e para que evento.
GET /organiser/orderslista as encomendas de todos os seus eventosGET /organiser/events/{event_id}/attendeeslista os participantes de um evento- Os resultados vêm por páginas: peça a página seguinte até não haver mais
Utilização típica
Mantenha os dados dos compradores atualizados no seu CRM ou envie listas de participantes para um sistema de controlo de acessos ou acreditação.
Lançamentos contabilísticos e relatórios
Obtenha o detalhe financeiro das suas vendas de bilhetes.
GET /organiser/ledger_entrieslista vendas, reembolsos, taxas e pagamentos- Um relatório BI por evento com os principais números de vendas
Utilização típica
Carregue as receitas na sua contabilidade ou data warehouse e reconcilie-as com os seus pagamentos.
Audiences e membros
Escreva dados na Billetto em vez de apenas os ler.
- Criar, atualizar e remover membros de audiências
- Importar listas completas e acompanhar o estado da importação
- Obter uma audiência e o respetivo número de membros
Utilização típica
Sincronize membros, subscritores ou listas de parceiros do seu CRM com Audiences para pré-vendas e ofertas exclusivas.
Subscrições de webhooks
Gira os webhooks por código em vez de na interface da Billetto.
POST /organiser/webhooksregista um URL de endpoint- Atualizar ou remover um webhook existente
- Gerar um novo segredo de assinatura para um webhook
Utilização típica
Registe webhooks automaticamente quando configura um novo cliente ou ambiente e renove os segredos de forma programada.
Public Event Search
Pesquise eventos publicados na Billetto, de todos os organizadores.
- Parâmetros de consulta para filtrar resultados, descritos na referência
- Cada resultado liga à página do evento e ao checkout
Utilização típica
Meios de comunicação, guias de cidade e plataformas parceiras mostram assim o que está a acontecer, com bilhetes vendidos através da Billetto.
NA PRÁTICA
A API e os webhooks da Billetto, passo a passo
APIPasso 1: acesso
Crie um par de chaves e faça a primeira chamada
Abra Integrations, vá ao separador Developers e crie um par de chaves para o sistema que está a ligar. Copie o segredo, adicione-o aos cabeçalhos do pedido e chame um endpoint como /organiser/orders. A resposta é JSON que pode levar diretamente para o seu próprio modelo de dados.
- Um par de chaves por integração, com o nome do sistema que o usa
- Respostas JSON para eventos, encomendas, participantes e lançamentos contabilísticos
- Revogue um par de chaves a qualquer momento sem afetar os outros
Integrations
Dados de exemploAPI - Key pairs
+ Create key pairAUDIENCESPasso 2: escrever na Billetto
Adicione contactos a uma audiência através da API
Os endpoints de Audiences são a principal forma de escrever dados na Billetto. Envie contactos do seu CRM para uma audiência, ou importe uma lista completa e consulte o estado até estar pronta. Depois disso, o grupo está pronto para convites, pré-vendas e ofertas exclusivas.
- Adicione, atualize e remova membros um a um
- Importações em massa com um estado que pode consultar
- Os grupos aparecem de imediato em Audiences
Audiences
Dados de exemploVIP members 2026Synced via API
WEBHOOKSPasso 3: webhooks da Billetto
Registe um webhook e veja os envios em tempo real
Adicione o URL do seu endpoint no separador Developers e a Billetto gera um segredo de assinatura para ele. A partir daí, cada encomenda, reembolso, alteração de participante ou publicação de evento é enviada para o seu URL como um HTTP POST com um corpo JSON.
- Configuração na interface ou através de POST /organiser/webhooks
- Um segredo de assinatura por webhook, que pode voltar a gerar
- O cartão Webhooks mostra o URL e a versão da API de cada webhook
Integrations
Dados de exemploWebhooks
Receive data based on specific webhook events
Recent deliveriesLive
O que são os webhooks da Billetto e quando os usar
Um webhook é um URL no seu servidor que a Billetto chama quando algo muda na sua conta. Em vez de perguntar à API de poucos em poucos minutos se há novas encomendas, recebe uma chamada no momento em que uma encomenda é criada, reembolsada ou alterada.
É por isso que os webhooks são a ferramenta certa quando o tempo conta: uma confirmação no seu CRM em segundos, uma mensagem no Slack quando é vendido um bilhete VIP, ou um sistema de controlo de acessos que precisa de saber de um bilhete cancelado antes de as portas abrirem.
Webhooks ou API?
- Use webhooks para reagir às alterações assim que acontecem: novas encomendas, reembolsos, alterações de participantes e eventos publicados
- Use a API para carregar o histórico, fazer uma sincronização completa todas as noites ou obter detalhes que um webhook não inclui
- Use ambos para a solução mais fiável: webhooks pela rapidez e uma sincronização programada pela API que recupera tudo o que tenha falhado
Como é entregue um webhook da Billetto
Da venda de um bilhete ao processamento no seu sistema.Construa um recetor de webhooks fiável
Segurança
- Verifique cada chamada com o segredo de assinatura do webhook antes de confiar no conteúdo. A referência de webhooks explica como
- Aceite apenas HTTPS e guarde o segredo na configuração do servidor, não no código
- Gere um novo segredo se este puder ter sido exposto e depois atualize o seu recetor
Fiabilidade
- Responda depressa. Devolva um estado 2xx assim que a chamada estiver verificada e faça o trabalho pesado numa fila
- Trate duplicados. Guarde os IDs processados para que a mesma encomenda nunca seja criada duas vezes
- Não dependa da ordem. Se for importante, obtenha o estado atual da encomenda através da API
- Reconcilie regularmente. Uma sincronização programada pela API recupera o que o seu endpoint perdeu durante uma falha
Referência da API Billetto
A referência da API documenta cada endpoint com parâmetros, chamadas de exemplo e objetos de resposta. Use-a em conjunto com este guia quando começar a programar: encontre acima o recurso certo e consulte depois os campos exatos na referência.
Referência de webhooks
O recurso webhook contém a configuração de um endpoint: o URL, a versão da API utilizada e o segredo de assinatura. Recomendamos que crie o primeiro webhook na Billetto em Integrations → Developers e o gira através da API à medida que a sua configuração cresce.
Public Event Search API
A Public Event Search API devolve os eventos que os organizadores publicaram na Billetto, de todos os organizadores. É adequada para meios de comunicação, guias de cidade, entidades de turismo e apps parceiras que querem mostrar o que está a acontecer, com cada resultado a ligar à página do evento na Billetto onde os bilhetes são comprados.
Perguntas sobre a API e os webhooks da Billetto
Perguntas técnicas de programadores que trabalham com a API Billetto. Não encontra a sua resposta? Fale com a nossa equipa.
Inicie sessão na Billetto, abra Integrations e vá ao separador Developers. Em API - Key pairs pode criar um novo par de chaves, ver a quem pertence cada um e revogar os que já não usa.
Um par de chaves dá aos seus próprios sistemas acesso à sua própria conta de organizador. O OAuth 2.0 destina-se a apps às quais outros organizadores ligam a sua conta Billetto, para agir em nome deles sem conhecer as suas credenciais.
Os webhooks cobrem alterações em encomendas, participantes e eventos, como novas encomendas, reembolsos, alterações de participantes e eventos publicados. A referência de webhooks lista todos os eventos e o seu conteúdo.
Cada webhook tem o seu próprio segredo de assinatura. Use-o para verificar cada chamada recebida antes de a processar e rejeite as chamadas que falhem a verificação. Pode gerar um novo segredo para um webhook a qualquer momento.
Sim. Pode registar, atualizar e remover webhooks através dos endpoints de webhooks e gerar um novo segredo de assinatura para um webhook existente. A maioria das equipas começa na interface e passa para a API quando gere vários ambientes.
Um 429 significa que está a enviar demasiadas chamadas. Aguarde e tente novamente com pausas cada vez mais longas, e use webhooks em vez de consultas frequentes para manter baixo o número de chamadas.
Sim. Use a Public Event Search API para eventos publicados na Billetto, ou o endpoint de eventos do organizador para os seus próprios eventos. Os compradores concluem a compra no checkout da Billetto.
Sim. O Google Analytics 4, o Meta Pixel, o Zapier e o seu próprio fornecedor de pagamentos ligam-se sem código. Em integrações Billetto pode ver o que consegue configurar em poucos minutos.
Denmark