Documentação da API — Integração de Parceiro

1. O que você recebe

Antes de começar, a Ticketinho entrega a você:

• Uma chave de API no formato tkt_live_… (mostrada uma única vez).
• A URL base: https://api.ticketinho.com.br
• (Opcional, se usar webhook) um secret whsec_… para validar as notificações.

A chave dá acesso somente aos dados dos seus eventos. Guarde-a com segurança — quem tiver a chave acessa seus pedidos.

2. Autenticação

Envie a chave no cabeçalho Authorization em toda requisição:

Authorization: Bearer tkt_live_SUA_CHAVE_AQUI

Requisições sem chave, ou com chave inválida/revogada, recebem 401.

3. Acompanhar vendas

Opção A — você consulta quando quiser (pull). Faça um GET no endpoint de pedidos:

curl -H "Authorization: Bearer tkt_live_SUA_CHAVE_AQUI" \
  https://api.ticketinho.com.br/api/v1/partner/orders

A resposta traz os pedidos pagos, com valor líquido, cliente e os QR codes:

{
  "orders": [
    {
      "id": "....",
      "created_at": "2026-01-01T20:00:00.000Z",
      "net_amount": 100.00,
      "payment_status": "paid",
      "payment_method": "pix",
      "customer_name": "João Silva",
      "customer_email": "joao@email.com",
      "customer_whatsapp": "(11) 90000-0000",
      "event_id": "....",
      "event_title": "Minha Festa",
      "items": 1,
      "tickets": [
        { "qr_code": "....", "ticket_name": "Pista" }
      ]
    }
  ],
  "limit": 50, "offset": 0, "count": 1
}

Para muitos pedidos, pagine com ?limit=50&offset=50 (máx. 200 por página).

Opção B — a Ticketinho avisa na hora (webhook). Veja a seção 5. Recomendado: use o webhook para reagir em tempo real e o pull para conferência/relatórios.

4. Ler QR codes na portaria / caixa

Modelo recomendado — validação online. Ao escanear o QR, envie:

POST https://api.ticketinho.com.br/api/v1/partner/validate
Authorization: Bearer tkt_live_SUA_CHAVE_AQUI
Content-Type: application/json

{ "qr_code": "VALOR_LIDO_DO_QR" }

Resposta para ingresso válido:

{ "valid": true, "ticket_type": "Pista", "buyer_name": "João", "event_title": "Minha Festa" }

Resposta quando já entrou (proteção contra entrada dupla / QR clonado):

{ "valid": false, "message": "Ingresso já utilizado" }

A Ticketinho é a fonte da verdade: a segunda leitura do mesmo QR é bloqueada, mesmo em catracas ou celulares diferentes.

Modelo alternativo — lista offline. Baixe todos os QRs do evento de uma vez (útil com internet ruim na portaria):

GET https://api.ticketinho.com.br/api/v1/partner/events/ID_DO_EVENTO/tickets

Nesse modelo, o controle de "já usou" fica por conta do seu sistema e não sincroniza em tempo real com a Ticketinho.

Para descobrir o ID_DO_EVENTO, liste seus eventos:

GET https://api.ticketinho.com.br/api/v1/partner/events

Catracas: a integração com catracas é suportada apenas no modo online — a catraca (ou o software de controle de acesso dela) deve chamar o POST /validate a cada leitura de QR. Não trabalhamos com listas de liberação offline (arquivos TXT/CSV importados na catraca).

5. Webhook — receber pedidos automaticamente

Em vez de consultar, você pode receber um aviso a cada pedido pago. Informe à Ticketinho uma URL httpsdo seu sistema; nós enviamos um POST para lá assim que a venda é confirmada.

Corpo enviado:

{
  "event": "order.paid",
  "sent_at": "2026-01-01T20:00:00.000Z",
  "order": {
    "id": "....",
    "net_amount": 100,
    "payment_method": "pix",
    "customer": { "name": "João", "email": "joao@email.com", "whatsapp": "(11) 90000-0000" },
    "tickets": [
      { "qr_code": "....", "ticket_name": "Pista", "event_id": "....", "event_title": "Minha Festa" }
    ]
  }
}

Valide a assinatura. Cada requisição traz o cabeçalho X-Ticketinho-Signature, que é o HMAC-SHA256 do corpo bruto usando o seu secret. Recalcule e compare antes de confiar:

const crypto = require('crypto');

// corpoBruto = o body exatamente como recebido (string)
const assinatura = crypto
  .createHmac('sha256', SEU_SECRET)
  .update(corpoBruto)
  .digest('hex');

if (assinatura !== req.headers['x-ticketinho-signature']) {
  return res.status(401).end(); // descartar: não veio da Ticketinho
}

Evite duplicar. Use o order.id como chave: se já registrou aquele pedido, ignore.

Sem reenvio automático. Se o seu endpoint estiver fora do ar, o aviso é perdido — recupere os pedidos depois pelo GET /orders.

6. Referência dos endpoints

7. Observações importantes

• O valor informado é sempre o líquido (net_amount) — o que você recebe. A taxa de serviço não é exposta.
• Há limite de requisições por hora na leitura (definido pela Ticketinho). A validação na portaria tem limite próprio, bem maior.
• Sua chave acessa apenas os seus eventos. Nenhum dado de outro produtor é acessível.
• Use sempre https. Nunca exponha sua chave ou secret no front-end / em código público.