Pular para o conteúdo

BookingNew

POST {base_url}/1.0/bookings

Cria a reserva real. Último passo do fluxo de reserva.

Header Valor
Authorization Bearer <access_token>
Content-Type application/json
Accept application/json
{
"bookingKey": "<bookingKey from /bookings/hold>",
"clientReference": "99999",
"client": {
"name": "Jane",
"surname": "Doe",
"contactData": [
{
"email": "jane.doe@example.com",
"phone": {
"countryCode": "+52",
"number": "5512312322"
}
}
]
},
"commentsForHotel": "Special requests..."
}
Campo Obrigatório Tipo Notas
bookingKey Yes string Do BookingHold (≤ 5 min atrás)
clientReference Yes string Referência do parceiro. Não permite localizar uma reserva pela API.
client.name Yes string A-Z, a-z, 0-9. UTF-8
client.surname Yes string A-Z, a-z, 0-9. UTF-8
client.contactData[].email No string Recomendado
client.contactData[].phone.countryCode No string P. ex. +52
client.contactData[].phone.number No string Apenas dígitos
commentsForHotel No string Solicitações de formato livre para o hotel

Em uma amostra na qual client havia sido enviado no BookingHold, uma requisição do BookingNew sem client foi aceita (HTTP 200). Ver Guest data in the hold.

{
"confirmation": {
"bookingId": 21198221,
"clientReference": "99999",
"amount": 116.00,
"currency": "USD",
"cancellationPolicies": [
{
"startDate": "2027-05-12T00:00:00Z",
"endDate": "2027-05-15T23:59:59Z",
"amount": 116.00,
"currency": "USD"
}
],
"oldAmount": 116.00,
"status": "CONFIRMED"
},
"eventId": "f4901c59-33eb-4069-97fb-efe85bf891cd"
}

Uma resposta bem-sucedida do BookingNew pode omitir a propriedade error; não a exija.

Status Significado
CONFIRMED A PT aceitou a reserva e se responsabiliza por ela perante o parceiro.
CREATED A reserva está registrada, mas não está CONFIRMED. Não a trate como uma reserva confirmada.
CANCELLED A reserva falhou e os recursos foram liberados

O número de confirmação do hotel ficará disponível posteriormente em hotels[].confirmationCode, por meio do BookingGet. Enquanto não estiver disponível, o campo vem vazio. Não é enviada uma notificação; o parceiro deve consultar o BookingGet para obtê-lo.

Pode estar presente mesmo quando não houve mudança de preço entre o Hold e o BookingNew; nesse caso, é igual a amount. Quando houve mudança de preço, mostra o valor cotado original frente ao amount atual cobrado. Sempre compare oldAmount com amount para detectar variações.

Código HTTP Mensagem Causa O que fazer
1101 500 The provided key has already been used previously. bookingKey já utilizado Não obtenha uma nova key para reiniciar o fluxo — ver abaixo
5001 500 Invalid Policy Interno Contate a PriceTravel com a requisição, a resposta e o eventId
6001 400 Invalid New Request, can not parse the BookingKey bookingKey corrompido, expirado ou vazio Envie o bookingKey do BookingHold completo e sem alterações
6002 400 You cannot use the 'New' operation if more than 20 minutes have passed since obtaining the BookingKey from 'Hold'. Não definida. O BookingNew retornou este código com esta mensagem; a condição que o dispara não está definida. Obtenha um novo bookingKey com o BookingHold. Não use o código nem o número na mensagem para distinguir a causa.
7001 400 A valid client data was not provided name, surname ou contactData ausentes/inválidos Envie name, surname e contactData com valores válidos
7002 400 A valid credit card was not provided Não há um cartão de crédito válido no objeto Payment O objeto Payment está obsoleto: não o envie

1101 — The provided key has already been used previously. Foi observado que reutilizar um bookingKey após um BookingNew bem-sucedido retorna 1101 sem criar uma segunda reserva e sem retornar o bookingId original. A tentativa anterior provavelmente foi processada, mas um 1101 por si só não comprova que exista uma reserva. Não obtenha uma nova chave para reiniciar o fluxo. Entre em contato com a PT informando clientReference, o timestamp da tentativa em UTC e eventId, se disponível.

Não trate o eventId como um identificador único por requisição: ele pode se repetir entre retentativas da mesma reserva. Guarde o timestamp de cada tentativa junto com seu eventId.

  • O bookingKey deve ter menos de 5 minutos.
  • Uma vez status: CONFIRMED, você não pode modificar a reserva — apenas cancelar e recriar.
  • Uma resposta CONFIRMED é vinculante; o channel será cobrado.
  • Todas as reservas são pagas a crédito: seja sua linha de crédito ou seu saldo pré-pago com a PriceTravel. Não envie dados de cartão em nenhuma requisição.
  • Não repita após um timeout ou 5xx até que o resultado anterior seja resolvido — ver a estratégia de retentativa abaixo.

A API não fornece chaves de idempotência. Se você receber um timeout ou 5xx após o BookingNew:

  1. Não repita às cegas — a reserva pode ter sido criada.
  2. Aguarde ~10 segundos.
  3. Se você tiver o bookingId numérico, chame GET /1.0/bookings/{bookingId}. A API não permite localizar uma reserva por clientReference: ele não substitui o bookingId, e GET /1.0/bookings?clientReference=... não é uma rota disponível.
  4. Se você não tiver o bookingId, entre em contato com a PT informando seu clientReference, o timestamp da tentativa em UTC e o eventId, se disponível. A PT pode localizar a reserva internamente pelo clientReference. Não reinicie o fluxo de reserva enquanto o resultado anterior permanecer indefinido.