BookingNew
Endpoint
Seção intitulada “Endpoint”POST {base_url}/1.0/bookingsCria a reserva real. Último passo do fluxo de reserva.
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”{ "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..."}Campos do body
Seção intitulada “Campos do body”| 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.
Resposta (sucesso — CONFIRMED)
Seção intitulada “Resposta (sucesso — CONFIRMED)”{ "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.
Valores de status
Seção intitulada “Valores de status”| 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.
Campo oldAmount
Seção intitulada “Campo oldAmount”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.
Erros específicos deste endpoint
Seção intitulada “Erros específicos deste endpoint”| 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.
Regras críticas
Seção intitulada “Regras críticas”- 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.
Estratégia de idempotência / retentativa
Seção intitulada “Estratégia de idempotência / retentativa”A API não fornece chaves de idempotência. Se você receber um timeout ou 5xx após o BookingNew:
- Não repita às cegas — a reserva pode ter sido criada.
- Aguarde ~10 segundos.
- Se você tiver o
bookingIdnumérico, chameGET /1.0/bookings/{bookingId}. A API não permite localizar uma reserva porclientReference: ele não substitui obookingId, eGET /1.0/bookings?clientReference=...não é uma rota disponível. - Se você não tiver o
bookingId, entre em contato com a PT informando seuclientReference, o timestamp da tentativa em UTC e oeventId, se disponível. A PT pode localizar a reserva internamente peloclientReference. Não reinicie o fluxo de reserva enquanto o resultado anterior permanecer indefinido.

