POST/v1/transfers/book

预订接送服务

根据已定价的报价创建预订。

分享
POST/v1/transfers/book

API 控制台

试一试

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

凭证

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

请求体

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

请填写凭证以发送请求。

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

响应

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

根据已定价的报价创建预订。

认证和请求头

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

请求

发送你已持有的 bookingToken、pricingToken、searchId 和 resultId，以及旅客联系信息。selectedAmenities 和 currency 必须与发送给 pricing 的内容一致。

当报价的 flightInfoRequired 为 true 时，必须提供 airline 和 flightNumber。需要航班信息的往返行程还需要 returnAirline 和 returnFlightNumber。若发送 ticketTypes，其 count 总和必须等于主乘客加上 extraPaxInfo 的长度，因此也要发送 extraPaxInfo——单人出行时传空数组。

请求体结构

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

成功响应

预订以 HTTP 200 和一个 status 字段响应，而不是 201，因为预订并不总是立即确认。

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

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

metadata.detailsIdentifier 会告知之后查询预订时应使用哪个标识符。

响应体结构

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

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

200 被拒绝

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

错误

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

使用说明

只能向旅客收取 pricing 返回的 finalPrice.amount。若收到 transfer_price_changed，请重新定价并按新金额收费。

若预订请求以 502 失败，不要假定业务上也失败：请先用已有标识符查询预订，再决定是否重新创建。含设施的预订必须使用 searchId 查询。

切勿在客户端记录令牌、支付数据或旅客个人信息。

cURL 示例

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