GET/v1/transfers/reservations/by-search/:searchId

按搜索 ID 获取预订

查询包含已选设施的预订。

分享
GET/v1/transfers/reservations/by-search/:searchId

API 控制台

试一试

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

凭证

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

路径参数

1 个字段

搜索 ID

用于创建预订的搜索标识符。含设施的预订必须使用它。在统一详情端点中，reservationId、confirmationNumber、searchId 三者只能发送其中一个。

查询参数

3 个字段

GDS 提供方

接送服务内容选择器，目前仅支持 0。

货币

返回金额所用的货币。若已存在报价或预订，必须与其保持一致。

语言

旧版语言字段。建议使用 LANG 或 Accept-Language 请求头。

cURL 请求

cURL
bash
curl -X GET 'https://api.sandbox.travelandz.com/v1/transfers/reservations/by-search/:searchId?gdsprovider=0&currency=USD' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'X-Travelandz-Id: YOUR_PUBLIC_KEY:YOUR_PROFILE_CODE'

请填写凭证以发送请求。

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

响应

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

查询包含已选设施的预订。

认证和请求头

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

请求

此端点不接收请求体。searchId 放在路径中，gdsprovider 放在查询参数中。

请求参数结构

searchId
string是
Search identifier used to create the booking.

请求查询参数模式

gdsprovider
enum
0
是
Transfer content selector. Currently 0.
currency
enum
EURUSDINRCHFJPYGBPAUDCADCNYSGDNZDMXN
否
Lowercase values are accepted and normalized. Defaults to USD on a new search and is inherited afterwards.
language
enum
en-USes-ESde-DEfr-FRpt-BRzh-CNit-IT
否
Legacy field. Prefer the LANG or Accept-Language header.

成功响应

返回预订结构，且 selectedAmenities 内容完整。

响应体结构

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否

响应示例

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

错误

HTTP代码含义建议操作
400请求体、查询参数或路径无效，或包含未知属性。根据 message 数组修正请求。
400transfer_invalid_currency该货币不在支持列表中。使用受支持的货币。
400transfer_invalid_language请求的语言不受支持。使用文档中列出的语言值之一。
429transfer_provider_error服务暂时被限流。使用指数退避重试。
502transfer_provider_error请求无法完成。不要假定成功。保留标识符，并在该操作可能已创建时查询预订。
400transfer_currency_mismatch货币与报价、报价单或预订不一致。复用上一步返回的货币，或省略该字段以继承它。
503当前无法确认价格。稍后重试。不要预订，也不要向旅客收费。

使用说明

对于任何含设施创建的预订，这是推荐端点。请保留预订时使用的 searchId，以便日后查询。

cURL 示例

bash
bash
curl --request GET \
  --url "https://api.sandbox.travelandz.com/v1/transfers/reservations/by-search/73a5670b476649a985f0535db1077c05?gdsprovider=0&currency=USD" \
  -H "Authorization: Bearer $TRAVELANDZ_SECRET_KEY" \
  -H "X-Travelandz-Id: $TRAVELANDZ_PUBLIC_KEY:$TRAVELANDZ_PROFILE_CODE"