Integre seu sistema à Loukon

Duas formas, que se completam: webhooks (a Loukon avisa seu sistema a cada reserva paga ou cancelada) e a API REST (seu sistema consulta reservas, faz check-in e publica vagas).

Acesso

A documentação é aberta. Usar a API exige três coisas, conferidas a cada chamada:

  1. ser parceiro aprovado da Loukon;
  2. ter o Loukon Conecta ativo;
  3. ter a API liberada pela equipe da Loukon (peça no console).

Se qualquer uma deixar de valer, as chaves param de funcionar na hora. Revogada a liberação, todas as chaves são revogadas.

Autenticação

O dono da conta cria as chaves no console (login com verificação em 2 etapas). A chave aparece uma única vez; a Loukon guarda só um resumo criptográfico dela. Escopos: read (consultas) e write (check-in e vagas).

curl https://hml-developers.loukon.com/v1/me \
  -H "Authorization: Bearer lk_live_…"

Use a chave só do seu servidor. Nunca em página web, app de celular ou repositório de código. Vazou? Revogue no console e crie outra.

Limites e erros

120 chamadas por minuto por chave. Erros sempre no formato:

{ "error": { "code": "rate_limited", "message": "…" } }
401 invalid_keychave ausente, errada ou revogada
403 not_allowedAPI não liberada, parceiro inativo ou Conecta desligado
403 missing_scopechave sem write numa escrita
400 / 404 / 413pedido inválido, não encontrado, corpo grande demais
429 rate_limitedespere o próximo minuto
500 internalerro nosso; pode tentar de novo

Endpoints

Base: https://hml-developers.loukon.com/v1. JSON em UTF-8, datas em ISO 8601, valores em centavos (BRL).

GET /me

Testa a chave: parceiro e escopos.

GET /bookings

Reservas pagas pela data do passeio (horário de Brasília). Parâmetros: from e to (AAAA-MM-DD, até 92 dias; padrão: hoje), status (confirmed, completed, cancelled), page (100 por página).

{
  "data": [{
    "code": "LK7Q2M", "status": "confirmed", "starts_at": "2026-12-05T12:00:00+00:00", "created_at": "…",
    "product": { "id": "…", "title": "Passeio de barco", "option_id": "…", "option": "Saída 09h" },
    "pax": 2, "participants": { "adult": 2 }, "you_receive_cents": 36000,
    "traveler": { "name": "Maria Silva", "phone": "+55 11 98888-7777" },
    "answers": {}, "checked_in_at": null, "no_show": false
  }],
  "page": 1, "per_page": 100, "total": 1
}

Do viajante a API devolve só nome e telefone. Documento e demais dados do titular chegam no webhook de reserva, quando o seu sistema precisa emitir o ingresso.

GET /bookings/{code}

Uma reserva pelo código do voucher.

POST /bookings/{code}/check-in write

Marca o embarque. Repetir não altera o horário do primeiro check-in. 404 se o voucher não for seu ou não estiver confirmado.

GET /products

Suas atividades, com as opções (option_id) e o NET por tipo de participante.

PUT /availability write

Cria ou ajusta horários de até 200 opções por chamada. capacity: 0 fecha o horário; nunca abaixo do que já foi vendido. A resposta vem item a item: um erro não derruba os outros.

curl -X PUT https://hml-developers.loukon.com/v1/availability \
  -H "Authorization: Bearer lk_live_…" -H "Content-Type: application/json" \
  -d '{ "items": [ { "option_id": "…", "starts_at": "2026-12-05T09:00:00-03:00", "capacity": 20 } ] }'

{ "results": [ { "option_id": "…", "starts_at": "…", "capacity": 20, "ok": true } ] }

Se a agenda da opção já vem de um sistema integrado pelo Conecta (sincronização automática), a próxima sincronização prevalece.

Webhooks de reserva (Loukon → você)

Configure a URL (HTTPS) e gere a chave de assinatura no painel do Conecta, que tem também o botão de teste. Eventos:

POST https://seu-sistema/webhook
X-Loukon-Event: booking.confirmed
X-Loukon-Delivery: <id da entrega>
X-Loukon-Signature: sha256=<HMAC-SHA256 do corpo com a sua chave, em hex>

{ "event": "booking.confirmed", "event_id": "…", "timestamp": "…",
  "booking": { "code": "LK7Q2M", "status": "confirmed",
    "product": { "id": "…", "option_id": "…", "external_id": "seu código", "title": "…", "option": "…", "meeting_point": "…" },
    "schedule": { "starts_at": "…", "date": "2026-12-05", "time": "09:00" },
    "pax": 2, "participants": { "adult": 2 }, "net_cents": 36000,
    "holder": { "name": "…", "email": "…", "phone": "…", "doc_type": "CPF", "doc_number": "…", "birth_date": "…" },
    "answers": {} } }
// Node: confira antes de processar (compare em tempo constante)
const sig = "sha256=" + crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(req.headers["x-loukon-signature"]));

Use o event_id para não processar o mesmo evento duas vezes. Sem 2xx em 10 segundos, a Loukon tenta de novo (até 8 vezes, com espera crescente até 1 hora); depois, a entrega fica para você reenviar no Conecta. Na troca de chave, a anterior assina junto por 48 horas em X-Loukon-Signature-Previous.

Webhook de entrada (você → Loukon)

Para avisar cancelamento, ingresso emitido ou data fechada sem esperar a Loukon perguntar. A URL, com o id da sua integração, está no painel do Conecta: https://hml.loukon.com/api/webhooks/conecta/<id>.

X-Loukon-Timestamp: <segundos desde 1970>   (até 5 minutos de diferença)
X-Loukon-Signature: sha256=<HMAC-SHA256 de "<timestamp>.<corpo>" com a sua chave, em hex>

{ "event": "booking.ticket", "event_id": "único por evento",
  "data": { "booking_code": "LK7Q2M", "operator_reservation_id": "…", "ticket_url": "https://…" } }

Respostas: 2xx processado (o mesmo event_id não roda duas vezes), 401 assinatura, 4xx corpo inválido, 5xx tente de novo. Corpo até 64 KB.

Segurança