GET/v1/transfers/tracking/:reservationId/events/stream

流式获取接送跟踪事件

通过 Server-Sent Events（SSE）持续接收车辆位置和行程状态。

认证和请求头

请求头	说明
`Authorization`	`Bearer <secret_key>`。密钥只能保存在服务器端，不能写入客户端日志。
`X-Travelandz-Id`	`<public_key>:<profile_code>`，持久化的 profile code 格式为 `dp_<12 位字母数字>`。
`LANG`	推荐的语言请求头，也支持 `Accept-Language`。
`Accept`	渐进式 stream 响应使用 `text/event-stream`。

响应头

http

Content-Type: text/event-stream
Cache-Control: no-cache, no-transform
Connection: keep-alive

请求

此端点不接收请求体，参数与最新事件端点相同。请发送 Accept: text/event-stream。连接打开时确定的语言会用于后续所有事件。

请求参数结构

reservationId

string是

Reservation identifier returned when the booking was created.

请求查询参数模式

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.

成功响应

每个 update 事件的负载与最新事件端点相同。

响应体结构

location

object是

locationlatitude

number否

locationlongitude

number否

status

string否

Journey state, for example driver_departed_to_pickup.

timestamp

string

格式: ISO 8601

否

trackingId

string否

流事件

事件	说明
`update`	刷新后的快照。请用最新事件的负载替换当前展示的内容。
`error`	某次刷新未能完成。包含 `code` 和 `message`。连接不会自动关闭，下一次刷新可能成功。

流示例

text

event: update
data: {"location":{"latitude":40.7607634,"longitude":-73.971212},"status":"driver_departed_to_pickup","timestamp":"2026-07-25T17:47:01.761854Z","trackingId":"c90n51960f274447b29473fc0d995f6a"}

event: error
data: {"code":"transfer_provider_error","message":"Unable to load tracking data"}

错误

HTTP	代码	含义	建议操作
`400`		请求体、查询参数或路径无效，或包含未知属性。	根据 `message` 数组修正请求。
`400`	`transfer_invalid_currency`	该货币不在支持列表中。	使用受支持的货币。
`400`	`transfer_invalid_language`	请求的语言不受支持。	使用文档中列出的语言值之一。
`429`	`transfer_provider_error`	服务暂时被限流。	使用指数退避重试。
`502`	`transfer_provider_error`	请求无法完成。	不要假定成功。保留标识符，并在该操作可能已创建时查询预订。

使用说明

仅在旅客查看实时视图时保持连接，之后请显式关闭。请同时处理 update 和 error 事件，并在网络中断后重新连接。

流打开前的验证失败会以普通 JSON HTTP 错误返回；流打开之后，失败以 error 事件返回。

cURL 示例

bash

curl --request GET \
  --url "https://api.sandbox.travelandz.com/v1/transfers/tracking/f390daff1fdf4cccb19b7abd825dc011/events/stream?currency=USD" \
  -H "Authorization: Bearer $TRAVELANDZ_SECRET_KEY" \
  -H "X-Travelandz-Id: $TRAVELANDZ_PUBLIC_KEY:$TRAVELANDZ_PROFILE_CODE" \
  -H "Accept: text/event-stream"