Ir al contenido

BookingNew

POST {base_url}/1.0/bookings

Crea la reserva real. Último paso del flujo 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 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.

{
"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.

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.

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.

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.

  • 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 CONFIRMED es 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.

La API no proporciona claves de idempotencia. Si recibes un timeout o 5xx después de BookingNew:

  1. No reintentes a ciegas — la reserva puede haberse creado.
  2. Espera ~10 segundos.
  3. Si tienes el bookingId numérico, llama a GET /1.0/bookings/{bookingId}. La API no permite localizar una reserva por clientReference: no sustituye a bookingId y GET /1.0/bookings?clientReference=... no es una ruta disponible.
  4. Si no tienes el bookingId, contacta a PT con tu clientReference, el timestamp del intento en UTC y el eventId si está disponible. PT puede localizar la reserva internamente mediante clientReference. No reinicies el flujo de reserva mientras siga sin resolverse el resultado anterior.