Quando o teu negócio precisa de integrar ticketing na infraestrutura existente, a qualidade da API é determinante. Se ainda estás a avaliar opções, o nosso guia sobre como escolher plataforma de ticketing cobre os critérios-chave. Uma API mal concebida significa meses de desenvolvimento, bugs constantes e limitações que descobres demasiado tarde. Este guia ajuda-te a avaliar o que procurar antes de te comprometeres com uma plataforma.
A boa notícia é que quase nada do que é preciso exigir é opinião. A maior parte está escrita em especificações públicas: OpenAPI para o contrato, as RFC do IETF para a autenticação, os erros e o fim de vida de um endpoint, e a documentação do fornecedor de pagamentos para a entrega de eventos. O que se segue é essa lista, com a referência concreta ao lado.
O que indica a qualidade da documentação de uma API?
A qualidade da documentação reflete a maturidade da API. Procura estes elementos:
- Especificação OpenAPI/Swagger: permite gerar clientes automaticamente
- Exemplos de código: nas linguagens que utilizas (JS, Python, PHP...)
- Guias de casos de uso: não só referência, também tutoriais
- Changelog: histórico de alterações e política de versionamento
- Status page: visibilidade sobre a disponibilidade do serviço
O padrão tem nome e data. A OpenAPI Specification 3.1.0 foi publicada em 15 de fevereiro de 2021 e exige um campo openapi com a versão da especificação que o documento utiliza, distinto da versão da própria API. Admite JSON e YAML, e recomenda YAML 1.2 para que a conversão entre ambos não perca informação.
O contraste prático é simples. Um documento OpenAPI válido carrega-se num gerador e produz um cliente tipado na tua linguagem em minutos. Um PDF ou uma página de exemplos avulsos não. Pede o ficheiro, não a captura de ecrã: se o fornecedor não conseguir entregar-te o openapi.yaml no mesmo dia em que o pedes, a integração começa com dívida.
Como deve autenticar-se uma API de ticketing segura?
A API lida com dados sensíveis e transações económicas. A segurança não é negociável.
- OAuth 2.0: padrão moderno para autenticação
- API keys com scopes: permissões granulares por key
- Rotação de credenciais: possibilidade de rotação sem downtime
- Rate limiting: proteção contra abusos, com limites documentados
- Logs de acesso: auditoria de quem acede a quê
O enquadramento base é a RFC 6749, que define o OAuth 2.0 Authorization Framework. Mas o que convém levar à reunião técnica é a RFC 9700, *Best Current Practice for OAuth 2.0 Security*, publicada em 2025. Três das suas exigências verificam-se numa tarde:
- Os servidores de autorização devem suportar PKCE, e os clientes públicos devem utilizá-lo. É a proteção contra o roubo do código de autorização.
- A validação do *redirect URI* deve ser feita por comparação exata de strings, com a única exceção das portas variáveis em
localhostpara aplicações nativas. Qualquer correspondência por padrão é uma porta aberta. - Os tokens de acesso deveriam estar ligados ao emissor através de mTLS ou DPoP, para que um token roubado não funcione noutras mãos.
Se o fornecedor apenas oferece uma API key estática e eterna, não está descartado, mas o contrato deve cobrir o que essa decisão implica: scopes reais, rotação sem cortar o serviço e registo de acessos que possas exportar.
Que endpoints essenciais deve cobrir a API?
Verifica que a API cobre todas as operações de que precisas.
- Eventos: criar, editar, listar, gerir estados
- Bilhetes: tipos, preços, disponibilidade, reservas
- Encomendas: criar, consultar, cancelar, reembolsar
- Validação: verificar bilhetes, registar acessos
- Webhooks: notificações de eventos (venda, acesso, etc.)
Há uma pergunta que decide mais do que a lista anterior: o que acontece se o mesmo pedido chegar duas vezes. No ticketing, uma nova tentativa de rede sobre a criação de uma encomenda pode duplicar uma venda e bloquear uma capacidade que não existe. A resposta correta é uma chave de idempotência por operação de escrita, de forma que a segunda tentativa devolva o resultado da primeira em vez de criar um pedido novo. Pergunta isto por escrito e pede para ver o comportamento em sandbox.
A segunda pergunta é a paginação e os limites de leitura. Uma API que não documenta quantas encomendas devolve por página nem como se percorre o histórico transforma qualquer exportação noturna para o teu dashboard de métricas num problema de engenharia próprio.
Para que servem os webhooks numa integração?
Os webhooks são críticos para manter o teu sistema sincronizado sem polling constante.
- Eventos disponíveis: que ações disparam webhooks
- Payload documentado: estrutura clara de cada tipo de evento
- Tentativas de reenvio: o que acontece se o teu endpoint falhar
- Verificação de assinatura: para validar que o webhook é autêntico
- Logs: histórico de webhooks enviados e o seu estado
Como se verifica uma assinatura
O procedimento melhor documentado do setor é o da Stripe, e serve de padrão mesmo que o teu fornecedor seja outro. A sua documentação de webhooks descreve um cabeçalho Stripe-Signature com uma marca temporal com o prefixo t= e uma ou várias assinaturas com prefixo de esquema; o único esquema válido em produção é v1. A assinatura calcula-se como um HMAC com SHA-256 sobre a cadeia formada pela marca temporal, um ponto e o corpo JSON exato do pedido, usando o segredo do endpoint como chave.
Três detalhes que quebram integrações reais. Primeiro: é preciso usar o corpo em bruto; se a tua framework reserializar o JSON, a verificação falha sempre. Segundo: a comparação deve ser feita em tempo constante, para não vazar informação através do tempo de resposta. Terceiro: as bibliotecas oficiais aplicam uma tolerância predefinida de 5 minutos entre a marca temporal e a hora atual, e a própria documentação adverte para não a colocar a zero, porque isso desativa a verificação de frescura e reabre o ataque de repetição.
Tentativas de reenvio, duplicados e ordem
Os números concretos importam ao dimensionar a tua fila. A Stripe documenta tentativas automáticas de reenvio durante um máximo de três dias com recuo exponencial em modo produção, e três tentativas em algumas horas em sandbox. O reenvio manual funciona até 15 dias a partir do painel e até 30 dias a partir da CLI. Podem registar-se até 16 endpoints de webhook.
E dois avisos que convém copiar tal e qual para o teu design: não se garante a ordem de entrega dos eventos, e um endpoint pode receber o mesmo evento mais do que uma vez. A recomendação oficial é registar os identificadores de evento já processados e não usar a marca de criação para deduzir a ordem. Além disso, o endpoint deve devolver um 2xx antes da lógica pesada: qualquer resposta 3xx é considerada falha de entrega, e um *timeout* dispara o ciclo de tentativas de reenvio.
Como deve a API tratar os erros e os limites de utilização?
Com formatos padronizados, não com strings inventadas. A RFC 9457, *Problem Details for HTTP APIs*, publicada em 2023, define um corpo de erro legível por máquina com cinco campos: type (URI que identifica o tipo de problema), title, status, detail e instance, servido como application/problem+json. Uma API que o usa poupa-te a escrever um tradutor de erros para cada fornecedor.
Para os limites de utilização, a referência é a RFC 6585, *Additional HTTP Status Codes*, de abril de 2012, que introduziu o código 429 Too Many Requests. A própria especificação diz que a resposta deveria incluir detalhes que expliquem a condição e pode incluir um cabeçalho Retry-After a indicar quanto tempo esperar. Esse cabeçalho é a diferença entre uma nova tentativa com critério e um ciclo que agrava a saturação.
Pergunta na avaliação que limites aplica a API por minuto e por chave, se são diferentes em leitura e escrita, e o que acontece nos picos de um lançamento de vendas, que é precisamente o momento em que a tua integração mais é chamada. Uma plataforma que não publica os seus limites está a pedir-te que os descubras no pior dia possível.
Porque preciso de um ambiente de testes (sandbox)?
Desenvolver contra a produção é uma receita para o desastre. Exige um sandbox adequado.
- Ambiente sandbox separado: dados de teste sem afetar a produção
- Cartões de teste: para simular pagamentos sem cobranças reais
- Dados de exemplo: eventos e bilhetes pré-carregados para testar
- Paridade com a produção: mesmo comportamento, mesmas respostas
Acrescenta um teste que quase ninguém faz na avaliação: forçar os erros. Um sandbox útil permite simular um pagamento rejeitado, um reembolso parcial, uma autenticação do banco que o comprador abandona e um webhook que chega tarde. Se só conseguires testar o caminho feliz, não testaste nada.
O relógio também conta. Verifica que o sandbox permite avançar a data de um evento para testar o encerramento de vendas, a validação à porta e a geração de relatórios posteriores sem esperar semanas.
Que obrigações legais acarreta a integração?
Duas frentes, e nenhuma é opcional na União Europeia.
A primeira são os pagamentos. O Regulamento Delegado (UE) 2018/389 exige, no seu artigo 4.º, que a autenticação se baseie em dois ou mais elementos das categorias conhecimento, posse e inerência, e, no seu artigo 5.º, a associação dinâmica: o código gerado deve ser específico para o montante e o beneficiário aceites pelo ordenante. O seu artigo 16.º prevê a isenção de baixo valor: operações até 30 EUR, com um acumulado prévio que não exceda 100 EUR ou um máximo de cinco operações remotas consecutivas. A tua integração tem de saber devolver o comprador ao fluxo após uma autenticação, e isso testa-se em sandbox, não na noite do lançamento das vendas. Se venderes em Espanha, convém cruzar isto com os métodos de pagamento disponíveis.
A segunda são os dados. O Regulamento (UE) 2016/679 obriga, no seu artigo 32.º, a aplicar medidas técnicas e organizativas adequadas, incluindo a cifragem e a capacidade de garantir confidencialidade e integridade, e, no seu artigo 33.º, a notificar as violações de segurança à autoridade de controlo sem demora injustificada e, se possível, num prazo máximo de 72 horas. A API que te entrega e-mails e telefones de participantes transforma-te em responsável pelo que fizeres com eles: o contrato de subcontratante assina-se antes da primeira chamada, não depois. O detalhe operacional está no nosso guia de RGPD para organizadores.
Como se versiona e se depreca uma API sem quebrar a tua integração?
Com regras públicas. O versionamento semântico 2.0.0 reserva o incremento de versão principal para as alterações incompatíveis com versões anteriores, o menor para funcionalidade compatível e o de patch para correções. Aplicado a uma API, significa que uma alteração que quebra o teu cliente não pode chegar num deployment silencioso de uma terça-feira.
Para o fim de vida existe um cabeçalho padrão. A RFC 8594, de maio de 2019, define o campo de resposta HTTP Sunset com uma única marca temporal que indica quando é provável que o recurso deixe de responder, e um tipo de relação de link sunset para apontar para a política de retirada ou migração. Perguntar se a API o emite é uma forma rápida de saber se o fornecedor pensou no ciclo de vida ou só no lançamento.
O mesmo vale para o widget de venda incorporado: se o seu JavaScript for servido a partir de um URL sem versão, qualquer alteração do fornecedor chega ao teu site sem aviso.
Que suporte técnico deve oferecer o fornecedor?
Quando algo falha às 2 da madrugada antes do teu evento, precisas de respostas rápidas.
- Canal técnico: acesso a desenvolvedores, não apenas a suporte genérico
- SLA documentado: tempos de resposta assumidos
- Comunidade: fórum ou Slack onde esclarecer dúvidas
- Onboarding técnico: sessão de integração guiada
Exige que o SLA indique três coisas com números: tempo de primeira resposta por severidade, janela horária coberta e o que acontece se for incumprido. Um compromisso sem consequência é uma declaração de intenções. E pergunta pela janela de alterações: uma plataforma que faz deployment em produção numa sexta-feira de lançamento de vendas tem um problema de processo, não de tecnologia.
Como escolho a API de ticketing correta?
Uma boa API de ticketing acelera o teu desenvolvimento, reduz bugs e permite-te construir experiências personalizadas. É também a base para integrar um widget de venda incorporado no teu próprio site ou ligar o teu dashboard de métricas. Uma má API prende-te em limitações que descobres demasiado tarde. Investe tempo a avaliar antes de te comprometeres: pede acesso ao sandbox, testa os endpoints críticos e fala com a equipa técnica. A decisão correta vai poupar-te meses de frustração.
Nove verificações concretas para essa avaliação:
- Pede o ficheiro OpenAPI, não a documentação em HTML. Se não existir, gera tu o cliente e soma-o ao custo do projeto.
- Exige PKCE e validação exata do redirect URI se houver OAuth 2.0, tal como pede a RFC 9700.
- Testa a idempotência: lança duas vezes a mesma criação de encomenda e verifica que só se cria uma.
- Verifica uma assinatura de webhook à mão antes de confiar na biblioteca, e define uma tolerância temporal diferente de zero.
- Faz falhar o teu endpoint de propósito e mede quantas tentativas de reenvio chegam, durante quanto tempo e com que cabeçalhos.
- Duplica um webhook e verifica que o teu sistema não vende duas vezes o mesmo bilhete.
- Pergunta os limites de utilização por chave e se a API devolve
429comRetry-After. - Verifica o formato de erro:
application/problem+jsoncomtype,title,status,detaileinstancepoupa semanas. - Pergunta pelo cabeçalho Sunset e pela política de versionamento antes de assinar, não quando chegar o aviso.
Fontes
- OpenAPI Specification v3.1.0, 15 de fevereiro de 2021 (OpenAPI Initiative)
- OpenAPI/Swagger Specification (SmartBear, Swagger)
- OAuth 2.0, página oficial do padrão
- RFC 6749: The OAuth 2.0 Authorization Framework (IETF)
- RFC 9700: Best Current Practice for OAuth 2.0 Security (IETF, 2025)
- RFC 9457: Problem Details for HTTP APIs (IETF, 2023)
- RFC 6585: Additional HTTP Status Codes, abril de 2012 (IETF)
- RFC 8594: The Sunset HTTP Header Field, maio de 2019 (IETF)
- Semantic Versioning 2.0.0, especificação em espanhol
- Receive Stripe events in your webhook endpoint, documentação oficial da Stripe
- Regulamento Delegado (UE) 2018/389, normas técnicas de regulamentação para a autenticação reforçada de clientes (EUR-Lex)
- Regulamento (UE) 2016/679, Regulamento Geral sobre a Proteção de Dados (EUR-Lex)