POST/v1/transfers/reservations/changes/search
Consola API
Pruébalo
Envía una petición real al entorno sandbox e inspecciona la respuesta.
Credenciales
Inicia sesión para elegir entre tus API keys guardadas en vez de pegarlas.
Cuerpo de la petición
Petición cURL
bash
curl -X POST 'https://api.sandbox.travelandz.com/v1/transfers/reservations/changes/search' \
-H 'Authorization: Bearer YOUR_SECRET_KEY' \
-H 'X-Travelandz-Id: YOUR_PUBLIC_KEY:YOUR_PROFILE_CODE' \
-H 'Content-Type: application/json' \
-d '{"reservationHashedId":"5c8563a5d31d4c33a3a1eafbbfe59c4b","pickupDatetime":"2026-08-30 22:00","numPassengers":2,"currency":"USD"}'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í.
Busca ofertas de reemplazo para una reserva existente.
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
Solo reservationHashedId es obligatorio. Envía únicamente los campos que quieras cambiar: todo lo que omitas se toma de la reserva original.
Este endpoint siempre responde con JSON. Nunca abre un stream.
Schema del body
reservationHashedIdIdentifier of the reservation you want to replace.
modenumPassengersWhen sent, an integer of at least 1.
startAddressOptional override of the original location.
startCityAppended to the address to improve resolution.
startZipcodeAppended to the address to improve resolution.
startLatMust be sent together with
startLng.startLngMust be sent together with
startLat.startPlaceIdAlternative to an address or coordinates.
endAddressOptional override of the original location.
endCityAppended to the address to improve resolution.
endZipcodeAppended to the address to improve resolution.
endLatMust be sent together with
endLng.endLngMust be sent together with
endLat.endPlaceIdAlternative to an address or coordinates.
pickupDatetimeflightDatetimereturnPickupDatetimereturnFlightDatetimeamenitiesamenities[]currencyLowercase values are accepted and normalized. Defaults to
USD on a new search and is inherited afterwards.campaignYour own campaign context.
branchRequires
campaign when sent.languageLegacy field. Prefer the
LANG or Accept-Language header.Ejemplo de petición
json
{
"reservationHashedId": "5c8563a5d31d4c33a3a1eafbbfe59c4b",
"pickupDatetime": "2026-08-30 22:00",
"numPassengers": 2,
"currency": "USD"
}Respuesta exitosa
Devuelve un nuevo searchId de cambio y offers[]. Las ofertas tienen la misma forma que un resultado de búsqueda normal, incluido un bookingToken opaco por oferta.
Schema de respuesta
gdsprovidersearchIdChange search identifier. Send it to pricing and confirmation.
moreComingTrue when more replacement offers may still arrive.
pickupDatetimenumPassengersstartLocationstartLocationformattedAddressstartLocationfullAddressstartLocationiataCodePresent for airport locations.
startLocationicaoCodestartLocationplaceIdReusable place identifier; send it back to skip geocoding.
startLocationlatitudestartLocationlongitudestartLocationtimezoneIANA timezone of the location.
endLocationendLocationformattedAddressendLocationfullAddressendLocationiataCodePresent for airport locations.
endLocationicaoCodeendLocationplaceIdReusable place identifier; send it back to skip geocoding.
endLocationlatitudeendLocationlongitudeendLocationtimezoneIANA timezone of the location.
offersoffers[]searchIdSend this value in pricing, booking and reservation reads.
offers[]gdsprovideroffers[]resultIdIdentifies the selected offer.
offers[]bookingTokenOpaque value. Copy it into pricing and booking; never decode or modify it.
offers[]expiresAtThe offer and its token stop being usable after this moment.
offers[]vehicleIdoffers[]totalAmountIndicative total for the offer in
currency.offers[]currencyoffers[]bookableFalse when the offer cannot be booked.
offers[]flightInfoRequiredWhen true,
airline and flightNumber are required to book.offers[]extraPaxRequiredWhen true,
extraPaxInfo is required to book.offers[]goodToKnowInfooffers[]goodToKnowInfo[]Localized operational notes to show the traveller.
offers[]supportsoffers[]cancellationPoliciesoffers[]cancellationPolicies[]noticeHours of notice the policy requires.
offers[]cancellationPolicies[]refundPercentoffers[]cancellationPolicies[]refundableUntilDatetimeoffers[]cancellationPolicies[]refundAmountRefundable amount in the offer currency.
offers[]cancellationPolicies[]currencyoffers[]stepsoffers[]steps[]stepTypeLeg type, for example
car.offers[]steps[]mainTrue for the primary leg of the transfer.
offers[]steps[]descriptionoffers[]steps[]departureDatetimeoffers[]steps[]durationMinutesoffers[]steps[]durationSecondsoffers[]steps[]distanceMetersoffers[]steps[]distanceMilesoffers[]steps[]lineNamePresent for scheduled line transport.
offers[]steps[]lineColoroffers[]steps[]provideroffers[]steps[]providernameoffers[]steps[]providerratingoffers[]steps[]vehicleoffers[]steps[]vehicletypeVehicle name, for example
Shared Ride Van.offers[]steps[]vehiclecategoryVehicle grouping, for example
Shared or Private.offers[]steps[]vehiclemaxBagsoffers[]steps[]vehiclemaxPassengersoffers[]steps[]vehiclenumVehiclesoffers[]steps[]vehicleimageUrloffers[]steps[]waitTimeoffers[]steps[]waitTimeincludedoffers[]steps[]waitTimeminutesIncludedoffers[]steps[]waitTimeextraWaitTimeChargeableoffers[]steps[]amenitiesoffers[]steps[]amenities[]keyValue to send in
selectedAmenities.offers[]steps[]amenities[]nameLocalized name.
offers[]steps[]amenities[]descriptionoffers[]steps[]amenities[]imageUrloffers[]steps[]amenities[]pngImageUrloffers[]steps[]amenities[]inputTypeoffers[]steps[]amenities[]includedTrue when the amenity is already part of the offer.
offers[]steps[]amenities[]selectableTrue when the amenity can be added to this offer.
offers[]steps[]amenities[]selectedTrue when the amenity is part of the priced selection.
offers[]steps[]startLocationoffers[]steps[]startLocationformattedAddressoffers[]steps[]startLocationfullAddressoffers[]steps[]startLocationiataCodePresent for airport locations.
offers[]steps[]startLocationicaoCodeoffers[]steps[]startLocationplaceIdReusable place identifier; send it back to skip geocoding.
offers[]steps[]startLocationlatitudeoffers[]steps[]startLocationlongitudeoffers[]steps[]startLocationtimezoneIANA timezone of the location.
offers[]steps[]endLocationoffers[]steps[]endLocationformattedAddressoffers[]steps[]endLocationfullAddressoffers[]steps[]endLocationiataCodePresent for airport locations.
offers[]steps[]endLocationicaoCodeoffers[]steps[]endLocationplaceIdReusable place identifier; send it back to skip geocoding.
offers[]steps[]endLocationlatitudeoffers[]steps[]endLocationlongitudeoffers[]steps[]endLocationtimezoneIANA timezone of the location.
offers[]ticketTypesoffers[]ticketTypes[]idSend this value in
ticketTypes[].id when booking.offers[]ticketTypes[]nameoffers[]ticketTypes[]departureDatetimeoffers[]ticketTypes[]arrivalDatetimeoffers[]alternativeTimesoffers[]alternativeTimes[]departureDatetimeoffers[]alternativeTimes[]arrivalDatetimeEjemplos de respuesta
json
{
"gdsprovider": 0,
"searchId": "5c8563a5d31d4c33a3a1eafbbfe59c49",
"moreComing": false,
"pickupDatetime": "2026-08-30T22:00:00-04:00",
"numPassengers": 2,
"startLocation": {
"formattedAddress": "433 Park Ave, New York, NY 10022, USA",
"fullAddress": "433 Park Ave, New York",
"placeId": "EiU0MzMgUGFyayBBdmUsIE5ldyBZb3JrLCBOWSAxMDAyMiwgVVNB",
"latitude": 40.7607634,
"longitude": -73.971212,
"timezone": "America/New_York"
},
"endLocation": {
"formattedAddress": "John F Kennedy International Airport",
"fullAddress": "John F Kennedy International Airport",
"iataCode": "JFK",
"icaoCode": "KJFK",
"latitude": 40.639751,
"longitude": -73.778926,
"timezone": "America/New_York"
},
"offers": [
{
"searchId": "5c8563a5d31d4c33a3a1eafbbfe59c49",
"gdsprovider": 0,
"resultId": "763475651c06f5ac31ea587084dc0640",
"bookingToken": "opaque_change_offer_token_generated_by_travelandz",
"expiresAt": "2026-08-30T22:20:00.000Z",
"totalAmount": 49.84,
"currency": "USD",
"bookable": true,
"flightInfoRequired": true,
"extraPaxRequired": false,
"goodToKnowInfo": [],
"cancellationPolicies": [
{
"notice": 48,
"refundPercent": 100,
"refundAmount": 49.84,
"currency": "USD"
}
],
"supports": {},
"steps": [
{
"stepType": "car",
"main": true,
"departureDatetime": "2026-08-30T22:40:00-04:00",
"provider": {
"name": "GO Airlink NYC",
"rating": 5
},
"vehicle": {
"type": "Shared Ride Van",
"category": "Shared",
"maxBags": 4,
"maxPassengers": 11,
"numVehicles": 1
},
"amenities": []
}
],
"ticketTypes": [],
"alternativeTimes": [
{
"departureDatetime": "2026-08-30T22:40:00-04:00",
"arrivalDatetime": "2026-08-30T23:06:10-04:00"
},
{
"departureDatetime": "2026-08-30T23:40:00-04:00",
"arrivalDatetime": "2026-08-31T00:06:10-04:00"
}
]
}
]
}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_location_not_found | No se pudo resolver el origen o el destino. | Añade city o zipcode, o envía un place ID o un par de coordenadas. |
503 | El precio no pudo confirmarse en este momento. | Reintenta más tarde. No reserves ni cobres al viajero. |
Notas de uso
Después de que el viajero elija una oferta de reemplazo, pide pricing para ella y luego confirma el cambio. La reserva original permanece activa hasta confirmar el cambio.
Ejemplo cURL
bash
curl --request POST \
--url "https://api.sandbox.travelandz.com/v1/transfers/reservations/changes/search" \
-H "Authorization: Bearer $TRAVELANDZ_SECRET_KEY" \
-H "X-Travelandz-Id: $TRAVELANDZ_PUBLIC_KEY:$TRAVELANDZ_PROFILE_CODE" \
-H "Content-Type: application/json" \
--data '{
"reservationHashedId": "5c8563a5d31d4c33a3a1eafbbfe59c4b",
"pickupDatetime": "2026-08-30 22:00",
"numPassengers": 2,
"currency": "USD"
}'