1.简介
本文档旨在为DHL客户提供清晰的API对接在线操作指南,协助您高效地使用DHL API完成下单等操作。
2.D-connector系统
D-Connector 是DHL为客户提供的密钥管理平台,用于获取身份认证所需的 APP Key 与 App Secret。每位客户的APP Key均唯一,请妥善保管,切勿泄露。
2.1 访问地址
D-Connector 正式环境系统网址为:https://dconnector.dhl.com/
2.2 D-connector账号信息
2.2.1 测试账号
在未申请正式账号前,PI团队<cn.pi_support@dhl.com>会向您提供测试环境的API credentials信息,您可使用以下测试账号进行对接开发。
测试账号:
"pickupAccountId":"HKCYL001",
"soldToAccountId":"HKCYL001"
2.2.2 正式账号
完成测试环境对接后,如需正式账号,请按以下流程操作:
申请: 将用于注册的邮箱地址提供至
CN.PI_Support@dhl.com。审核: 账号创建流程约为1-2个工作日,请在正式发货前提早申请。
激活与维护: 账号开通后,系统将自动发送账号信息。根据DHL IT安全政策,用户需每90天至少登录一次D-Connector系统以保持账号活跃,系统会提前邮件提醒。为避免因账号锁定导致下单失败,请务必按时登录。
2.3 查看身份认证信息
登录D-Connector系统后,通过左侧导航栏 Open API > Open API Info 进入信息页面。此处可查看您专属的 APP Key 和 App Secret,这是调用所有DHL API的关键凭证,请务必妥善保管。
APP Key 对应
token API中的client_id参数。APP Secret 对应
token API中的client_secret参数。点击 Regenerate Secret 可生成新的APP Secret,但APP Key保持不变。
3.查阅接口文档
3.1 接口文档下载及API URL
测试环境与正式环境的服务地址不同,根据您所使用的环境选择对应的基地址(Base URL),在调用任何业务接口之前,必须首先请求 token API 接口,以获取有效的身份认证凭证。
token URL:
| 测试环境URL | https://dconnector-test.dhl.com/api/dvt/open/api/v1/token |
|---|---|
| 正式环境URL | https://dconnector.dhl.com/api/dvt/open/api/v1/token |
下单接口基地址:
| 测试环境URL | https://dconnector-test.dhl.com/api/dvt/open/api/v1/****** |
|---|---|
| 正式环境URL | https://dconnector.dhl.com/api/dvt/open/api/v1/****** |
其余接口基地址:
| 测试环境URL | https://dconnector-test.dhl.com/api/open/api/v2/****** |
|---|---|
| 正式环境URL | https://dconnector.dhl.com/api/open/api/v2/****** |
3.2 查看API结构
点击API区域(标记1处)开始在线编辑。
在示例框(标记2处)查看API请求案例。
在模型结构(标记3处)查看各字段的必填性、数据类型及详细描述。
3.3在线测试获取身份认证
找到
Token API部分,点击第二个API的展开按钮(标记1处)。点击 "Try it out" 按钮(标记2处)开启编辑。
在参数表中填入从D-Connector获取的 APP Key (
client_id) 和 APP Secret (client_secret)(标记3处)。点击 "Execute"(标记4处)发送请求以获取Token。
在响应体(标记5处)中复制获取到的Token。
6. 在 "servers" 下拉列表(标记6处)中选择请求的地址。例如,进行在线测试时,请选择测试环境地址:https://dconnector-test.dhl.com/api - DConnector TEST Environment
7. 完成Token获取后,在页面右上角点击 "Authorize" 按钮(标记7处),在弹出的认证对话框中,将获取到的Token值粘贴至指定字段(如不是swagger在线测试,格式通常为 Bearer <您的Token>),以完成全局身份认证。
3.4 在线测试
重要提示: 在正式环境中操作API将产生真实业务数据,请务必谨慎。所有功能测试应在测试环境中完成。
以下单API为例:
点击 "Try it out" 开始在线编辑。
2. 在 "Edit Value" 字段中,参考案例格式填写或修改测试数据。
注意: 在 Swagger 在线工具中进行测试时,请求数据字段中请勿使用 // 或 /* */ 注释。因为该工具不支持此注释语法,会导致请求失败并报错。
3. 填写完测试数据后,点击 "Execute" 发送请求。
4. 在 "Server response" 部分查看返回结果。
————返回200代表请求成功
————返回其它代码,代表请求失败,请参考返回报文提示进行修改,如对返回报文有疑问,请咨询CN.PI_Support@dhl.com