OpenAPI

基本要求

主动方式

接口地址

  1. 测试环境：http://cheetah.test.yunbaoguan.cn/api/openapi/
  2. 正式环境：https://sr.yunbaoguan.cn/api/openapi/

文档中描述的接口地址都是以相对路径表示，而完整路径则需要在前缀加上以上的接口地址。如 ping 地址，则表示

接口认证

任何HTTP接口调用，都需要附上一个认证头信息

Authorization: ACCESS_KEY xxxxxxxxx

AccessKey 可以在平台系统自助生成，或由平台方代为生成并通过客服告知应用方。

文档中调用例子会用<ACCESSKEY>表示需要用上一个有效的AccessKey。如：

$ curl -H 'Authorization: ACCESS_KEY <ACCESSKEY>' http://cheetah.test.yunbaoguan.cn/api/openapi/ping

{"corpId":"xxxxx","corpName":"XXXXX","user":"ACCESSKEY","currentTime":1622684170514}

应用可以使用如上 ping 地址测试认证头信息是否有效。

回调方式

回调相关条件

要接收平台发出的回调信息，要满足下面的要求：

  1. 应用系统需要在公网能通过HTTP访问，若是应用系统是内部系统，则需要通过某种技术手段，让应用系统的回调相关的HTTP接口暴露到公网能访问的状态
  2. 在平台系统中注册回调接口地址（开发者 -> 回调管理），并选择所需要的回调业务，和相关配置

回调报文通用格式

所有回调的报文会由通用格式进行封装，具体数据在payload中。通过HTTP POST请求，以JSON格式传递 (Content-Type: application/json)

在具体业务的接口文档中，将只描述payload中的数据规范，通用封装格式不再加以赘述。

一个回调的样本内容 (HTTP Request Body) 如下：

{
    "timestamp" : 1622691831675,
    "name" : "DEC_RECEIPT",
    "version" : "1.0",
    "payload" : {
        "timestamp" : 1622691831661,
        "status" : "P",
        "refNo" : "REFNO-001",
        "docId" : "100",
        "cusCiqNo" : null,
        "entryId" : null,
        "source" : "VGVzdGluZ0NhbGxiYWNr"
    }
}
属性 类型 说明
timestamp long 回调时间（Epoch微秒）
name String 回调服务名
version String 回调数据格式版本号
payload json 具体数据

在成功接收这个回执之后，应用应该立即返回HTTP状态200以表示成功接收。

回调重试机制

平台期望应用的返回HTTP状态嘛为200，若应用返回非200，则表示有错误。 回调接口若出现错误，平台会触发重试机制，默认重试10次，重试间隔最小5秒，最大160秒。

若对此成功状态的定义有不同，可以在平台回调管理中设置接口成功状态。

若需要对重试参数调整，也可以在平台回调管理中配置。

回调服务名

不同业务模块会在不同的时间产生不同的回调服务，具体的回调服务可以参考业务模块中有关回调服务的描述。

目前系统支持的回调服务，可以通过查询接口 callback 得到：

$ curl -H 'Authorization: ACCESS_KEY <ACCESSKEY>' http://cheetah.test.yunbaoguan.cn/api/openapi/callback

目前返回结果：

[
    {"key":"DEC_PDF","value":"报关单放行后回传PDF文件"},
    {"key":"DEC_DATA","value":"报关单数据回执"},
    {"key":"DEC_RECEIPT","value":"报关单海关状态回执"}
]