POST/v1/flights/order/:gdsprovider/:offerId

创建航班订单

从所选报价创建即时航班预订或保留订单。公共预订会通过 offerId 或已跟踪的报价数据解析内部价格。

POST/v1/flights/order/:gdsprovider/:offerId

API 控制台

试一试

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

凭证

Profile code

Public key

Secret key

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

路径参数

2 个字段

gdsproviderenum必填

GDS 提供方

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

offerIdstring必填

Offer ID

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

请求体

{
  "currency": "EUR",
  "passengers": [
    {
      "id": "pas_0000B7VCW4ca7emwcBOyUf",
      "type": "adult",
      "title": "mr",
      "phone_number": "+573128837058",
      "firstName": "Alejandro",
      "lastName": "Toledo",
      "gender": "m",
      "email": "jairotoledo2003@gmail.com",
      "bornDate": "2003-08-14"
    }
  ],
  "type": "instant"
}

cURL 请求

cURL

bash

curl -X POST 'https://api.sandbox.travelandz.com/v1/flights/order/0/:offerId' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'X-Travelandz-Id: YOUR_PUBLIC_KEY:YOUR_PROFILE_CODE' \
  -H 'Content-Type: application/json' \
  -d '{"currency":"EUR","passengers":[{"id":"pas_0000B7VCW4ca7emwcBOyUf","type":"adult","title":"mr","phone_number":"+573128837058","firstName":"Alejandro","lastName":"Toledo","gender":"m","email":"jairotoledo2003@gmail.com","bornDate":"2003-08-14"}],"type":"instant"}'

请填写凭证以发送请求。

响应

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

从所选报价创建即时航班预订或保留订单。公共预订会通过 offerId 或已跟踪的报价数据解析内部价格。

接口

方法	路径	认证
`POST`	`/v1/flights/order/: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是

offerId

string是

请求体结构

currency

enum

EURUSDCNY

是

公共预订请求的币种。内部价格会通过 offerId 或已跟踪的报价数据解析

passengers

array是

passengers[]id

string是

Passenger id from the selected tracked public offer. It must exactly match the offer passenger id and type. Empty, missing, duplicate or extra passenger ids are rejected. Mystifly offers generate ids such as mystifly_pax_1.

passengers[]type

enum

adultchildinfant_without_seat

是

passengers[]title

enum

mrmsmrsmiss

是

passengers[]phone_number

string

Format: E.164 phone number

是

满足 passengers[].phone。在 gdsprovider=1 流程中，passengers[0].phone_number 也满足 holder.phone 并派生 holder.countryCode

passengers[]infant_passenger_id

string否

当旅客关联婴儿时必填

passengers[]identity_documents

array否

身份证件对象。示例：[{ type, unique_identifier, issuing_country_code, expires_on }]。当报价或 required-fields 响应要求时必填

passengers[]firstName

string是

满足 required-fields 中的 passengers[].name

passengers[]lastName

string是

满足 required-fields 中的 passengers[].lastName

passengers[]gender

enum

mf

是

passengers[]email

string是

满足 passengers[].email。某些 gdsprovider=1 流程只会使用第一位旅客的 email 作为顶层 holder email

passengers[]bornDate

string

Format: YYYY-MM-DD

是

passengers[]country

string否

2 位 ISO 国家代码。当 required-fields 将 nationality 标记为 true 时使用

passengers[]NationalID

string否

当所选流程要求国家身份号码时使用。在当前 gdsprovider=1 响应中，即使没有显式 nationalId 标记，allowedDocuments 包含 dni 也可能表示需要该字段

passengers[]loyaltyProgrammeAccounts

array否

可选的常旅客账户对象。示例：[{ airlineIataCode, accountNumber }]。仅当 supportedLoyaltyPrograms 包含航空公司代码时使用

totalSegments

array是

totalSegments[]originCode

string是

Mapped from offer.slices[].segments[].departure.iataCode

totalSegments[]destinationCode

string是

Mapped from offer.slices[].segments[].arrival.iataCode

totalSegments[]flightNumber

string是

Mapped from offer.slices[].segments[].flightNumber

totalSegments[]departureDate

string

Format: ISO 8601

是

Mapped from offer.slices[].segments[].departure.departingAt

holdId

string否

仅适用于支持 hold 支付的供应方

type

enum

instanthold

否

默认值为 instant。仅当所选供应方支持时才适用 hold

成功响应

返回 order identifiers, status and provider booking payload.

响应体结构

orderId

string是

holdExpiresAt

string

Format: ISO 8601

否

holdPriceGuaranteed

string否

liveMode

boolean是

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

集成说明

Public booking always requires a tracked snapshot of the selected public offer for the same profile, gdsprovider and offerId.
passengers[].id is the passenger id from the tracked offer, not an internal user identifier.
passengers[].id and passengers[].type must exactly match the tracked offer passengers. Empty ids, duplicates, missing passengers, extra passengers or type mismatches are rejected.
Mystifly public offers generate internal passenger ids such as mystifly_pax_1, mystifly_pax_2, etc. Reuse those ids exactly as returned by the offer.
不要发送内部用户标识；它们不属于公共预订合同。
公共预订不要发送 originalPrice。API 会从 offerId 或已跟踪的报价 payload 解析内部价格和币种。如果发送 originalPrice，公共校验会将其作为非白名单字段拒绝。
当报价或 required-fields 端点指示需要身份证件时，发送 identity_documents[]。
type=hold and holdId only apply when the selected booking flow supports hold payment.
仅当所选预订流程需要航段元数据时才需要 totalSegments[]。请从每个 offer.slices[].segments[] item 构建。

required-fields 到 create-order 的映射

required-fields 响应	create-order 字段	说明
`passengers[].title`	`passengers[].title`	直接匹配
`passengers[].type`	`passengers[].type`	直接匹配
`passengers[].name`	`passengers[].firstName`	在预订 body 中重命名
`passengers[].lastName`	`passengers[].lastName`	直接匹配
`passengers[].gender`	`passengers[].gender`	直接匹配
`passengers[].bornDate`	`passengers[].bornDate`	直接匹配
`passengers[].nationality`	`passengers[].country`	使用 2 位 ISO 国家代码
`passengers[].phone`	`passengers[].phone_number`	E.164 格式
`passengers[].email`	`passengers[].email`	在 gdsprovider=1 流程中，只有第一位旅客的 email 会作为 holder email 使用
`passengers[].documentIdentifier`	`passengers[].identity_documents[].unique_identifier`	仅在需要证件对象时
`passengers[].documentType`	`passengers[].identity_documents[].type`	受 `allowedDocuments` 限制
`passengers[].documentExpiresAt`	`passengers[].identity_documents[].expires_on`	仅在需要时
`passengers[].documentCountryCode`	`passengers[].identity_documents[].issuing_country_code`	仅在需要时
`passengers[].allowedDocuments`	`passengers[].identity_documents[].type`	如果包含 `dni`，还需要收集 `passengers[].NationalID`
`holder.phone`	`passengers[0].phone_number`	某些流程会从第一位旅客派生 holder 联系信息
`holder.email`	`passengers[0].email`	某些流程会从第一位旅客派生 holder 联系信息
`holder.countryCode`	由 `passengers[0].phone_number` 派生	没有单独的预订字段；使用 E.164 电话前缀

通用标记 age、address、city、postalCode 和 documentIssuedAt 当前不会映射到明确的公共预订字段。

嵌套旅客 payload

json

{
  "identity_documents": [
    {
      "type": "passport",
      "unique_identifier": "X1234567",
      "issuing_country_code": "ES",
      "expires_on": "2030-12-31"
    }
  ],
  "loyaltyProgrammeAccounts": [
    {
      "airlineIataCode": "BA",
      "accountNumber": "123456789"
    }
  ]
}

totalSegments 示例

json

[
  {
    "originCode": "MAD",
    "destinationCode": "BCN",
    "flightNumber": "1234",
    "departureDate": "2026-08-20T08:15:00"
  }
]

`totalSegments`	来源于 `offer.slices[].segments[]`
`originCode`	`segment.departure.iataCode`
`destinationCode`	`segment.arrival.iataCode`
`flightNumber`	`segment.flightNumber`
`departureDate`	`segment.departure.departingAt`

示例

bash

curl -X POST https://api.sandbox.travelandz.com/v1/flights/order/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 '{"currency":"EUR","type":"instant","passengers":[{"id":"pas_0001","type":"adult","title":"mr","phone_number":"+34612345678","firstName":"John","lastName":"Doe","gender":"m","email":"john.doe@example.com","bornDate":"1990-01-15","country":"ES"}]}'

请求体 - 示例

json

{
  "currency": "EUR",
  "passengers": [
    {
      "id": "pas_0000B7VCW4ca7emwcBOyUf",
      "type": "adult",
      "title": "mr",
      "phone_number": "+573128837058",
      "firstName": "Alejandro",
      "lastName": "Toledo",
      "gender": "m",
      "email": "jairotoledo2003@gmail.com",
      "bornDate": "2003-08-14"
    }
  ],
  "type": "instant"
}

响应

状态码	说明
`200`	Flight order created successfully.
`400`	请求无效：payload 不合法。
`401`	未授权：凭证无效或缺失。
`403`	禁止访问：凭证无效。
`500`	服务器内部错误

200 响应体

媒体类型：application/json

json

{
  "orderId": "ord_0000B7VCdoZtPDdnjqCYIe",
  "liveMode": false
}