POST/v1/transfers/reservations/changes

确认接送预订变更

用已选择并定价的变更报价替换现有预订。

POST/v1/transfers/reservations/changes

API 控制台

试一试

向沙箱 API 发送真实请求并查看响应。

凭证

Profile code

Public key

Secret key

登录后即可从已保存的 API 密钥中选择，无需手动粘贴。

请求体

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

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"}'

请填写凭证以发送请求。

此请求需要来自上一次调用的标识符或令牌。请先运行前一个步骤，然后把它的值粘贴到这里。

响应

点击「试一试！」发送请求，响应将显示在此处。

用已选择并定价的变更报价替换现有预订。

认证和请求头

请求头	说明
`Authorization`	`Bearer <secret_key>`。密钥只能保存在服务器端，不能写入客户端日志。
`X-Travelandz-Id`	`<public_key>:<profile_code>`，持久化的 profile code 格式为 `dp_<12 位字母数字>`。
`LANG`	推荐的语言请求头，也支持 `Accept-Language`。
`Content-Type`	带 JSON body 的请求使用 `application/json`。

请求

接受与预订相同的全部字段，并额外要求 oldReservationId。请使用变更流程生成的 bookingToken 和 pricingToken，而非原预订的令牌。设置 useReservationCard 可复用该预订已有的支付方式。

请求体结构

oldReservationId

string是

Identifier of the reservation being replaced.

useReservationCard

boolean否

Reuse the payment method already held for the reservation.

gdsprovider

enum

0

是

Transfer content selector. Currently 0.

bookingToken

string是

Copy the bookingToken of the selected offer.

searchId

string是

Must be the searchId of the selected offer.

resultId

string是

Must be the resultId of the selected offer.

pricingToken

string是

Opaque value returned by pricing. Required to book.

selectedAmenities

array是

selectedAmenities[]

string[]否

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

格式: email

是

countryCodeName

string

格式: ISO 3166-1 alpha-2

是

For example US or ES.

phoneNumber

string是

Valid phone number including the country prefix.

firstName

string是

lastName

string是

customerSpecialInstructions

string否

partnerTrackingId

string是

Your own correlation identifier for this booking.

airline

string

格式: IATA (2 characters)

否

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

flightNumber

string否

Alphanumeric, 1-8 characters, no spaces.

returnAirline

string否

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

returnFlightNumber

string否

Alphanumeric, 1-8 characters.

extraPaxInfo

array是

extraPaxInfo[]firstName

string是

extraPaxInfo[]lastName

string是

extraPaxInfo[]email

string

格式: email

否

extraPaxInfo[]phoneNumber

string否

ticketTypes

array是

ticketTypes[]id

string是

Ticket type identifier from the offer. Must be unique.

ticketTypes[]count

number是

Integer of at least 1.

scheduleIndex

number否

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

paymentToken

string否

Only when the selected offer requires it.

successUrl

string

格式: 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.

请求示例

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"
}

成功响应

响应结构与预订相同。

在向旅客告知任何结果前，请同时查看 status 和 completed：

completed 且 completed 为 true 并至少有一个预订：接送已预订成功。
pending：尚无最终结果。请查询预订以确认结果，不要重复发送请求。
failed：预订被拒绝，error 说明原因。

变更完成后，新预订的标识符将取代原预订的标识符。请更新你保存的所有原预订信息。

响应体结构

status

enum

completedpendingfailed

是

completed

boolean是

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

timedOut

boolean是

True when a final state was not reached in time.

reservations

array是

reservations[]gdsprovider

enum

0

是

reservations[]reservationId

string是

Persist this value; reservation reads and cancellation need it.

reservations[]confirmationNumber

string否

Traveller-facing confirmation code.

reservations[]status

enum

completedpendingfailed

是

reservations[]cancelled

boolean是

reservations[]totalAmount

number是

Total charged for the reservation.

reservations[]currency

enum

EURUSDINRCHFJPYGBPAUDCADCNYSGDNZDMXN

是

reservations[]pickupInstructions

string否

reservations[]ticketUrl

string

格式: URL

否

reservations[]selectedScheduleIndex

number否

reservations[]departureDatetime

string

格式: ISO 8601

否

reservations[]arrivalDatetime

string

格式: ISO 8601

否

reservations[]selectedAmenities

array是

reservations[]selectedAmenities[]key

string是

Value to send in selectedAmenities.

reservations[]selectedAmenities[]name

string是

Localized name.

reservations[]selectedAmenities[]description

string否

reservations[]selectedAmenities[]imageUrl

string

格式: URL

否

reservations[]selectedAmenities[]pngImageUrl

string

格式: URL

否

reservations[]selectedAmenities[]inputType

enum

booleannumeric

否

reservations[]selectedAmenities[]included

boolean是

True when the amenity is already part of the offer.

reservations[]selectedAmenities[]selectable

boolean是

True when the amenity can be added to this offer.

reservations[]selectedAmenities[]selected

boolean是

True when the amenity is part of the priced selection.

error

string否

Present when status is failed.

metadata

object是

metadatauseSearchIdForDetails

boolean是

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

metadatadetailsIdentifier

enum

reservationIdsearchId

是

Identifier to use when reading the reservation.

metadatadetailsSearchId

string否

Present when detailsIdentifier is searchId.

metadatamessage

string否

响应示例

200 已变更

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 尚无最终结果

json

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

错误

HTTP	代码	含义	建议操作
`400`		请求体、查询参数或路径无效，或包含未知属性。	根据 `message` 数组修正请求。
`400`	`transfer_invalid_currency`	该货币不在支持列表中。	使用受支持的货币。
`400`	`transfer_invalid_language`	请求的语言不受支持。	使用文档中列出的语言值之一。
`429`	`transfer_provider_error`	服务暂时被限流。	使用指数退避重试。
`502`	`transfer_provider_error`	请求无法完成。	不要假定成功。保留标识符，并在该操作可能已创建时查询预订。
`400`	`transfer_pricing_required`	请求缺少 pricing token。	先调用 pricing，然后发送其 `pricingToken`。
`400`	`transfer_invalid_booking_token`	booking token 已过期、被修改，或不属于该报价。	重新搜索，并使用新选报价的令牌。
`400`	`transfer_invalid_pricing_token`	pricing token 无效，或与请求其余内容不一致。	重新调用 pricing，并原样发送其返回的令牌。
`400`	`transfer_invalid_amenities`	amenity key 重复、为空，或该报价不提供。	发送取自报价或设施目录的唯一 key。
`400`	`transfer_currency_mismatch`	货币与报价、报价单或预订不一致。	复用上一步返回的货币，或省略该字段以继承它。
`400`	`transfer_flight_info_required`	该报价要求提供 `airline` 和 `flightNumber`。	当报价的 `flightInfoRequired` 为 true 时，同时发送两个航班字段。
`400`	`transfer_return_flight_info_required`	往返行程要求提供返程航班信息。	发送 `returnAirline` 和 `returnFlightNumber`。
`409`	`transfer_price_changed`	报价的价格已不再是此前的报价金额。	重新调用 pricing，并按新的 `finalPrice.amount` 收费。
`409`	`transfer_booking_in_progress`	无法为该 pricing token 接受此预订。	在再次创建之前先查询预订，以避免重复预订。
`410`	`transfer_pricing_expired`	在创建预订前报价单已过期。	重新搜索并定价。

使用说明

若变更令牌过期或金额发生变化，请重新执行变更搜索和定价。缺失或格式错误的 oldReservationId 会以 400 拒绝。

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"
}'