BookingHold
Endpoint
Seção intitulada “Endpoint”POST {base_url}/1.0/bookings/holdBloqueia um quarto e uma tarifa específicos por 5 minutos para dar tempo de confirmar.
Headers
Seção intitulada “Headers”| Header | Valor |
|---|---|
Authorization |
Bearer <access_token> |
Content-Type |
application/json |
Accept |
application/json |
Corpo da requisição
Seção intitulada “Corpo da requisição”{ "rateKey": "<rateKey from /hotels/checkrates>"}| Campo | Tipo | Descrição |
|---|---|---|
rateKey |
string | Ver o aviso acima sobre a origem do rateKey |
client |
object | Opcional. Titular da reserva |
client.name |
string | Nome |
client.surname |
string | Sobrenome |
client.contactData[].email |
string | |
client.contactData[].phone.countryCode |
string | Código de país |
client.contactData[].phone.number |
string | Número de telefone |
roomCriteria[] |
array | Opcional. Uma entrada por quarto |
roomCriteria[].roomId |
int | Número do quarto dentro da cotação, de 1 a N, na ordem em que os quartos foram solicitados no HotelRates — ver Guest data in the hold |
roomCriteria[].paxes[] |
array | Hóspedes do quarto |
roomCriteria[].paxes[].age |
int | Idade do hóspede |
roomCriteria[].paxes[].name |
string | Nome do hóspede |
roomCriteria[].paxes[].surname |
string | Sobrenome do hóspede |
Guest data in the hold
Seção intitulada “Guest data in the hold”O BookingHold aceita, de forma opcional, client e roomCriteria, enviados juntos como no exemplo abaixo. Esse fluxo convive com o atual: client pode continuar sendo enviado no BookingNew, como documenta BookingNew.
- Envie
roomIdde 1 a N na ordem dos quartos do HotelRates, e envie o arrayroomCriterianessa mesma ordem. - Para cada quarto, envie os mesmos hóspedes (quantidade e idades) que foram cotados no HotelRates.
Exemplo de requisição com dois quartos, um deles com um menor:
{ "rateKey": "<rateKey from /hotels/checkrates>", "client": { "name": "Jane", "surname": "Doe", "contactData": [ { "email": "jane.doe@example.com", "phone": { "countryCode": "+52", "number": "5512312322" } } ] }, "roomCriteria": [ { "roomId": 1, "paxes": [ { "age": 30, "name": "Jane", "surname": "Doe" }, { "age": 32, "name": "John", "surname": "Doe" } ] }, { "roomId": 2, "paxes": [ { "age": 41, "name": "Maria", "surname": "Lopez" }, { "age": 10, "name": "Ana", "surname": "Lopez" } ] } ]}Requisição do BookingNew neste fluxo:
{ "bookingKey": "<bookingKey from /bookings/hold>", "clientReference": "99999", "commentsForHotel": "Special requests..."}Observado em uma amostra:
- O BookingNew foi aceito apenas com
bookingKey,clientReferenceecommentsForHotel. - No BookingGet, o
primaryGuestde cada quarto foi o primeiro hóspede desse quarto.
Resposta (sucesso)
Seção intitulada “Resposta (sucesso)”{ "bookingKey": "oDvxthDyTDD9xNd...XYZ=", "eventId": "441542bd-f08e-40ed-81e9-11fbd08b0915", "error": null}| Campo | Tipo | Descrição |
|---|---|---|
bookingKey |
string | Token usado no BookingNew. Válido 5 minutos. |
eventId |
string | ID de rastreamento |
error |
object|null | Detalhes do erro, ou null em caso de sucesso |
Janela de tempo
Seção intitulada “Janela de tempo”O bookingKey expira 5 minutos após a emissão. Após a expiração, o quarto é liberado e você deve reiniciar a partir do CheckRates (ou antes).
Erros específicos deste endpoint
Seção intitulada “Erros específicos deste endpoint”| Código | HTTP | Mensagem | Causa | O que fazer |
|---|---|---|---|---|
| 1101 | 400 | The provided key has already been used previously | rateKey já usado em um Hold | Obtenha um novo rateKey com o CheckRates |
| 4001 | 400 | Invalid Hold Request, can not parse the rateKey | rateKey corrompido, codificado incorretamente ou vazio | Envie o rateKey do CheckRates completo e sem alterações |
| 4002 | 400 | You cannot invoke 'Hold' without first performing a 'CheckRates' |
Hold chamado com o rateKey do Rates em vez do CheckRates |
Use o rateKey retornado pelo CheckRates, não pelo Rates |
| 4003 | 400 | RateKey from CheckRates older than 20 min | O rateKey do CheckRates tem mais de 20 min |
Repita o CheckRates |
| 4008 | 400 | The requested rate is no longer available. |
Não definida. A resposta não indica o motivo. Observado em uma resposta. A requisição de Hold foi enviada menos de 20 segundos após um CheckRates bem-sucedido. 4008 e 4009 retornam a mesma mensagem; a diferença entre eles não está definida. | Solicite um novo rateKey repetindo o Rates e o CheckRates. Não use o código para distinguir a causa. |
| 4009 | 400 | The requested rate is no longer available. |
Não definida. A resposta não indica o motivo. Observado em uma resposta. A requisição de Hold foi enviada menos de 20 segundos após um CheckRates bem-sucedido. 4008 e 4009 retornam a mesma mensagem; a diferença entre eles não está definida. | Solicite um novo rateKey repetindo o Rates e o CheckRates. Não use o código para distinguir a causa. |
Padrões de diagnóstico
Seção intitulada “Padrões de diagnóstico”| Sintoma | Causa provável |
|---|---|
| 4001 com um rateKey de aparência válida | O rateKey contém caracteres não seguros para URL (+, /, =) — verifique se está sendo enviado no body JSON, não como parâmetro de URL |
| 4002 | Chamar o Hold com o rateKey de /rates em vez de /checkrates |
| 1101 ao repetir | O Hold anterior teve sucesso silenciosamente; procure um bookingKey nos seus logs |
Headers opcionais (informativo)
Seção intitulada “Headers opcionais (informativo)”Algumas implementações enviam um header adicional para rastreamento; ele não é validado pela API, mas pode ser útil nos logs:
| Header | Propósito |
|---|---|
CustomerIp |
IP de origem do cliente para analytics |
Este header é opcional. Sua presença não altera o comportamento.

