BookingNew
Endpoint
Sección titulada «Endpoint»POST {base_url}/1.0/bookingsCrea la reserva real. Último paso del flujo de reserva.
Headers
Sección titulada «Headers»| Header | Valor |
|---|---|
Authorization |
Bearer <access_token> |
Content-Type |
application/json |
Accept |
application/json |
Cuerpo de la petición
Sección titulada «Cuerpo de la petición»{ "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 del body
Sección titulada «Campos del body»| Campo | Requerido | Tipo | Notas |
|---|---|---|---|
bookingKey |
Yes | string | De BookingHold (≤ 5 min de antigüedad) |
clientReference |
Yes | string | Referencia del partner. No permite localizar una reserva mediante la 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. ej. +52 |
client.contactData[].phone.number |
No | string | Solo dígitos |
commentsForHotel |
No | string | Peticiones de formato libre para el hotel |
En una muestra en la que se había enviado client en BookingHold, se aceptó una petición de BookingNew sin client (HTTP 200). Ver Guest data in the hold.
Respuesta (éxito — CONFIRMED)
Sección titulada «Respuesta (éxito — 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"}Una respuesta exitosa de BookingNew puede omitir la propiedad error; no la exijas.
Valores de status
Sección titulada «Valores de status»| Status | Significado |
|---|---|
CONFIRMED |
PT aceptó la reserva y responde por ella ante el partner. |
CREATED |
La reserva está registrada, pero no está CONFIRMED. No la trates como una reserva confirmada. |
CANCELLED |
La reserva falló y los recursos se liberaron |
El número de confirmación del hotel estará disponible después en hotels[].confirmationCode mediante BookingGet. Mientras no esté disponible, el campo viene vacío. No se envía una notificación; el partner debe consultar BookingGet para obtenerlo.
Campo oldAmount
Sección titulada «Campo oldAmount»Puede venir aunque no haya habido cambio de precio entre Hold y BookingNew; en ese caso es igual a amount. Cuando hubo un cambio de precio, muestra el monto cotizado original frente al amount actual cobrado. Siempre compara oldAmount con amount para detectar variaciones.
Errores específicos de este endpoint
Sección titulada «Errores específicos de este endpoint»| Código | HTTP | Mensaje | Causa | Qué hacer |
|---|---|---|---|---|
| 1101 | 500 | The provided key has already been used previously. | bookingKey ya utilizado | No obtengas una key nueva para reiniciar el flujo — ver abajo |
| 5001 | 500 | Invalid Policy | Interno | Contacta a PriceTravel con el request, el response y el eventId |
| 6001 | 400 | Invalid New Request, can not parse the BookingKey | bookingKey corrupto, expirado o vacío | Envía el bookingKey de BookingHold completo y sin modificar |
| 6002 | 400 | You cannot use the 'New' operation if more than 20 minutes have passed since obtaining the BookingKey from 'Hold'. |
No definida. BookingNew devolvió este código con este mensaje; la condición que lo dispara no está definida. | Obtén un bookingKey nuevo con BookingHold. No uses el código ni el número del mensaje para distinguir la causa. |
| 7001 | 400 | A valid client data was not provided | name, surname o contactData faltantes/inválidos | Envía name, surname y contactData con valores válidos |
| 7002 | 400 | A valid credit card was not provided | No hay una tarjeta de crédito válida en el objeto Payment |
El objeto Payment está deprecado: no lo envíes |
1101 — The provided key has already been used previously. Se ha observado que reutilizar un bookingKey después de un BookingNew exitoso devuelve 1101 sin crear una segunda reserva y sin devolver el bookingId original. El intento anterior probablemente se procesó, pero un 1101 por sí solo no demuestra que exista una reserva. No obtengas una clave nueva para reiniciar el flujo. Contacta a PT con clientReference, el timestamp del intento en UTC y eventId si está disponible.
No trates eventId como un identificador único por petición: puede repetirse entre reintentos de la misma reserva. Conserva el timestamp de cada intento junto con su eventId.
Reglas críticas
Sección titulada «Reglas críticas»- El bookingKey debe tener menos de 5 minutos de antigüedad.
- Una vez
status: CONFIRMED, no puedes modificar la reserva — solo cancelar y volver a crear. - Una respuesta
CONFIRMEDes vinculante; se cobrará al channel. - Todas las reservas se pagan a crédito: ya sea tu línea de crédito o tu saldo prepagado con PriceTravel. No envíes datos de tarjeta en ninguna petición.
- No reintentes tras un timeout o 5xx hasta que se resuelva el resultado anterior — ver la estrategia de reintento más abajo.
Estrategia de idempotencia / reintento
Sección titulada «Estrategia de idempotencia / reintento»La API no proporciona claves de idempotencia. Si recibes un timeout o 5xx después de BookingNew:
- No reintentes a ciegas — la reserva puede haberse creado.
- Espera ~10 segundos.
- Si tienes el
bookingIdnumérico, llama aGET /1.0/bookings/{bookingId}. La API no permite localizar una reserva porclientReference: no sustituye abookingIdyGET /1.0/bookings?clientReference=...no es una ruta disponible. - Si no tienes el
bookingId, contacta a PT con tuclientReference, el timestamp del intento en UTC y eleventIdsi está disponible. PT puede localizar la reserva internamente medianteclientReference. No reinicies el flujo de reserva mientras siga sin resolverse el resultado anterior.

