Skip to content

Documentação da API Billetto e guia de webhooks

Como autenticar-se, que endpoints chamar e como os webhooks da Billetto enviam dados de bilheteira para os seus sistemas em tempo real. Guias técnicos para programadores que constroem sobre a Billetto.
CENTRO DE PROGRAMADORES

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

AUTENTICAÇÃO

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 e tipos de bilhete

Obtenha os eventos da sua conta com data, local, estado e tipos de bilhete.

  • GET /organiser/events lista 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/orders lista as encomendas de todos os seus eventos
  • GET /organiser/events/{event_id}/attendees lista 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_entries lista 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/webhooks regista 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
Abrir a referência da API

AUDIENCESPasso 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

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
Ler a referência de webhooks
WEBHOOKS DA BILLETTO

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 FUNCIONA

Como é entregue um webhook da Billetto

Da venda de um bilhete ao processamento no seu sistema.
1
REGISTE O ENDPOINT
Adicione um URL HTTPS público no separador Developers ou através da API e guarde o segredo de assinatura que a Billetto lhe dá.
2
ALGO MUDA
Um comprador faz uma encomenda, um bilhete é reembolsado, os dados de um participante mudam ou publica um evento.
3
A BILLETTO ENVIA UM POST
A Billetto envia para o seu URL um HTTP POST com um corpo JSON que descreve a alteração.
4
VERIFIQUE E RESPONDA
Verifique a chamada com o seu segredo de assinatura, responda com um estado 2xx e processe os dados em segundo plano.
BOAS PRÁTICAS DE WEBHOOKS

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
Documentação completa dos endpoints

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.

O recurso webhook

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.

Eventos públicos de todos os organizadores

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.

FAQ DE API E WEBHOOKS

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.

Onde encontro a minha chave API da Billetto?

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.

Qual é a diferença entre um par de chaves API e OAuth?

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.

Que eventos podem os webhooks da Billetto enviar?

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.

Como verifico que uma chamada de webhook vem da Billetto?

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.

Posso criar webhooks através da API?

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.

O que faço perante uma resposta HTTP 429?

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.

Posso mostrar eventos da Billetto no meu site ou plataforma?

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.

Não sou programador. Posso ligar a Billetto a outras ferramentas?

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.

Pronto para a primeira chamada?

Crie um par de chaves em Integrations, abra a referência e chame o seu primeiro endpoint. Se preferir ligar o Google Analytics, o Meta Pixel ou o Zapier sem código, comece pelas integrações Billetto.