API do HotelGestão

Ligue o site próprio, o channel manager, um chatbot, o BI ou a sua automação às reservas do hotel — com o mesmo preço e a mesma disponibilidade do balcão, e a trava do banco impedindo reserva dupla entre canais.

REST + JSONOpenAPI 3.1Webhooks com HMAC120 chamadas/min

Referência OpenAPI

Comece em 3 passos

1Gere a chave
O dono do hotel cria em Configurações → Integrações → Canais → API, com leitura e escrita ou somente leitura. A chave aparece uma vez.

2Consulte

Disponibilidade e preço para duas pessoas:

curl "https://app.hotelgestao.com.br/api/v1/availability?checkIn=2026-10-10&checkOut=2026-10-12&guests=2" \
  -H "Authorization: Bearer hg_SUA_CHAVE"

3Reserve

Repetir com a mesma Idempotency-Key devolve a mesma reserva:

curl -X POST "https://app.hotelgestao.com.br/api/v1/reservations" \
  -H "Authorization: Bearer hg_SUA_CHAVE" \
  -H "Idempotency-Key: pedido-000123" \
  -H "Content-Type: application/json" \
  -d '{"roomType":"Standard","checkIn":"2026-10-10",
       "checkOut":"2026-10-12","guests":2,
       "guest":{"name":"Maria Silva","phone":"99988887777"}}'

Endereço base: https://app.hotelgestao.com.br/api/v1 · datas em AAAA-MM-DD no dia do hotel · valores em reais · erros em português, com o campo que causou.

O que dá para fazer

Disponibilidade e preço
O que dá para vender e o total da estadia, por tipo, com temporada aplicada.
Reservas
Listar, criar, alterar observações e cancelar, com trava contra reserva dupla.
Hóspedes
Buscar e cadastrar, sem duplicar quem já existe.
Bloqueios
Fechar e reabrir datas de uma unidade (stop-sell).
Webhooks
Aviso na hora de cada reserva criada, alterada ou cancelada, assinado com HMAC.
Unidades e tipos
Quartos, suítes, chalés, camas: capacidade e diária-base por ocupação.

Para espelhar reservas, guarde o updatedAt mais recente e volte com updatedSince — ou receba por webhook.

Referência completa

Cada rota, parâmetro, corpo e resposta. Toque numa rota para abrir.

Testar com a chave Baixar OpenAPI

Hotel

Dados do estabelecimento e das unidades (quartos, suítes, chalés, camas…).

get/hotelDados do hotel

Respostas

200Hotel
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

get/room-typesTipos de unidade

Cada tipo com quantas unidades tem, a capacidade máxima e a diária-base por número de hóspedes (sem temporada).

Respostas

200Tipos
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

get/roomsUnidades

Parâmetros

typena URL · stringFiltra por tipo.

Respostas

200Unidades
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

get/rooms/{id}Uma unidade

Parâmetros

idno caminho · string · obrigatórioId da unidade.

Respostas

200Unidade
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
404Não existe.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

Disponibilidade e preço

O que dá para vender e por quanto, com as regras do hotel aplicadas.

get/availabilityDisponibilidade e preço de uma estadia

Por tipo: quantas unidades estão livres no período inteiro e o total da estadia para o número de hóspedes (a mais barata livre do tipo).

Parâmetros

checkInna URL · string (date) · obrigatórioEntrada.
checkOutna URL · string (date) · obrigatórioSaída.
guestsna URL · integer · padrão 2Número de hóspedes (padrão 2).

Respostas

200Disponibilidade
400Datas inválidas.
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

get/calendarCalendário por unidade

Dia a dia, se cada unidade está livre, e o que a ocupa. Janela padrão 30 dias; máxima 366.

Parâmetros

fromna URL · string (date)Primeiro dia (padrão: hoje).
tona URL · string (date)Dia seguinte ao último.

Respostas

200Calendário
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

get/ratesDiárias por noite

Diária de cada noite por tipo, para o número de hóspedes, com temporada e dia da semana aplicados.

Parâmetros

fromna URL · string (date)Primeira noite (padrão: hoje).
tona URL · string (date)Dia seguinte à última noite.
guestsna URL · integer · padrão 2Número de hóspedes (padrão 2).

Respostas

200Diárias
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

Reservas

get/reservationsListar reservas

Para sincronizar: guarde o updatedAt mais recente e volte com updatedSince.

Parâmetros

statusna URL · stringUm ou vários, separados por vírgula.
updatedSincena URL · string (date-time)
checkInFromna URL · string (date)Entrada a partir de.
checkInTona URL · string (date)Entrada até (inclusive).
limitna URL · integer · padrão 50
cursorna URL · stringO nextCursor da página anterior.

Respostas

200Reservas
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

post/reservationsCriar reserva

Com roomType, a API escolhe a unidade livre mais barata do tipo que caiba os hóspedes; com roomId, usa exatamente aquela. Sem total, o preço é o da tabela do hotel. Idempotente: repetir com o mesmo cabeçalho Idempotency-Key (ou o mesmo externalId) devolve a mesma reserva com duplicate: true em vez de criar outra. O hóspede é reaproveitado pelo documento, ou pelo telefone + nome.

Parâmetros

Idempotency-Keyheader · string

Corpo (JSON)

roomTypestringTipo (veja /room-types). Obrigatório se não houver roomId.
roomIdstringUnidade exata.
checkInstring (date) · obrigatório
checkOutstring (date) · obrigatório
guestsinteger
guestHospedeEntrada · obrigatório
totalnumberValor acertado no canal. Sem ele, vale a tabela do hotel.
paidnumberQuanto já foi pago no canal.
statusstring
channelstringNome do canal para o relatório (ex.: "Site próprio", "Chatbot").
externalIdstringId da reserva no seu sistema (também torna a criação idempotente).
notesstring

Respostas

200Repetição: a mesma reserva, com duplicate: true
201Criada
400Campo inválido (veja field).
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
403Chave somente leitura.
404roomId/roomType não existe.
409Sem unidade livre no período.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

get/reservations/{id}Uma reserva

Parâmetros

idno caminho · string · obrigatórioId da reserva.

Respostas

200Reserva
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
404Não existe.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

patch/reservations/{id}Alterar reserva

Muda observações, número de hóspedes e contato do hóspede. Datas, unidade e valores mudam no balcão, onde a troca fica registrada no histórico da reserva; pela API, cancele e crie outra.

Parâmetros

idno caminho · string · obrigatórioId da reserva.

Corpo (JSON)

notesstring
guestsinteger
guestobject

Respostas

200Alterada
400Campo não permitido ou inválido.
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
403Chave somente leitura.
404Não existe.
409Reserva cancelada ou encerrada.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

post/reservations/{id}/cancelCancelar reserva

Idempotente. Reserva com check-in feito é cancelada no balcão (409).

Parâmetros

idno caminho · string · obrigatórioId da reserva.

Corpo (JSON)

reasonstring

Respostas

200Cancelada
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
403Chave somente leitura.
404Não existe.
409Check-in já feito.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

Hóspedes

get/guestsListar/buscar hóspedes

Parâmetros

qna URL · stringNome, telefone, e-mail ou documento (mín. 2 caracteres).
limitna URL · integer · padrão 50
cursorna URL · stringO nextCursor da página anterior.

Respostas

200Hóspedes
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

post/guestsCadastrar hóspede

Se já existir (mesmo documento, ou mesmo telefone + nome), devolve o cadastro com duplicate: true.

Corpo (JSON)

namestring · obrigatório
phonestringDDD + número, só dígitos (10 a 13).
emailstring (email)
documentstringCPF, passaporte ou outro documento.

Respostas

200Já existia
201Criado
400Campo inválido.
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
403Chave somente leitura.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

get/guests/{id}Um hóspede

Parâmetros

idno caminho · string · obrigatórioId do hóspede.

Respostas

200Hóspede
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
404Não existe.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

Bloqueios

Fechar datas de uma unidade (stop-sell, manutenção combinada, uso próprio).

put/blocks/{uid}Fechar datas de uma unidade

Idempotente pelo uid que VOCÊ escolhe (ex.: stopsell-natal-101): enviar de novo com outras datas move o bloqueio.

Parâmetros

uidno caminho · string · obrigatório

Corpo (JSON)

roomIdstring · obrigatório
startstring (date) · obrigatório
endstring (date) · obrigatórioDia seguinte à última noite fechada.
reasonstring

Respostas

200Bloqueado
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
403Chave somente leitura.
404roomId não existe.
409Já há reserva no período.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

delete/blocks/{uid}Reabrir datas

Parâmetros

uidno caminho · string · obrigatório

Respostas

200Removido
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
404Não existe.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

Motel

Suítes por período (2h, 3h, pernoite) para totem de autoatendimento, tablet da recepção e integrações. Só para hotel do tipo Motel, com a tabela preenchida em Configurações do Sistema → Motel.

get/suitesSuítes agora, com preço de cada período

Estado de cada suíte (livre, ocupada, excedida, limpeza, manutencao, reservada), quanto falta do período em curso e o preço de cada período para aquele tipo de suíte no momento (fim de semana e data especial já aplicados). É o que o totem mostra na tela.

Respostas

200Suítes
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

post/suites/{id}/staysAbrir entrada numa suíte

Abre a permanência por período. Sem cadastro do hóspede: a placa é opcional. Uma suíte só pode ter uma entrada aberta (o banco recusa a segunda).

Parâmetros

idno caminho · string · obrigatórioId da suíte (roomId).

Corpo (JSON)

periodIdstring · obrigatórioId do período (ex.: 2h, pernoite), como vem em /suites.
platestringPlaca do carro (opcional).
notestring

Respostas

201Entrada aberta
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
403Chave somente leitura.
404Suíte não encontrada.
409Suíte ocupada, em limpeza ou em manutenção.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

get/staysPermanências

Parâmetros

statusna URL · string · padrão abertaaberta (padrão), agendada, fechada ou cancelada.
limitna URL · integer · padrão 50

Respostas

200Permanências
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

get/stays/{id}Uma permanência, com a conta do momento

Parâmetros

idno caminho · string · obrigatórioId da permanência.

Respostas

200Permanência
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
404Não existe.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.

post/stays/{id}/closeFechar a conta da suíte

Calcula período, hora adicional (com tolerância), consumo e desconto, exige que os pagamentos somem o total a pagar, lança no caixa aberto do hotel e devolve a suíte para limpeza.

Parâmetros

idno caminho · string · obrigatórioId da permanência.

Corpo (JSON)

paymentslista de object · obrigatório
discountnumberDesconto em reais sobre o total.

Respostas

200Conta fechada
401Chave ausente, inválida ou revogada.
402O plano do hotel não inclui a API ou está vencido/bloqueado.
403Chave somente leitura.
404Permanência aberta não encontrada.
409Sem caixa aberto no hotel.
423Hotel suspenso pela VisionX.
429Mais de 120 chamadas por minuto nesta chave (veja o cabeçalho retry-after).
500Erro interno — informe o requestId ao suporte.