POST/v1/flights/order/required-fields/:gdsprovider/:offerId

查询航班预订必填字段

返回完成所选航班报价预订所需的动态旅客、证件和身份字段。

POST/v1/flights/order/required-fields/:gdsprovider/:offerId

API 控制台

试一试

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

凭证

Profile code

Public key

Secret key

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

路径参数

2 个字段

gdsproviderenum必填

GDS 提供方

用于获取航班内容的全球分销系统。选择 0 使用默认提供方。

offerIdstring必填

Offer ID

上一次航班搜索请求返回的报价标识符。

请求体

{
  "offerId": "off_0000B7VCW4q5OD5G49hmKn",
  "passengers": [
    {
      "type": "adult"
    }
  ]
}

cURL 请求

cURL

bash

curl -X POST 'https://api.sandbox.travelandz.com/v1/flights/order/required-fields/0/:offerId' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'X-Travelandz-Id: YOUR_PUBLIC_KEY:YOUR_PROFILE_CODE' \
  -H 'Content-Type: application/json' \
  -d '{"offerId":"off_0000B7VCW4q5OD5G49hmKn","passengers":[{"type":"adult"}]}'

请填写凭证以发送请求。

响应

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

返回完成所选航班报价预订所需的动态旅客、证件和身份字段。

接口

方法	路径	认证
`POST`	`/v1/flights/order/required-fields/:gdsprovider/:offerId`	需要 API key

必需请求头：

Header	说明
`Authorization`	`Bearer <secret_key>`. The secret is shown only once when the credential is created.
`X-Travelandz-Id`	`<public_key>:<profile_code>`. The `profile_code` is the `dp_`-prefixed Developer Profile code shown in your dashboard. This binds the request to a profile and credential.
`Content-Type`	Use `application/json` for requests with a body.

请求参数结构

gdsprovider

number是

Accepted values: 0, 1

offerId

string是

请求体结构

offerId

string是

Selected offer id

passengers

array是

passengers[]type

enum

adultchildinfant_without_seat

是

成功响应

返回 required field definitions for the offer.

响应体结构

holder

object是

holderphone

boolean是

为 true 时，为使用 holder 联系信息的流程提供 E.164 格式的 passengers[0].phone_number

holderemail

boolean是

为 true 时，为使用 holder email 的流程提供 passengers[0].email

holdercountryCode

boolean是

create-order 中没有单独字段。在 gdsprovider=1 流程中，它由 E.164 格式的 passengers[0].phone_number 派生

passengers

array是

passengers[]idx

number是

required-fields 响应中的旅客索引

passengers[]title

boolean是

映射到 passengers[].title

passengers[]type

boolean是

映射到 passengers[].type

passengers[]name

boolean是

映射到 passengers[].firstName

passengers[]lastName

boolean是

映射到 passengers[].lastName

passengers[]age

boolean是

仅供参考。create-order 中没有直接字段，并且当前公共航班流程中该值为 false

passengers[]nationality

boolean是

为 true 时映射到 passengers[].country

passengers[]gender

boolean是

映射到 passengers[].gender

passengers[]phone

boolean是

为 true 时映射到 passengers[].phone_number

passengers[]email

boolean是

为 true 时映射到 passengers[].email。某些 gdsprovider=1 流程只会使用第一位旅客的 email

passengers[]address

boolean是

仅供参考。create-order 中没有直接字段，并且当前公共航班流程中该值为 false

passengers[]city

boolean是

仅供参考。create-order 中没有直接字段，并且当前公共航班流程中该值为 false

passengers[]postalCode

boolean是

仅供参考。create-order 中没有直接字段，并且当前公共航班流程中该值为 false

passengers[]bornDate

boolean是

为 true 时映射到 passengers[].bornDate

passengers[]documentIdentifier

boolean是

为 true 时映射到 passengers[].identity_documents[].unique_identifier

passengers[]documentType

boolean是

为 true 时映射到 passengers[].identity_documents[].type，当使用证件对象时适用

passengers[]documentIssuedAt

boolean是

仅供参考。create-order 中没有直接字段，并且当前公共航班流程中该值为 false

passengers[]documentExpiresAt

boolean是

为 true 时映射到 passengers[].identity_documents[].expires_on

passengers[]documentCountryCode

boolean是

为 true 时映射到 passengers[].identity_documents[].issuing_country_code

passengers[]allowedDocuments

array可为空

预订证件流程允许的值：passport、tax_id、known_traveler_number、passenger_redress_number、dni。如果允许 dni，还需要收集 passengers[].NationalID，因为当前响应没有专用的 nationalId 标记

liveMode

boolean是

True when the request is served by the live Travelandz environment. This value comes from Travelandz, not the provider payload.

集成说明

优先使用此 POST 端点，因为它可以在请求体中接收旅客上下文。
GET /v1/flights/order/required-fields/:gdsprovider/:offerId 仅为兼容保留，集成应使用 POST。
真实响应合同是 holder 加 passengers[]，不是 requiredFields[] 包装。
根据响应判断预订前是否需要收集 identity_documents、NationalID、国籍或证件有效期。
allowedDocuments 限制 passengers[].identity_documents[].type 的有效值。如果包含 dni，也要收集 passengers[].NationalID，即使当前响应没有专用的 nationalId boolean。
在 gdsprovider=1 流程中，holder.countryCode 不对应单独的预订字段，而是由 E.164 格式的 passengers[0].phone_number 满足。
在 gdsprovider=1 流程中，passengers[].email 可能被标记为必填，但实际可能只使用第一位旅客的 email 作为 holder email。

示例

bash

curl -X POST https://api.sandbox.travelandz.com/v1/flights/order/required-fields/0/offer_123 \
  -H "Authorization: Bearer $TRAVELANDZ_SECRET_KEY" \
  -H "X-Travelandz-Id: $TRAVELANDZ_PUBLIC_KEY:$TRAVELANDZ_PROFILE_CODE" \
  -H "Content-Type: application/json" \
  -d '{"offerId":"offer_123","passengers":[{"type":"adult"}]}'

请求体 - 示例

json

{
  "offerId": "off_0000B7VCW4q5OD5G49hmKn",
  "passengers": [
    {
      "type": "adult"
    }
  ]
}

响应

状态码	说明
`200`	已成功解析预订必填字段。
`400`	请求无效：payload 不合法。
`401`	未授权：凭证无效或缺失。
`403`	禁止访问：凭证无效。
`500`	服务器内部错误

200 响应体

媒体类型：application/json

json

{
  "holder": {
    "phone": false,
    "email": false,
    "countryCode": false
  },
  "passengers": [
    {
      "idx": 0,
      "title": true,
      "type": true,
      "name": true,
      "lastName": true,
      "age": false,
      "nationality": false,
      "gender": true,
      "phone": true,
      "email": true,
      "address": false,
      "city": false,
      "postalCode": false,
      "bornDate": true,
      "documentIdentifier": false,
      "documentType": false,
      "documentIssuedAt": false,
      "documentExpiresAt": false,
      "documentCountryCode": false,
      "allowedDocuments": null
    }
  ],
  "liveMode": false
}