通过 Travelandz 公共 API 搜索、定价、预订和退款火车行程。
基础路径
所有公共火车操作都位于 /v1/trains 下。目前可用的供应方是 gdsprovider=0。
认证
每个请求都需要 Authorization: Bearer <secret_key> 和 X-Travelandz-Id: <public_key>:<profile_code>。持久化 profile code 格式为 dp_<12 位字母数字>；secret 必须保存在服务器端。
协议约定
- JSON 端点成功时返回
200 OK。 - POST 请求使用
Content-Type: application/json。 - 日期使用
YYYY-MM-DD，金额使用{ amount, currency }。 - body 或 query 中的未知字段会返回
400。 - 流式端点返回换行分隔的 JSON（NDJSON），而不是单个 JSON 文档。
工作流
- 搜索地点，再使用地点 id 搜索行程。
- 保存
journeyId，为选中的行程请求报价。 - 保存一个或多个
offerId，创建预订。 - 使用
bookingId查询必填字段并创建订单。 - 保存
orderId，请求退款前先查询可退款项目。
端点目录
| Method | Path | 用途 |
|---|---|---|
GET | /v1/trains/locations | 搜索车站和地点。 |
POST | /v1/trains/journeys | 搜索行程。 |
POST | /v1/trains/journeys/stream | 以 NDJSON 流搜索行程。 |
POST | /v1/trains/journeys/:gdsprovider/:journeyId/offers | 获取行程报价。 |
POST | /v1/trains/journeys/:gdsprovider/:journeyId/offers/stream | 以流获取行程报价。 |
POST | /v1/trains/book/:gdsprovider/prebook | 创建预订。 |
GET | /v1/trains/book/:gdsprovider/:bookingId/required-fields | 获取预订必填字段。 |
POST | /v1/trains/book/:gdsprovider/:bookingId/order | 创建并确认订单。 |
GET | /v1/trains/order/:gdsprovider/:orderId | 获取订单和票据。 |
GET | /v1/trains/order/:gdsprovider/:orderId/refundable-items | 列出可退款项目。 |
POST | /v1/trains/order/:gdsprovider/:orderId/refund | 发起退款。 |
GET | /v1/trains/order/:gdsprovider/:orderId/refund | 获取退款状态。 |
通用枚举
| 字段 | 值 |
|---|---|
passengers[].type | youth、adult、senior |
passengers[].title | mr、ms、mx |
identityDocument.type | passport |
transport | train、bus、ferry |
flexibility | non_flex、semi_flex、full_flex |
order.status | pending、confirmed、cancelled |
refund.state | success、pending、error |