17track 是知名的跨境物流查询平台，与17track API对接后同步快递派送信息，麦哲伦跨境物流管理系统已经对接17track。

开发文档

获取API访问密钥

通过登录管理控制台->设置->访问密钥获取；如果需要更换密钥，可以直接操作“更换密钥”，更换后的新密钥生效时间会有最长5分钟的延迟，新的密钥生效后，旧的密钥立即失效。

API地址

API地址：https://api.17track.net/track/v1

数据请求

所有API接口统一采用http(s) POST方式提交请求，请求和响应数据均使用UTF-8编码的JSON格式。所有请求基地址均以http(s)://api.17track.net/track/v1/开始。
所有请求都需要将密钥作为请求头一起提交，头名称为17token，如下所示(注册单号请求)：

curl -X POST 
    --header '17token:your secret key'
    --header 'Content-Type:application/json'
    --data '[{"number":"RR123456789CN"}]'
    https://api.17track.net/track/v1/register

数据封装

{    "code": 0,    "data": {        "accepted":[],        "rejected":[]
    }
}

响应结果采用统一的数据封装格式，说明如下；

响应状态

HTTP状态码

错误状态码

错误状态码是在http状态码返回的基础上，对数据处理结果的具体表示

参数格式

跟踪单号：跟踪单号必须是连续的5到50个字母和数字的组合。
运输商：运输商代码必须是有效的运输商Key，具体可参考运输商编码

基础信息

运输商编码

访问 https://www.17track.net/zh-cn/apicarrier 获取当前支持的所有可用运输商，由于我们在持续增加更多的运输商，所以请定期更新。使用到运输商代码的相关的接口均使用我们自己定义的运输商信息中的编码“Key”来进行提交。

国家地区编码

通过访问 https://www.17track.net/zh-cn/apicountry 获取最新的国家地区编码，在查询跟踪信息或者收到推送信息后需要通过该编码表查询发件国家地区和目的国家地区编码所对应实际国家地区。

包裹状态

查询状态

跟踪信息

跟踪信息扩展

事件信息

注意事项

所有接口请求的跟踪单号都需要先通过register接口进行注册；
所有接口请求限制频率为3req/s，后续可能会根据实际情况进行调整；
相同的跟踪单号和运输商多次提交只算一个额度，到期删除后再提交会再重新计算额度；
系统将自动停止跟踪连续30日无事件更新或者签收后15日无事件更新的单号；
系统对于停止跟踪的单号会继续保留90天，到期后会物理删除对应的数据；
对停止跟踪的单号有一次机会可以重新激活继续进行跟踪；

API接口参考（v1.0）

注册运单

该接口每次可提交注册40个跟踪单号
POST /register
请求数据示例：

[
    {        "number": "RR123456789CN",        "carrier": 3011,        "final_carrier":0,        "auto_detection":false,        "tag": "MyId"
    },
    {        "number": "1234"
    }
]

请求参数说明:

响应结果示例：

{    "code": 0,    "data": {        "accepted": [
            {                "origin": 1,                "number": "RR123456789CN",                "carrier": 3011
            }
        ],        "rejected": [
            {                "number": "1234",                "error": {                    "code": -18010012,                    "message": "The format of '1234' is invalid."
                }
            }
        ]
    }
}

响应结果说明:

修改运输商

用于修运第一运输商和尾程运输商，该接口每次可提交修改40个跟踪单号
POST /changecarrier
请求数据示例：

[
    {        "number": "RR123456789CN",        "carrier_old": 3011,        "carrier_new": 3013,        "final_carrier_old": 0,        "final_carrier_new": 0
    }
]

请求参数说明:

响应结果示例：

{    "code": 0,    "data": {        "accepted": [
            {                "number": "RR123456789CN",                "carrier": 3013
            }
        ],        "rejected": []
    }
}

响应结果说明:

修改信息

用于修改和跟踪相关的附属信息
POST /changeinfo
请求数据示例：

{    "number": "LW503511611CN",    "carrier":3011,    "items": {        "tag": "This is my order id."
    }
}

请求参数说明:

响应结果示例：

{    "code": 0,    "data": {        "accepted": [
            {                "number": "LW503511611CN",                "carrier": 3011
            }
        ],        "rejected": []
    }
}

响应结果说明:

停止跟踪

该接口每次可提交40个跟踪单号
POST /stoptrack
请求数据示例：

[
    {        "number": "RR123456789CN",        "carrier": "3011"
    }
]

请求参数说明:

响应结果示例：

{    "code": 0,    "data": {        "accepted": [
            {                "number": "RR123456789CN",                "carrier": "3011"
            }
        ]
    }
}

响应结果说明:

重启跟踪

该接口每次可提交40个跟踪单号
POST /retrack
请求数据示例：

[
    {        "number": "RR123456789CN",        "carrier": "3011"
    }
]

请求参数说明:

响应结果示例：

{    "code": 0,    "data": {        "accepted": [
            {                "number": "RR123456789CN",                "carrier": "3011"
            }
        ]
    }
}

响应结果说明:

获取列表

查询注册单号列表信息
POST /gettracklist
请求数据示例：

{    "number": "RR123456789CN",    "carrier": 3011,    "register_time_from": "2019-01-01 12:24:00",    "register_time_to": "2019-02-01",    "tracking_time_from": "2019-01-01",    "tracking_time_to": "2019-12-01",    "push_time_from": "2019-01-01",    "push_time_to": "2019-12-01",    "push_state": 0,    "stop_time_from": "2019-01-01",    "stop_time_to": "2019-12-01",    "package_state": 10,    "tracking_state": 0,    "page_no": 1}

请求参数说明:

响应结果示例：

{    "code": 0,    "data": {        "accepted": [
            {                "number": "RV929123748CN",                "w1": 3011,                "b": 301,                "w2": 10011,                "c": 1001,                "e": 20,                "rt": "2019-08-26 09:48:16",                "tt": "2020-01-16 02:52:11",                "pt": "2019-11-08 06:16:25",                "ps": 200,                "st": "2020-02-28 02:36:59",                "sr": 1,                "ir": true,                "ts": false,                "mc": 0,                "tag": null
            }
        ]
    }
}

响应结果说明:

获取详情

该接口每次可提交40个跟踪单号
POST /gettrackinfo
请求数据示例：

[
    {        "number": "RR123456789CN",        "carrier": "3011"
    }
]

请求参数说明:

响应结果示例：

{    "code": 0,    "data": {        "accepted": [
            {                "number": "RM101474005CN",                "tag": "",                "track": {                    "b": 301,                    "c": 1803,                    "e": 10,                    "f": -1,                    
                    "w1": 3011,                    "w2": 18031,                    
                    "z1": [
                        {                            "a": "2015-05-13 14:47",                            "b": null,                            "c": "",                            "d": "",                            "z": "电子信息已收到"
                        }
                    ],                    "z2": [
                        {                            "a": "2015-05-31 00:00",                            "b": null,                            "c": "",                            "d": "",                            "z": "Distribué ANDORRE LA VIEILLE (09)."
                        }
                    ],                    "z9": [],                    "ygt1": 370,                    "ygt2": 0,                    "ygt9": 0,                    "is1": 1,                    "is2": 0,                    "ln1": "zh-CHS",                    "ln2": null,                    "ln9": null,                    "hs": 627236210,                    "z0": {                        "a": "2015-05-29 09:00",                        "b": null,                        "c": "BLAGOVESCH 1",                        "d": "",                        "z": "移交海关"
                    },                    "ylt1": "2015-06-01 20:44:52",                    "ylt2": "2079-01-01 00:00:00",                    "ylt9": "2079-01-01 00:00:00",                    "yt": "",                    "zex": {                        "trN": "",                        "trC": 0,                        "psex": 0,                        "dt": 1586726160000,                        "dtS": 1586726160000,                        "dtP": 0,                        "dtD": 0,                        "dtL": 1588846740000
                    }
                }
            }
        ]
    }
}

响应结果说明:

Webhook

设置

通过登录管理控制台->设置->WebHook设置回调接口Url，如果不设置，将不会进行通知；

通知策略：如果通知的Webhook URL返回http状态码200表示已被正常处理将不会进行重试，否则都会认为本次通知失败。通知失败后会依次尝试分别在其后的第10分钟、第30分钟、第60分钟后进行重试，如果仍然不能正常通知，将放弃对应单号当前的变更通知，但是不会影响其后续的变更通知；

数据及签名

当跟踪事件有更新或者根据策略不再对单号进行跟踪时时，系统会产生一个POST请求发送到你在设置页面设置的回调url上。推送数据格式统一采用如下格式：

{    "sign": "a829f039332706b9b888eba84b77bd01f425ed327d2c4a92b50bba5beb0a0260",    "event": "TRACKING_STOPPED",    "data": {        "number": "RM101474005CN",        "carrier":3011,        "tag":""
    }
}

数据格式

|Name|Description| |sign|数据签名| |event|推送类型，目前暂时只提供;TRACKING_STOPPED：停止跟踪通知;TRACKING_UPDATED：跟踪信息更新通知，当跟踪的单号事件有变更时，会推送最新的跟踪信息| |data|推送的数据，会根据event不同而不同|

签名验证

为了确保消息来源的身份是17TRACK推送的，最好对接收到的数据进行签名验证。验证时将event、data的值和API访问密钥通过右斜杠拼接event/data/secretkey，然后计算SHA256；如果计算出的结果和sign一致，则表示消息来源合法有效。

签名举例

推送通知的数据统一采用UTF-8编码的JSON数据格式，对接收到的原始数据（不需要进行任何格式化、空格和换行等处理）进行解析，比如收到的数据是：{"sign":"a829f039332706b9b888eba84b77bd01f425ed327d2c4a92b50bba5beb0a0260","event":"TRACKING_STOPPED","data":{"number":"RM101474005CN","carrier":3011}}，则解析结果为： event: TRACKING_STOPPEDdata: {"number":"RM101474005CN","carrier":3011,"tag":""}如果secretkey为 6A8D7CFC3F7A41149E0A4EE8ABD0DD8A，则待签名的数据为：TRACKING_STOPPED/{"number":"RM101474005CN","carrier":3011,"tag":""}/6A8D7CFC3F7A41149E0A4EE8ABD0DD8A，将此数据经过SHA256并采用十六进制编码，如果计算的结果和sign一致，则表示数据合法有效。

通知类型

停止跟踪

{    "sign": "a829f039332706b9b888eba84b77bd01f425ed327d2c4a92b50bba5beb0a0260",    "event": "TRACKING_STOPPED",    "data": {      "number": "RM101474005CN",      "carrier": 3011,      "tag":""
    }
}

事件更新

{    "sign": "34f40c8fc37f9a7100c65215b0df85c58cc4880cf2e832fe91c86de1bc00b181",    "event": "TRACKING_UPDATED",    "data": {        "number": "STOAA0000272952YQ",        "tag": "",        "track": {            "b": 301,            "c": 2105,            "e": 10,            "f": -1,            "w1": 190316,            "w2": 0,            "is1": 1,            "is2": 0,            "hs": 730243286,            "ln1": "en",            "ln2": null,            "ln9": "en",            "ygt1": 366,            "ygt2": 0,            "ygt9": 423,            "ylt1": "2020-05-11 12:05:58",            "ylt2": "2079-01-01 00:00:00",            "ylt9": "2020-05-11 12:05:58",            "yt": "",            "z0": {                "a": "2020-05-07 10:19",                "b": null,                "c": "",                "d": "BLOOMINGTON, CA 92316",                "z": "Departed Shipping Partner Facility, USPS Awaiting Item -> Your item departed a shipping partner facility at 10:19 am on May 7, 2020 in BLOOMINGTON, CA 92316. This does not indicate receipt by the USPS or the actual mailing date."
            },            
            "z1": [
                {                    "a": "2020-05-07 10:19",                    "b": null,                    "c": "",                    "d": "BLOOMINGTON, CA 92316",                    "z": "Departed Shipping Partner Facility, USPS Awaiting Item -> Your item departed a shipping partner facility at 10:19 am on May 7, 2020 in BLOOMINGTON, CA 92316. This does not indicate receipt by the USPS or the actual mailing date."
                },
                {                    "a": "2020-05-05 16:49",                    "b": null,                    "c": "",                    "d": "BLOOMINGTON, CA 92316",                    "z": "Arrived Shipping Partner Facility, USPS Awaiting Item"
                },
                {                    "a": "2020-04-12 21:16",                    "b": null,                    "c": "",                    "d": "FREMONT, CA 94538",                    "z": "Picked Up by Shipping Partner, USPS Awaiting Item"
                }
            ],            "z2": [],            "z9": [
                {                    "a": "2020-04-13 17:07",                    "b": null,                    "c": "China, Shenzhen",                    "d": "",                    "z": "Item inbound in sorting center."
                },
                {                    "a": "2020-04-13 17:02",                    "b": null,                    "c": "China, Shenzhen",                    "d": "",                    "z": "Item accepted."
                }
            ],            
            "zex": {                "trN": "92612927005099010009150135",                "trC": 21051,                "psex": 0,                "dt": 1586726160000,                "dtS": 1586726160000,                "dtP": 0,                "dtD": 0,                "dtL": 1588846740000
            }
        }
    }
}