POST/v1/transfers/book

Reservar un transfer

Crea una reserva a partir de una oferta cotizada.

POST/v1/transfers/book

Consola API

Pruébalo

Envía una petición real al entorno sandbox e inspecciona la respuesta.

Credenciales

Profile code

Public key

Secret key

Inicia sesión para elegir entre tus API keys guardadas en vez de pegarlas.

Cuerpo de la petición

{
  "gdsprovider": 0,
  "bookingToken": "opaque_offer_token_generated_by_travelandz",
  "pricingToken": "opaque_public_pricing_token_generated_by_travelandz",
  "searchId": "73a5670b476649a985f0535db1077c05",
  "resultId": "fe94b51ccd0623a9f1adabfbe0614d34",
  "selectedAmenities": [
    "baby_seats",
    "child_booster"
  ],
  "currency": "USD",
  "email": "happytraveler@example.com",
  "countryCodeName": "US",
  "phoneNumber": "+18775998200",
  "firstName": "Happy",
  "lastName": "Traveler",
  "airline": "AA",
  "flightNumber": "123",
  "customerSpecialInstructions": "My doorbell is broken, please call on arrival",
  "partnerTrackingId": "1234567ABC",
  "extraPaxInfo": [
    {
      "firstName": "Jose",
      "lastName": "Smith"
    }
  ]
}

Petición cURL

cURL

bash

curl -X POST 'https://api.sandbox.travelandz.com/v1/transfers/book' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'X-Travelandz-Id: YOUR_PUBLIC_KEY:YOUR_PROFILE_CODE' \
  -H 'Content-Type: application/json' \
  -d '{"gdsprovider":0,"bookingToken":"opaque_offer_token_generated_by_travelandz","pricingToken":"opaque_public_pricing_token_generated_by_travelandz","searchId":"73a5670b476649a985f0535db1077c05","resultId":"fe94b51ccd0623a9f1adabfbe0614d34","selectedAmenities":["baby_seats","child_booster"],"currency":"USD","email":"happytraveler@example.com","countryCodeName":"US","phoneNumber":"+18775998200","firstName":"Happy","lastName":"Traveler","airline":"AA","flightNumber":"123","customerSpecialInstructions":"My doorbell is broken, please call on arrival","partnerTrackingId":"1234567ABC","extraPaxInfo":[{"firstName":"Jose","lastName":"Smith"}]}'

Añade tus credenciales para enviar una petición.

Esta petición necesita identificadores o tokens de una llamada anterior. Ejecuta primero el paso previo y pega aquí sus valores.

Respuesta

Pulsa «¡Pruébalo!» para enviar una petición y ver la respuesta aquí.

Crea una reserva a partir de una oferta cotizada.

Autenticación y headers

Header	Descripción
`Authorization`	`Bearer <secret_key>`. Conserva el secret en el servidor y nunca lo escribas en logs del cliente.
`X-Travelandz-Id`	`<public_key>:<profile_code>`, donde el profile code persistido usa el formato `dp_<12 alfanuméricos>`.
`LANG`	Header recomendado para el idioma. También se acepta `Accept-Language`.
`Content-Type`	`application/json` para peticiones con body JSON.

Petición

Envía el bookingToken, pricingToken, searchId y resultId que ya tienes, más los datos de contacto del viajero. selectedAmenities y currency deben coincidir con lo que enviaste a pricing.

Cuando la oferta tiene flightInfoRequired: true, airline y flightNumber son obligatorios. Un round trip que requiere datos de vuelo exige también returnAirline y returnFlightNumber. Si envías ticketTypes, la suma de count debe igualar al pasajero principal más la longitud de extraPaxInfo, así que envía también extraPaxInfo — un array vacío para un único viajero.

Schema del body

gdsprovider

enum

0

Sí

Transfer content selector. Currently 0.

bookingToken

stringSí

Copy the bookingToken of the selected offer.

searchId

stringSí

Must be the searchId of the selected offer.

resultId

stringSí

Must be the resultId of the selected offer.

pricingToken

stringSí

Opaque value returned by pricing. Required to book.

selectedAmenities

arraySí

selectedAmenities[]

string[]No

When sent, must match the priced selection exactly.

currency

enum

EURUSDINRCHFJPYGBPAUDCADCNYSGDNZDMXN

Lowercase values are accepted and normalized. Defaults to USD on a new search and is inherited afterwards.

email

string

Formato: email

Sí

countryCodeName

string

Formato: ISO 3166-1 alpha-2

Sí

For example US or ES.

phoneNumber

stringSí

Valid phone number including the country prefix.

firstName

stringSí

lastName

stringSí

customerSpecialInstructions

stringNo

partnerTrackingId

stringSí

Your own correlation identifier for this booking.

airline

string

Formato: IATA (2 characters)

Required when the offer has flightInfoRequired: true. Send it together with flightNumber.

flightNumber

stringNo

Alphanumeric, 1-8 characters, no spaces.

returnAirline

stringNo

Required for a round trip that needs flight details. Send it together with returnFlightNumber.

returnFlightNumber

stringNo

Alphanumeric, 1-8 characters.

extraPaxInfo

arraySí

extraPaxInfo[]firstName

stringSí

extraPaxInfo[]lastName

stringSí

extraPaxInfo[]email

string

Formato: email

extraPaxInfo[]phoneNumber

stringNo

ticketTypes

arraySí

ticketTypes[]id

stringSí

Ticket type identifier from the offer. Must be unique.

ticketTypes[]count

numberSí

Integer of at least 1.

scheduleIndex

numberNo

Index of the chosen alternative time. Must be 0 or greater.

paymentToken

stringNo

Only when the selected offer requires it.

successUrl

string

Formato: URL

Only when the selected offer requires it.

language

enum

en-USes-ESde-DEfr-FRpt-BRzh-CNit-IT

Legacy field. Prefer the LANG or Accept-Language header.

Ejemplo de petición

json

{
  "gdsprovider": 0,
  "bookingToken": "opaque_offer_token_generated_by_travelandz",
  "pricingToken": "opaque_public_pricing_token_generated_by_travelandz",
  "searchId": "73a5670b476649a985f0535db1077c05",
  "resultId": "fe94b51ccd0623a9f1adabfbe0614d34",
  "selectedAmenities": [
    "baby_seats",
    "child_booster"
  ],
  "currency": "USD",
  "email": "happytraveler@example.com",
  "countryCodeName": "US",
  "phoneNumber": "+18775998200",
  "firstName": "Happy",
  "lastName": "Traveler",
  "airline": "AA",
  "flightNumber": "123",
  "customerSpecialInstructions": "My doorbell is broken, please call on arrival",
  "partnerTrackingId": "1234567ABC",
  "extraPaxInfo": [
    {
      "firstName": "Jose",
      "lastName": "Smith"
    }
  ]
}

Respuesta exitosa

El booking responde con HTTP 200 y un campo status en lugar de 201, porque la reserva no siempre queda confirmada de inmediato.

Lee status junto con completed antes de comunicar nada al viajero:

completed con completed: true y al menos una reserva: el transfer está reservado.
pending: todavía no hay respuesta definitiva. Consulta la reserva para saber cómo terminó; no repitas la petición.
failed: la reserva fue rechazada. error explica el motivo.

metadata.detailsIdentifier te indica qué identificador usar al consultar después la reserva.

Schema de respuesta

status

enum

completedpendingfailed

Sí

completed

booleanSí

Treat the operation as confirmed only when this is true and reservations is not empty.

timedOut

booleanSí

True when a final state was not reached in time.

reservations

arraySí

reservations[]gdsprovider

enum

0

Sí

reservations[]reservationId

stringSí

Persist this value; reservation reads and cancellation need it.

reservations[]confirmationNumber

stringNo

Traveller-facing confirmation code.

reservations[]status

enum

completedpendingfailed

Sí

reservations[]cancelled

booleanSí

reservations[]totalAmount

numberSí

Total charged for the reservation.

reservations[]currency

enum

EURUSDINRCHFJPYGBPAUDCADCNYSGDNZDMXN

Sí

reservations[]pickupInstructions

stringNo

reservations[]ticketUrl

string

Formato: URL

reservations[]selectedScheduleIndex

numberNo

reservations[]departureDatetime

string

Formato: ISO 8601

reservations[]arrivalDatetime

string

Formato: ISO 8601

reservations[]selectedAmenities

arraySí

reservations[]selectedAmenities[]key

stringSí

Value to send in selectedAmenities.

reservations[]selectedAmenities[]name

stringSí

Localized name.

reservations[]selectedAmenities[]description

stringNo

reservations[]selectedAmenities[]imageUrl

string

Formato: URL

reservations[]selectedAmenities[]pngImageUrl

string

Formato: URL

reservations[]selectedAmenities[]inputType

enum

booleannumeric

reservations[]selectedAmenities[]included

booleanSí

True when the amenity is already part of the offer.

reservations[]selectedAmenities[]selectable

booleanSí

True when the amenity can be added to this offer.

reservations[]selectedAmenities[]selected

booleanSí

True when the amenity is part of the priced selection.

error

stringNo

Present when status is failed.

metadata

objectSí

metadatauseSearchIdForDetails

booleanSí

True when reservation details must be read with searchId instead of reservationId.

metadatadetailsIdentifier

enum

reservationIdsearchId

Sí

Identifier to use when reading the reservation.

metadatadetailsSearchId

stringNo

Present when detailsIdentifier is searchId.

metadatamessage

stringNo

Ejemplos de respuesta

200 Reservado

json

{
  "status": "completed",
  "completed": true,
  "timedOut": false,
  "reservations": [
    {
      "gdsprovider": 0,
      "reservationId": "f390daff1fdf4cccb19b7abd825dc011",
      "confirmationNumber": "TZ-6202191",
      "status": "completed",
      "cancelled": false,
      "totalAmount": 181.97,
      "currency": "USD",
      "pickupInstructions": "The driver will call you when he arrives.",
      "selectedScheduleIndex": 0,
      "departureDatetime": "2026-08-16T14:40:00-04:00",
      "arrivalDatetime": "2026-08-16T15:06:00-04:00",
      "selectedAmenities": [
        {
          "key": "baby_seats",
          "name": "Baby seats",
          "description": "Your vehicle will have a child safety seat to keep children under age 4 safe.",
          "imageUrl": "https://api.sandbox.travelandz.com/v1/assets/transfers/images/0/amenities/baby-seats.svg",
          "pngImageUrl": "https://api.sandbox.travelandz.com/v1/assets/transfers/images/0/amenities/baby-seats.png",
          "inputType": "numeric",
          "included": false,
          "selected": true,
          "selectable": true
        },
        {
          "key": "child_booster",
          "name": "Child booster",
          "description": "Your vehicle will have a child booster seat to keep children from age 4-8 safe.",
          "imageUrl": "https://api.sandbox.travelandz.com/v1/assets/transfers/images/0/amenities/child-booster.svg",
          "pngImageUrl": "https://api.sandbox.travelandz.com/v1/assets/transfers/images/0/amenities/child-booster.png",
          "inputType": "numeric",
          "included": false,
          "selected": true,
          "selectable": true
        }
      ]
    }
  ],
  "metadata": {
    "useSearchIdForDetails": true,
    "detailsIdentifier": "searchId",
    "detailsSearchId": "73a5670b476649a985f0535db1077c05",
    "message": "This booking includes amenities. Use searchId to retrieve complete reservation details."
  }
}

200 Sin respuesta definitiva

json

{
  "status": "pending",
  "completed": false,
  "timedOut": true,
  "reservations": [],
  "metadata": {
    "useSearchIdForDetails": false,
    "detailsIdentifier": "reservationId"
  }
}

200 Rechazado

json

{
  "status": "failed",
  "completed": false,
  "timedOut": false,
  "reservations": [],
  "error": "The booking could not be completed",
  "metadata": {
    "useSearchIdForDetails": false,
    "detailsIdentifier": "reservationId"
  }
}

Errores

HTTP	Código	Significado	Acción recomendada
`400`		El body, la query o el path son inválidos, o incluyen una propiedad desconocida.	Corrige la petición usando el array `message`.
`400`	`transfer_invalid_currency`	La moneda está fuera de la lista soportada.	Usa una moneda soportada.
`400`	`transfer_invalid_language`	El idioma solicitado no está soportado.	Usa uno de los valores de idioma documentados.
`429`	`transfer_provider_error`	El servicio está temporalmente limitado por rate limit.	Reintenta con backoff exponencial.
`502`	`transfer_provider_error`	La petición no pudo completarse.	No asumas que tuvo éxito. Conserva tus identificadores y consulta la reserva cuando la operación pudiera haberse creado.
`400`	`transfer_pricing_required`	La petición no incluye pricing token.	Llama primero a pricing y envía su `pricingToken`.
`400`	`transfer_invalid_booking_token`	El booking token expiró, fue modificado o no pertenece a esta oferta.	Vuelve a buscar y usa el token de la nueva oferta seleccionada.
`400`	`transfer_invalid_pricing_token`	El pricing token es inválido o inconsistente con el resto de la petición.	Vuelve a pedir pricing y envía sin cambios el token devuelto.
`400`	`transfer_invalid_amenities`	Las keys de amenities están duplicadas, vacías o no están disponibles en esta oferta.	Envía keys únicas tomadas de la oferta o del catálogo de amenities.
`400`	`transfer_currency_mismatch`	La moneda no coincide con la oferta, la cotización o la reserva.	Reutiliza la moneda devuelta por el paso anterior, u omite el campo para heredarla.
`400`	`transfer_flight_info_required`	La oferta exige `airline` y `flightNumber`.	Envía ambos campos de vuelo cuando la oferta tenga `flightInfoRequired: true`.
`400`	`transfer_return_flight_info_required`	Un round trip exige los datos del vuelo de retorno.	Envía `returnAirline` y `returnFlightNumber`.
`409`	`transfer_price_changed`	El precio de la oferta ya no es el que se cotizó.	Vuelve a pedir pricing y cobra el nuevo `finalPrice.amount`.
`409`	`transfer_booking_in_progress`	La reserva no pudo aceptarse para este pricing token.	Consulta la reserva antes de crear otra, para no reservar dos veces.
`410`	`transfer_pricing_expired`	La cotización expiró antes de crear la reserva.	Vuelve a buscar y a cotizar.

Notas de uso

Cobra al viajero únicamente el finalPrice.amount devuelto por pricing. Si recibes transfer_price_changed, vuelve a pedir pricing y cobra el nuevo importe.

Si una petición de booking falla con 502, no asumas que falló funcionalmente: consulta la reserva con los identificadores que ya tienes antes de crear otra. Las reservas con amenities deben consultarse por searchId.

Nunca registres tokens, datos de pago ni datos personales del viajero en el cliente.

Ejemplo cURL

bash

curl --request POST \
  --url "https://api.sandbox.travelandz.com/v1/transfers/book" \
  -H "Authorization: Bearer $TRAVELANDZ_SECRET_KEY" \
  -H "X-Travelandz-Id: $TRAVELANDZ_PUBLIC_KEY:$TRAVELANDZ_PROFILE_CODE" \
  -H "Content-Type: application/json" \
  --data '{
  "gdsprovider": 0,
  "bookingToken": "opaque_offer_token_generated_by_travelandz",
  "pricingToken": "opaque_public_pricing_token_generated_by_travelandz",
  "searchId": "73a5670b476649a985f0535db1077c05",
  "resultId": "fe94b51ccd0623a9f1adabfbe0614d34",
  "selectedAmenities": [
    "baby_seats",
    "child_booster"
  ],
  "currency": "USD",
  "email": "happytraveler@example.com",
  "countryCodeName": "US",
  "phoneNumber": "+18775998200",
  "firstName": "Happy",
  "lastName": "Traveler",
  "airline": "AA",
  "flightNumber": "123",
  "customerSpecialInstructions": "My doorbell is broken, please call on arrival",
  "partnerTrackingId": "1234567ABC",
  "extraPaxInfo": [
    {
      "firstName": "Jose",
      "lastName": "Smith"
    }
  ]
}'