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:
- ser parceiro aprovado da Loukon;
- ter o Loukon Conecta ativo;
- 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_key | chave ausente, errada ou revogada |
403 not_allowed | API não liberada, parceiro inativo ou Conecta desligado |
403 missing_scope | chave sem write numa escrita |
| 400 / 404 / 413 | pedido inválido, não encontrado, corpo grande demais |
429 rate_limited | espere o próximo minuto |
500 internal | erro 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:
booking.confirmed: reserva paga. Responda 2xx; se quiser, comoperator_reservation_ideticket_url(HTTPS), que vão para o voucher do viajante.booking.cancelled: cancelada depois de entregue (trazreasone o seuoperator_reservation_id).
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://…" } }booking.cancelled:{ booking_code, reason }booking.ticket:{ booking_code, operator_reservation_id?, ticket_url? }availability.closed:{ product_id, starts_at, ends_at? }
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
- Só HTTPS. A API não responde a navegadores de outros sites (sem CORS): chame do seu servidor.
- Chaves com escopo mínimo: crie uma só de leitura para relatórios.
- A Loukon só envia webhooks para endereços públicos (bloqueia rede interna) e não segue redirecionamentos.
- Criação e revogação de chaves exigem verificação em 2 etapas e ficam registradas.
- Achou uma falha de segurança? Escreva para seguranca@loukon.com.br.