1. 使用流程
Track123的API接口使用流程分为下面4个步骤
2. 请求
所有可传递参数的请求，均使用HTTP Post，请求参数为JSON格式的HTTP Body。
协议
所有请求基于HTTPS协议进行传输。
基础链接
https://api.track123.com/gateway/open-api/
请求头
所有请求的头部都必须包含名为 Track123-Api-Secret 的键，其值为在系统生成的API秘钥 。
请求头中 Content-Type 对应值必须为 application/json，Content-Type 默认提供 UTF-8 格式的字符集参数，其他编码格式都不支持。（比如ISO-8859-1）
3. 响应
Track123的响应内容为JSON格式。
每个响应对象，都包含“code”和 “msg”字段，如果接口有返回值，还会包含“data”字段。
Code
code字段为业务状态码，标识业务执行的结果。
Msg
对业务业务状态码对应的描述信息或者其他辅助的描述信息
Data
实际返回的业务对象
4. 状态码
HTTP状态码
Track123使用HTTP状态码来标记请求在协议层面的状态。
| 状态码 | 类型 | 描述 |
|---|
| 200 | Success | 请求成功 |
| 400 | Bad Request | 请求类型错误，比如请求参数不正确 |
| 500 | Server Error | 服务器出现异常，请联系客服 |
查询状态码
Track123运单使用不同的查询状态码标识运单查询的状态。
| 查询状态码 | 类型 | 描述 |
|---|
| 001 | NORMAL_QUERY | 查询正常 |
| 002 | NO_RECORD | 查无轨迹 |
| 003 | UNSTABLE_OFFICIAL_WEBSITE | 物流商官网不稳定 |
| 004 | OFFICIAL_WEBSITE_FORMAT_CHANGES | 物流商官网格式变化，待修复 |
| 005 | CACHE_FOR_WEBSITE_ERROR | 物流商不稳定，使用历史缓存 |
| 006 | CACHE_FOR_DEAL_ERROR | 查询发生异常，使用历史缓存 |
业务状态码
Track123使用业务状态码（即响应对象中的code字段）来标记请求在业务层面的状态
| 状态码 | 类型 | 描述 |
|---|
| 00000 | SUCCESS | 成功 |
| A0001 | USER_ERROR | 用户端错误 |
| A0200 | USER_LOGIN_ERROR | 服务器出现异常，请联系客服 |
| A0201 | USER_NOT_EXIST | 用户不存在 |
| A0202 | USER_ACCOUNT_LOCKED | 用户账户被冻结 |
| A0203 | USER_ACCOUNT_INVALID | 服务器出现异常，请联系客服 |
| A0230 | TOKEN_INVALID_OR_EXPIRED | token无效或已过期 |
| A0231 | TOKEN_ACCESS_FORBIDDEN | token已被禁止访问 |
| A0300 | AUTHORIZED_ERROR | 访问权限异常 |
| A0301 | ACCESS_UNAUTHORIZED | 访问未授权 |
| A0400 | PARAM_ERROR | 用户请求参数错误 |
| A0410 | PARAM_IS_NULL | 请求必填参数为空 |
| B0001 | SYSTEM_EXECUTION_ERROR | 系统执行出错 |
| B0100 | SYSTEM_EXECUTION_TIMEOUT | 系统执行超时 |
| B0100 | SYSTEM_ORDER_PROCESSING_TIMEOUT | 系统订单处理超时 |
| B0210 | FLOW_LIMITING | 系统限流 |
| B0300 | SYSTEM_RESOURCE_ERROR | 系统资源异常 |
| B0310 | SYSTEM_RESOURCE_EXHAUSTION | 系统资源耗尽 |
| C0113 | INTERFACE_NOT_EXIST | 接口不存在 |
| D0000 | Server Error | 其他错误，将在msg或data中返回详细信息 |
5. 快递物流状态
| 状态码 | 类型 | 描述 |
|---|
| INIT | 待查询 | 单号正在查询中，请等待 |
| NO_RECORD | 暂无信息 | 包裹无法查询到物流轨迹信息 |
| INFO_RECEIVED | 已接收 | 物流公司已经收到寄运订单，正在准备揽收包裹 |
| IN_TRANSIT | 运输中 | 包裹正在运输途中 |
| WAITING_DELIVERY | 派送中 | 包裹正在派送或已到达代收点等待收件人自提 |
| DELIVERY_FAILED | 投递失败 | 包裹尝试派送，但由于地址问题、收件人联系不上等原因导致派送失败 |
| ABNORMAL | 异常 | 包裹出现破损、退件、海关扣留等异常情况 |
| DELIVERED | 已成功 | 包裹投递成功 |
| EXPIRED | 已过期 | 包裹在最近的30天没有任何物流更新 |
已接收子状态
| 状态 | 描述 |
|---|
| INFO_RECEIVED_01 | 物流公司已经收到寄运订单，正在准备揽收包裹 |
运输途中子状态
| 状态 | 描述 |
|---|
| IN_TRANSIT_01 | 运输途中，包裹正在运输途中 |
| IN_TRANSIT_02 | 包裹已到达分拣中心 |
| IN_TRANSIT_03 | 包裹清关完成 |
| IN_TRANSIT_04 | 封发，包裹已经封装完成，即将送往机场 |
| IN_TRANSIT_05 | 交航，包裹已经交给航空公司，即将或正在飞往目的国 |
| IN_TRANSIT_06 | 落地，包裹已经到达目的国家 |
| IN_TRANSIT_07 | 包裹已到达当地的邮局或快递网点，即将安排派送 |
| IN_TRANSIT_08 | 航班已从机场起飞 |
到达待取子状态
| 状态 | 描述 |
|---|
| WAITING_DELIVERY_01 | 包裹正在派送中或即将进行派送 |
| WAITING_DELIVERY_02 | 包裹已到达自提点，等待收件人上门自提包裹 |
| WAITING_DELIVERY_03 | 收件人请求延迟派送或快递商在派送失败后留下便签等待第二次派送 |
签收成功子状态
| 状态 | 描述 |
|---|
| DELIVERED_01 | 包裹投递成功 |
| DELIVERED_02 | 收件人去代收点自提成功 |
| DELIVERED_03 | 包裹由收件人签字签收 |
| DELIVERED_04 | 包裹放至快递柜，或由物业、门卫、家人、邻居代收 |
投递失败子状态
| 状态 | 描述 |
|---|
| DELIVERY_FAILED_01 | 由于地址相关问题，导致派送失败 |
| DELIVERY_FAILED_02 | 由于收件人不在家，导致派送失败 |
| DELIVERY_FAILED_03 | 由于无法联系到收件人，导致派送失败 |
| DELIVERY_FAILED_04 | 由于其他的原因，导致派送失败 |
可能异常子状态
| 状态 | 描述 |
|---|
| ABNORMAL_01 | 包裹无人认领 |
| ABNORMAL_02 | 包裹被海关扣留 |
| ABNORMAL_03 | 包裹破损、遗失或被丢弃 |
| ABNORMAL_04 | 订单在揽件前被取消 |
| ABNORMAL_05 | 收件人拒收包裹 |
| ABNORMAL_06 | 包裹已退回发件人处 |
| ABNORMAL_07 | 包裹正在被退回发件人的途中 |
| ABNORMAL_08 | 其他异常情况 |
6. 海运物流状态
查询状态
| searchStatus | 描述 |
|---|
| INIT | 待查询 |
| IN_TRANSIT | 非终态 |
| FINAL | 终态 |
| NO_RECORD | 查询不到 |
| EXPIRED | 过期 |
运输状态
| transitStatus | 描述 |
|---|
| NO_RECORD | 查询不到 |
| IN_TRANSIT | 运输中 |
| DELIVERED | 已送达 |
| EXPIRED | 已过期 |
轨迹状态
| eventStatus | 描述 |
|---|
| STUF | 提箱 |
| STRP | 还箱 |
| LOAD | 装货 |
| DISC | 卸货 |
| GTOT | 出场 |
| GTIN | 进场 |
| DEPA | 离港 |
| ARRI | 到港 |
| BERT | 靠泊 |
| HOLD | 查验 |
| CUST | 海放 |
| RELS | 码放 |
| UNKNOWN | 未知 |
发生地类型
| locationType | 描述 |
|---|
| PRE | 接货地 |
| POL | 起运港 |
| POT | 中转港 |
| POD | 目的港 |
| PDE | 交货地 |
7. 空运物流状态
查询状态
| aviationTransitStatus | 描述 |
|---|
| INIT | 待查询 |
| BOOKED | 订舱 |
| RECEIVED | 收运 |
| IN_TRANSIT | 运输中 |
| ARRIVED | 到达 |
| NOTIFIED | 通知取货 |
| DELIVERED | 已取货 |
| EXCEPTION | 异常 |
| NO_RECORD | 查询不到 |
| EXPIRED | 过期 |
轨迹状态
| status | 描述 |
|---|
| BOOKED | 订舱 |
| RECEIVED | 收运 |
| IN_TRANSIT | 运输中 |
| ARRIVED | 到达 |
| NOTIFIED | 通知取货 |
| DELIVERED | 已取货 |
| EXCEPTION | 异常 |