API da Leange — referência da API

Convenções, em todas as superfícies. Datas de estadia são AAAA-MM-DD no fuso da pousada, e a estadia é semiaberta — check_out não é diária. Dinheiro é inteiro em centavos (*_cents), nunca decimal. Erros seguem RFC 7807 com trace_id — cite-o num chamado e achamos a requisição. Toda escrita aceita Idempotency-Key. O preço nunca é enviado pelo cliente: o servidor calcula e reconfere.

Leange Booking API

Motor de disponibilidade, precificação e contratação de reservas.

https://api.bookingmax.online — 'producao/homologacao — e por aqui que se integra'

http://localhost:8080 — dev local

Contrato: /docs/openapi.yaml — importe direto no Postman, no Insomnia ou no openapi-generator. É o mesmo arquivo que o servidor implementa, e há teste amarrando os dois nos dois sentidos: rota documentada sem implementação reprova, e rota implementada sem documentação também.

catalogo

Unidades e categorias de quarto

Método	Rota	O que faz	Parâmetros
GET	/v1/properties	Lista as unidades da pousada.
GET	/v1/properties/{propertyId}/room-types	Lista as categorias de quarto de uma unidade.	propertyId

chat

Atendimento por conversa e o encaminhamento para o WhatsApp

Método	Rota	O que faz	Parâmetros
GET	/v1/chat/config	Estado do chat e o link do WhatsApp, antes de qualquer conversa.	property_id
POST	/v1/chat/conversations	Abre a conversa do chat nativo.
POST	/v1/chat/conversations/{conversationId}/close	Encerra a conversa e devolve o encaminhamento para o WhatsApp.	conversationIdX-Chat-Token
GET	/v1/chat/conversations/{conversationId}/messages	Estado da conversa e as mensagens.	conversationIdX-Chat-Token
POST	/v1/chat/conversations/{conversationId}/messages	Manda uma mensagem do hospede.	conversationIdX-Chat-Token

conta

Conta do hospede — OPCIONAL, nunca obrigatoria

Método	Rota	O que faz	Parâmetros
GET	/v1/me/bookings	Reservas do hospede logado.

cotacao

Preco detalhado e explicavel

Método	Rota	O que faz	Parâmetros
POST	/v1/quotes	Cotacao completa e explicavel de uma categoria.	Idempotency-Key

disponibilidade

Calendario e busca por periodo

Método	Rota	O que faz	Parâmetros
GET	/v1/availability/calendar	Calendario dia a dia — a rota do date-picker.	property_idroom_type_idstartendadultschildrenpets
GET	/v1/availability/search	Opcoes disponiveis para um periodo, ja precificadas.	property_idcheck_incheck_outadultschildrenpetspromo_code

funil

Hold, reserva e pagamento

Método	Rota	O que faz	Parâmetros
GET	/pagamento/{paymentId}	Volta do pagador depois de aprovar no PayPal.	paymentId
POST	/v1/bookings	Cria a reserva a partir de um hold — o aceite do contrato.	Idempotency-Key
GET	/v1/bookings/{bookingId}	Consulta uma reserva.	bookingIdaccess_token
POST	/v1/bookings/{bookingId}/payments	Inicia o pagamento (PIX, cartao ou PayPal).	Idempotency-Keyaccess_token
POST	/v1/chat/orcamento	Orcamento a partir de TEXTO LIVRE (chat com IA).
POST	/v1/guests/identify	Diz se o CPF ja tem conta nesta pousada e, quando nao tem, cria uma em silencio.
POST	/v1/holds	Trava o quarto por um TTL curto (default 15 min).	Idempotency-Key
DELETE	/v1/holds/{holdId}	Libera o hold (usuario abandonou o checkout).	holdId
GET	/v1/images/{imageId}	Serve a foto de uma acomodacao.	imageId
POST	/v1/screenings	Roda o crivo de avaliacao dos pets.
POST	/v1/uploads/vaccine-card	Envia a carteirinha de vacinacao do pet.

Leange Partner API

Consulta de preco, alocacao de quarto e reserva, para integradores.

https://api.bookingmax.online — 'producao/homologacao — e por aqui que se integra'

http://localhost:8080 — dev local

Contrato: /docs/openapi-parceiro.yaml — importe direto no Postman, no Insomnia ou no openapi-generator. É o mesmo arquivo que o servidor implementa, e há teste amarrando os dois nos dois sentidos: rota documentada sem implementação reprova, e rota implementada sem documentação também.

1. Como se autenticar

Você assina uma asserção com a sua chave privada e a troca por um token de vida curta. Não existe segredo compartilhado: a sua chave privada nunca sai da sua máquina, e o que guardamos é a metade pública.

# uma vez: gere o par e mande a metade PÚBLICA para a Leange
openssl genpkey -algorithm ed25519 -out leange.key
openssl pkey -in leange.key -pubout -out leange.pub

# a Leange devolve o seu client_id e o kid da chave

A cada token, monte e assine a asserção (validade de até 5 minutos, jti único — ela é de uso único):

cabeçalho: {"alg":"EdDSA","typ":"JWT","kid":"<seu kid>"}
corpo:     {"iss":"<client_id>","sub":"<client_id>",
            "aud":"https://auth.bookingmax.online/token",
            "jti":"<único>","iat":<agora>,"exp":<agora+120>}

curl -s -X POST https://auth.bookingmax.online/token \
  -d grant_type=client_credentials \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  --data-urlencode "client_assertion=<a asserção>" \
  -d resource=leange-booking-partner \
  -d tenant=<slug da pousada>

Três coisas que economizam um dia de integração. jti único por asserção — reapresentar a mesma é recusado, ela é credencial de uso único. exp de no máximo 5 minutos — um exp longo é recusado, porque transformaria a asserção no segredo de vida longa que este desenho evita. E guarde o token enquanto ele vale: pedir um por requisição funciona, mas gasta os dois lados.

2. O `Host` escolhe a pousada

Cada pousada tem o domínio dela, e é o Host da requisição que resolve de quem é o inventário. O tenant que você pediu no token tem de ser o mesmo — divergência responde 404. Não existe pousada padrão.

3. Consultar é uma autoridade; reservar é outra

Catálogo, disponibilidade e preço são leitura. Segurar quarto e reservar são escrita, e dependem de a Leange ter liberado isso para a sua credencial — sem a liberação, a resposta é 403 PARTNER_READ_ONLY dizendo o que fazer. A separação existe porque consultar tarifa é barato e repetível, e segurar quarto tira produto do estoque de quem está comprando agora.

4. O que esperar das respostas

pending_review é venda feita esperando uma conversa — nunca recusa: a pousada é pet-friendly e um pet sem carteira de vacinação vira atendimento humano, não cancelamento. 409 PRICE_CHANGED traz a cotação nova, e a decisão passa a ser do seu cliente. E a reserva nasce pending_payment: o quarto só é vendido quando o pagamento entra, e o hóspede paga pelo link que devolvemos em guest_payment_url.

5. As rotas

alocacao

Segurar o quarto por um prazo

Método	Rota	O que faz	Parâmetros
POST	/v1/partner/holds	Segura o quarto da cotacao por um prazo	Idempotency-Key
DELETE	/v1/partner/holds/{holdId}	Devolve ao estoque o que nao virou reserva	holdId

catalogo

As pousadas e o que elas oferecem

Método	Rota	O que faz	Parâmetros
GET	/v1/partner/properties	Lista as pousadas, com horarios e politicas

disponibilidade

O que esta livre no periodo, com preco

Método	Rota	O que faz	Parâmetros
GET	/v1/partner/availability	O que esta livre no periodo, com preco e extrato	property_idcheck_incheck_outadultschildrenpets

reserva

Contratar e consultar

Método	Rota	O que faz	Parâmetros
POST	/v1/partner/bookings	Contrata a reserva do quarto segurado	Idempotency-Key
GET	/v1/partner/bookings/{codigo}	Estado de uma reserva SUA, pelo codigo	codigo

Gerada do contrato por tools/apidocs a cada publicação — esta página não é escrita à mão e não pode divergir do servidor. Se uma rota não está aqui, ela não está no contrato.

Leange Booking API

catalogo

chat

conta

cotacao

disponibilidade

funil

Leange Partner API

1. Como se autenticar

2. O Host escolhe a pousada

3. Consultar é uma autoridade; reservar é outra

4. O que esperar das respostas

5. As rotas

alocacao

catalogo

disponibilidade

reserva

2. O `Host` escolhe a pousada