POST/v1/transfers/reservations/changes

Confirmar cambio de una reserva de transfer

Reemplaza una reserva existente con una oferta de cambio seleccionada y cotizada.

POST/v1/transfers/reservations/changes

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

{
  "oldReservationId": "5c8563a5d31d4c33a3a1eafbbfe59c4b",
  "useReservationCard": true,
  "gdsprovider": 0,
  "bookingToken": "opaque_change_offer_token_generated_by_travelandz",
  "pricingToken": "opaque_change_pricing_token_generated_by_travelandz",
  "searchId": "5c8563a5d31d4c33a3a1eafbbfe59c49",
  "resultId": "763475651c06f5ac31ea587084dc0640",
  "currency": "USD",
  "email": "happytraveler@example.com",
  "countryCodeName": "US",
  "phoneNumber": "+18775998200",
  "firstName": "Happy",
  "lastName": "Traveler",
  "airline": "AA",
  "flightNumber": "123",
  "customerSpecialInstructions": "Special instructions changed",
  "partnerTrackingId": "change-1234567ABC"
}

Petición cURL

cURL

bash

curl -X POST 'https://api.sandbox.travelandz.com/v1/transfers/reservations/changes' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'X-Travelandz-Id: YOUR_PUBLIC_KEY:YOUR_PROFILE_CODE' \
  -H 'Content-Type: application/json' \
  -d '{"oldReservationId":"5c8563a5d31d4c33a3a1eafbbfe59c4b","useReservationCard":true,"gdsprovider":0,"bookingToken":"opaque_change_offer_token_generated_by_travelandz","pricingToken":"opaque_change_pricing_token_generated_by_travelandz","searchId":"5c8563a5d31d4c33a3a1eafbbfe59c49","resultId":"763475651c06f5ac31ea587084dc0640","currency":"USD","email":"happytraveler@example.com","countryCodeName":"US","phoneNumber":"+18775998200","firstName":"Happy","lastName":"Traveler","airline":"AA","flightNumber":"123","customerSpecialInstructions":"Special instructions changed","partnerTrackingId":"change-1234567ABC"}'

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í.

Reemplaza una reserva existente con una oferta de cambio seleccionada y 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

Acepta todos los campos del booking, más el oldReservationId obligatorio. Usa el bookingToken y el pricingToken generados por el flujo de cambio, no los de la reserva original. Usa useReservationCard para reutilizar el método de pago ya asociado a la reserva.

Schema del body

oldReservationId

stringSí

Identifier of the reservation being replaced.

useReservationCard

booleanNo

Reuse the payment method already held for the reservation.

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

{
  "oldReservationId": "5c8563a5d31d4c33a3a1eafbbfe59c4b",
  "useReservationCard": true,
  "gdsprovider": 0,
  "bookingToken": "opaque_change_offer_token_generated_by_travelandz",
  "pricingToken": "opaque_change_pricing_token_generated_by_travelandz",
  "searchId": "5c8563a5d31d4c33a3a1eafbbfe59c49",
  "resultId": "763475651c06f5ac31ea587084dc0640",
  "currency": "USD",
  "email": "happytraveler@example.com",
  "countryCodeName": "US",
  "phoneNumber": "+18775998200",
  "firstName": "Happy",
  "lastName": "Traveler",
  "airline": "AA",
  "flightNumber": "123",
  "customerSpecialInstructions": "Special instructions changed",
  "partnerTrackingId": "change-1234567ABC"
}

Respuesta exitosa

Responde con el mismo envelope que el booking.

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.

Cuando el cambio se completa, los identificadores de la nueva reserva reemplazan a los de la anterior. Actualiza todo lo que tuvieras guardado de la reserva original.

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 Cambiado

json

{
  "status": "completed",
  "completed": true,
  "timedOut": false,
  "reservations": [
    {
      "gdsprovider": 0,
      "reservationId": "c204ab71cf4c4f0d9a2f2c5a4de1b8f3",
      "confirmationNumber": "TZ-6202244",
      "status": "completed",
      "cancelled": false,
      "totalAmount": 49.84,
      "currency": "USD",
      "pickupInstructions": "The driver will call you when he arrives.",
      "departureDatetime": "2026-08-30T22:40:00-04:00",
      "arrivalDatetime": "2026-08-30T23:06:00-04:00",
      "selectedAmenities": []
    }
  ],
  "metadata": {
    "useSearchIdForDetails": false,
    "detailsIdentifier": "reservationId"
  }
}

200 Sin respuesta definitiva

json

{
  "status": "pending",
  "completed": false,
  "timedOut": false,
  "reservations": [],
  "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

Si un token de cambio expira o el importe cambia, repite la búsqueda de cambio y el pricing. Un oldReservationId ausente o mal formado se rechaza con 400.

Ejemplo cURL

bash

curl --request POST \
  --url "https://api.sandbox.travelandz.com/v1/transfers/reservations/changes" \
  -H "Authorization: Bearer $TRAVELANDZ_SECRET_KEY" \
  -H "X-Travelandz-Id: $TRAVELANDZ_PUBLIC_KEY:$TRAVELANDZ_PROFILE_CODE" \
  -H "Content-Type: application/json" \
  --data '{
  "oldReservationId": "5c8563a5d31d4c33a3a1eafbbfe59c4b",
  "useReservationCard": true,
  "gdsprovider": 0,
  "bookingToken": "opaque_change_offer_token_generated_by_travelandz",
  "pricingToken": "opaque_change_pricing_token_generated_by_travelandz",
  "searchId": "5c8563a5d31d4c33a3a1eafbbfe59c49",
  "resultId": "763475651c06f5ac31ea587084dc0640",
  "currency": "USD",
  "email": "happytraveler@example.com",
  "countryCodeName": "US",
  "phoneNumber": "+18775998200",
  "firstName": "Happy",
  "lastName": "Traveler",
  "airline": "AA",
  "flightNumber": "123",
  "customerSpecialInstructions": "Special instructions changed",
  "partnerTrackingId": "change-1234567ABC"
}'