Pular para o conteúdo

Fluxo de reserva

1. Token (auth, valid ~1h)
│
▼
2. HotelRates (search, returns rateKey valid 60 min)
│
▼
3. CheckRates (validate rate, returns NEW rateKey valid 20 min)
│
▼
4. BookingHold (block inventory, returns bookingKey valid 5 min)
│
▼
5. BookingNew (confirm reservation, returns bookingId)
│
├─→ BookingGet (retrieve booking details by ID)
└─→ BookingDelete (cancel — wait 90s after creation)
  • Se você receber um timeout ou um erro 5xx do BookingNew, não reinicie o fluxo — ver a estratégia de retentativa em BookingNew.
  • Uma reserva CONFIRMED pode ainda não ter o número de confirmação do hotel; ele ficará disponível posteriormente em hotels[].confirmationCode, por meio do BookingGet — ver BookingNew.
  • client pode ser enviado no BookingNew (fluxo atual) ou, junto com os hóspedes por quarto (roomCriteria), no BookingHold — ver Guest data in the hold.
Passo Entrada Saída TTL
Token client_id + client_secret access_token ~1 hora
Rates hotelIds + dates + paxes rateKey (rates) 60 min
CheckRates rateKey de Rates rateKey (checkrates) 20 min
BookingHold rateKey de CheckRates bookingKey 5 min
BookingNew bookingKey bookingId n/a

O serviço de Rates permite consultar vários quartos simultaneamente. A resposta só retorna tipos de quarto em que o mesmo quarto está disponível para todos os quartos solicitados.

  • Um rateKey por resposta representa o custo total de todos os quartos combinados.
  • Não selecione múltiplos rateKeys para uma reserva multi-quarto — um único rateKey já inclui todos os quartos.

Exemplo: ao solicitar 2 quartos, só são retornados tipos em que há 2 quartos iguais disponíveis; o valor do rateKey = custo dos dois quartos.

A API não suporta modificações de reservas. Para “modificar” uma reserva, você deve:

  1. Cancelar a reserva existente (mínimo 90s após a criação).
  2. Criar uma nova reserva com as alterações desejadas.
  • Máximo de 50 IDs de hotel por chamada a /hotels/rates.
  • Máximo de 28 dias de intervalo de estadia por consulta.
  • Rate limit por channel (HTTP 429 ao exceder).
Erro Sintoma Solução
Pular o CheckRates antes do Hold Erro 4002 em /bookings/hold Sempre chame o CheckRates primeiro
Usar um rateKey vencido (>60 min) Erro 4001 / 4006 / sold_out Busque novamente via /hotels/rates
Chamar Cancel <90s após a reserva Erro 1203 (a reserva ainda está sendo criada) Aguarde ao menos 90 segundos
Reservar com o rateKey de Rates em vez do de CheckRates Erro 4002 no Hold Use o rateKey retornado pelo CheckRates
Cotar >28 dias Erro 3003 Divida em várias consultas
CheckIn no passado Erro 3001 Use a data de hoje ou datas futuras
CheckOut <= CheckIn Erro 3002 CheckOut deve ser estritamente posterior a CheckIn
Quarto sem nenhum adulto Erro 3004 Cada quarto exige ao menos um pax de 18+ anos