POST/v1/transfers/reservations/changes/search
API 控制台
试一试
向沙箱 API 发送真实请求并查看响应。
凭证
登录后即可从已保存的 API 密钥中选择，无需手动粘贴。
请求体
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"}'请填写凭证以发送请求。
此请求需要来自上一次调用的标识符或令牌。请先运行前一个步骤，然后把它的值粘贴到这里。
响应
点击「试一试！」发送请求，响应将显示在此处。
为现有预订查找替代报价。
认证和请求头
| 请求头 | 说明 |
|---|---|
Authorization | Bearer <secret_key>。密钥只能保存在服务器端，不能写入客户端日志。 |
X-Travelandz-Id | <public_key>:<profile_code>，持久化的 profile code 格式为 dp_<12 位字母数字>。 |
LANG | 推荐的语言请求头，也支持 Accept-Language。 |
Content-Type | 带 JSON body 的请求使用 application/json。 |
请求
只有 reservationHashedId 是必需的。仅发送你想修改的字段，省略的字段沿用原预订。
此端点始终以 JSON 响应，不会打开流。
请求体结构
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.请求示例
json
{
"reservationHashedId": "5c8563a5d31d4c33a3a1eafbbfe59c4b",
"pickupDatetime": "2026-08-30 22:00",
"numPassengers": 2,
"currency": "USD"
}成功响应
返回新的变更 searchId 和 offers[]。这些报价与普通搜索结果结构相同，每个报价都带有不透明的 bookingToken。
响应体结构
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[]arrivalDatetime响应示例
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"
}
]
}
]
}错误
| HTTP | 代码 | 含义 | 建议操作 |
|---|---|---|---|
400 | 请求体、查询参数或路径无效，或包含未知属性。 | 根据 message 数组修正请求。 | |
400 | transfer_invalid_currency | 该货币不在支持列表中。 | 使用受支持的货币。 |
400 | transfer_invalid_language | 请求的语言不受支持。 | 使用文档中列出的语言值之一。 |
429 | transfer_provider_error | 服务暂时被限流。 | 使用指数退避重试。 |
502 | transfer_provider_error | 请求无法完成。 | 不要假定成功。保留标识符，并在该操作可能已创建时查询预订。 |
400 | transfer_location_not_found | 无法解析起点或终点。 | 补充城市或邮编，或改用 place ID 或经纬度对。 |
503 | 当前无法确认价格。 | 稍后重试。不要预订，也不要向旅客收费。 |
使用说明
旅客选定替代报价后，先为其调用 pricing，然后确认变更。在确认变更之前，原预订保持有效。
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"
}'