# 中国电子口岸（海口海关）报文加签API文档

Version | Update Time | Status | Author | Description
--- | --- | --- | --- | ---
1.0.0 | 2022-02-16 10:30 | 创建 | Weasley J | 创建API文档
1.0.9 | 2023-06-11 15:36 | 编辑 | Weasley J | 更新API文档
1.1.0 | 2023-07-15 15:36 | 编辑 | Weasley J | 补充API文档

## 1. 电子口岸报文加签测试

### 1.1. 海关总署XML数据加签

URL: http://localhost:8080/rpc/eport/test/cebmessage/signature

Type: GET

Author: lwj

Content-Type: application/x-www-form-urlencoded;charset=UTF-8

Description: 非正式调用API，只为了让你看到海关总署XML加密的数据返回格式

Request-headers:

| Header | Value | Type | Required | Description
--- | --- | --- | --- | --- | ---
| x-auth-token-eport-sign |  | string | true | 客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等

Response-fields:

Field | Type | Description | Since
--- | --- | --- | ---
message | string | 返回消息 | -
success | boolean | 是否成功 | -
timestamp | string | 响应时间戳 | -
code | int32 | 状态码 | -
data | object | 响应数据 | -
└─success | boolean | 本次加签是否成功 | -
└─certNo | string | 签名的ukey的卡序列号 | -
└─x509Certificate | string | 签名的ukey证书 | -
└─digestValue | string | XML报文的数字摘要 | -
└─signatureValue | string | 调用ukey获取的签名值 | -
└─signatureNode | string | XML报文的签名节点 用来组装 ds:SignedInfo 节点 | -

Response-example:

    {
      "message": "",
      "success": true,
      "timestamp": "",
      "code": 0,
      "data": {
        "success": true,
        "certNo": "",
        "x509Certificate": "",
        "digestValue": "",
        "signatureValue": "",
        "signatureNode": ""
      }
    }

Curl-example:

    curl -X GET -H 'x-auth-token-eport-sign:DefaultAuthToken' -i http://localhost:8080/rpc/eport/test/cebmessage/signature

### 1.2. 海关179数据抓取加签

URL: http://localhost:8080/rpc/eport/test/179/signature

Type: GET

Author: lwj

Content-Type: application/x-www-form-urlencoded;charset=UTF-8

Description: 非正式调用API，只为了让你看到179加密的数据返回格式

Request-headers:

| Header | Value | Type | Required | Description
--- | --- | --- | --- | --- | ---
| x-auth-token-eport-sign |  | string | true | 客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等

Response-fields:

Field | Type | Description | Since
--- | --- | --- | ---
message | string | 返回消息 | -
success | boolean | 是否成功 | -
timestamp | string | 响应时间戳 | -
code | int32 | 状态码 | -
data | object | 响应数据 | -
└─success | boolean | 本次加签是否成功 | -
└─certNo | string | 签名的ukey的卡序列号 | -
└─x509Certificate | string | 签名的ukey证书 | -
└─digestValue | string | XML报文的数字摘要 | -
└─signatureValue | string | 调用ukey获取的签名值 | -
└─signatureNode | string | XML报文的签名节点 用来组装 ds:SignedInfo 节点 | -

Response-example:

    {
      "message": "",
      "success": true,
      "timestamp": "",
      "code": 0,
      "data": {
        "success": true,
        "certNo": "",
        "x509Certificate": "",
        "digestValue": "",
        "signatureValue": "",
        "signatureNode": ""
      }
    }

Curl-example:

    curl -X GET -H 'x-auth-token-eport-sign:DefaultAuthToken' -i http://localhost:8080/rpc/eport/test/179/signature

### 1.3. 执行脚本命令

URL: http://localhost:8080/rpc/eport/test/endpoint/exec

Type: GET

Author: lwj

Content-Type: application/x-www-form-urlencoded;charset=UTF-8

Description: 此接口测试环境、生产环境不对外开放，会在将终端输出同步写给浏览器

Request-headers:

| Header | Value | Type | Required | Description
--- | --- | --- | --- | --- | ---
| x-auth-token-eport-sign |  | string | true | 客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等

Query-parameters:

| Parameter | Value | Type | Required | Description
--- | --- | --- | --- | --- | ---
| cmd |  | string | true | No comments found.

Response-example:

    Return void.

Curl-example:

    curl -X GET -H 'x-auth-token-eport-sign:DefaultAuthToken' -i http://localhost:8080/rpc/eport/test/endpoint/exec?cmd=

## 2. Ukey健康状态恢复

### 2.1. ukey健康指令

URL: http://localhost:8080/rpc/eport/ukey/health/endpoint/{command}

Type: POST

Author: lwj

Content-Type: application/x-www-form-urlencoded;charset=UTF-8

Description: <ul>
支持command类型
<li>RESTART: 重启控件(较多使用)</li>
<li>START: 启动控件</li>
<li>STOP: 停止控件</li>
<li>REPAIR: 修复证书</li>
</ul>

Request-headers:

| Header | Value | Type | Required | Description
--- | --- | --- | --- | --- | ---
| x-auth-token-eport-sign |  | string | true | 客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等

Response-fields:

Field | Type | Description | Since
--- | --- | --- | ---
message | string | 返回消息 | -
success | boolean | 是否成功 | -
timestamp | string | 响应时间戳 | -
code | int32 | 状态码 | -
data | object | 响应数据 | -
└─stdOutList | array | 标准输出流信息 | -
└─errorOutList | array | 错误输出流信息 | -

Response-example:

    {
      "message": "",
      "success": true,
      "timestamp": "",
      "code": 0,
      "data": {
        "stdOutList": [
          ""
        ],
        "errorOutList": [
          ""
        ]
      }
    }

Curl-example:

    curl -X POST -H 'x-auth-token-eport-sign:DefaultAuthToken' -i http://localhost:8080/rpc/eport/ukey/health/endpoint/{command}

## 3. 电子口岸报文推送

### 3.1. 推送CEBMessage报文

URL: http://localhost:8080/rpc/eport/upload/CEBMessage

Type: POST

Author: weasley

Content-Type: application/json

Description: <ul>
<b>支持JSON报文和XML报文</b>
<li>JSON报文: 无需组装XML结构报文</li>
<li>XML报文: 需组装XML结构的报文</li>
</ul>

Request-headers:

| Header | Value | Type | Required | Description
--- | --- | --- | --- | --- | ---
| x-auth-token-eport-sign |  | string | true | 客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等

Body-parameters:

Parameter | Type | Required | Description
--- | --- | --- | ---
messageType | enum | true | 消息类型 [Enum values: CEB311Message("CEB311Message") CEB621Message("CEB621Message") ]
dataType | enum | true | 报文的数据类型 [Enum values: JSON() XML() ]
- cebMessage | object | true | 进口单、出口单的底层数据模型 以CEB311Message数据类型为例 JSON示例
      {"order":{"orderHead":{"guid":"AFNC7T-WEASLEY-20230713095517-N04JEE","appType":"1","appTime":"20230704181028","appStatus":"2","orderType":"I","orderNo":"T_C5051511332138160010","ebpCode":"4601630004","ebpName":"海南省荣誉进出口贸易有限公司","ebcCode":"4601630004","ebcName":"海南省荣誉进出口贸易有限公司","goodsValue":"0.01","freight":"0","discount":"0","taxTotal":"0","acturalPaid":"0.01","currency":"142","buyerRegNo":"4","buyerName":"袁晓雨","buyerTelephone":"13701727375","buyerIdType":"1","buyerIdNumber":"130435200009241538","consignee":"袁晓雨","consigneeTelephone":"13701727375","consigneeAddress":"北京北京市东城区","note":"test"},"orderList":[{"gnum":1,"itemNo":"1","itemName":"LANNA兰纳","gmodel":"10片/包","itemDescribe":"","barCode":"1","unit":"011","qty":"1","price":"1","totalPrice":"1","currency":"142","country":"136","note":"test"}]},"guid":"AFNC7T-WEASLEY-20230713095517-N04JEE","version":"1.0","baseTransfer":{"copCode":"4601630004","copName":"海南省荣誉进出口贸易有限公司","dxpMode":"DXP","dxpId":"DXPENT0000530815","note":"test"}}
XML示例: 不带ds:Signature节点的CEBXxxMessage.xml原文;待加签xml报文样例

Request-body:

    {
      "messageType": "CEB311Message",
      "dataType": "JSON",
      "cebMessage": {
        "object": "any object"
      }
    }

Response-fields:

Field | Type | Description | Since
--- | --- | --- | ---
message | string | 返回消息 | -
success | boolean | 是否成功 | -
timestamp | string | 响应时间戳 | -
code | int32 | 状态码 | -
data | object | 响应数据 | -
└─payload | object | 请求数据载荷 | -
└─Message | object | No comments found. | -
└─MessageHead | object | No comments found. | -
└─MessageId | string | No comments found. | -
└─MessageType | string | No comments found. | -
└─SenderID | string | No comments found. | -
└─ReceiverID | string | No comments found. | -
└─SendTime | string | No comments found. | -
└─Version | string | No comments found. | -
└─MessageBody | object | No comments found. | -
└─data | string | No comments found. | -
└─original | string | 三方原始返回 | -
└─expected | string | 三方期望返回 | -

Response-example:

    {
      "message": "",
      "success": true,
      "timestamp": "",
      "code": 0,
      "data": {
        "payload": {
          "Message": {
            "MessageHead": {
              "MessageId": "",
              "MessageType": "",
              "SenderID": "",
              "ReceiverID": "",
              "SendTime": "",
              "Version": ""
            },
            "MessageBody": {
              "data": ""
            }
          }
        },
        "original": "",
        "expected": ""
      }
    }

Curl-example:

    curl -X POST -H 'Content-Type: application/json' -H 'x-auth-token-eport-sign:DefaultAuthToken' -i http://localhost:8080/rpc/eport/upload/CEBMessage --data '{
      "messageType": "CEB311Message",
      "dataType": "JSON",
      "cebMessage": {
        "object": "any object"
      }
    }'

### 3.2. 推送海关179号数据

URL: http://localhost:8080/rpc/eport/upload/179/data

Type: POST

Author: weasley

Content-Type: application/json

Description: <ul>
JSON示例:
<pre>
{
"sessionID": "032C3F56-0EE6-4558-B548-6C7A3451F07D",
"payExchangeInfoHead": {
"guid": "E4766021-21AC-1AA2-21DD-E974DF93C11D",
"initalRequest": "<xml><appid><![CDATA[xwxwxwxwx112121]]></appid><mch_id>11111111</mch_id><body><![CDATA[测试测试]]></body><nonce_str><![CDATA[ashdgahgdhaghgliqwueyqu1]]></nonce_str><out_trade_no>202009231454212140210352</out_trade_no><total_fee>500</total_fee><spbill_create_ip><![CDATA[192.168.0.1]]></spbill_create_ip><notify_url><![CDATA[https://www.baidu.com]]></notify_url><openid><![CDATA[adasyduiyasdhjxzycua-Q]]></openid><trade_type><![CDATA[JSAPI]]></trade_type><sign><![CDATA[asd1sa56d4545wqe44wq5]]></sign></xml>",
"initalResponse": "<xml><appid><![CDATA[xwxwxwxwx112121]]></appid><bank_type><![CDATA[OTHERS]]></bank_type><cash_fee>500</cash_fee><fee_type><![CDATA[CNY]]></fee_type><is_subscribe><![CDATA[N]]></is_subscribe><mch_id>11111111</mch_id><nonce_str><![CDATA[ashdgahgdhaghgliqwueyqu1]]></nonce_str><openid><![CDATA[adasyduiyasdhjxzycua-Q]]></openid><out_trade_no>202009231454212140210352</out_trade_no><result_code><![CDATA[SUCCESS]]></result_code><return_code><![CDATA[SUCCESS]]></return_code><sign><![CDATA[asgdhasgdhasgdhgasgdhasgdh]]></sign><time_end>20200923145426</time_end><total_fee>500</total_fee><trade_type><![CDATA[JSAPI]]></trade_type><transaction_id>4200000681202009235085032319</transaction_id></xml>",
"ebpCode": "请替换",
"payCode": "4403169D3W",
"payTransactionId": "4200000681202009235085032319",
"totalAmount": 5,
"currency": "142",
"verDept": "3",
"payType": "4",
"tradingTime": "20200923145426",
"note": ""
},
"payExchangeInfoLists": [
{
"orderNo": "202009231454218421271832",
"goodsInfo": [
{
"gname": "济州花梨精华面膜",
"itemLink": "http://m.yunjiweidian.com/yunjibuyer/static/vue-buyer/idc/index.html#/detail?itemId=999761&shopId=453"
}
],
"recpAccount": "请替换",
"recpCode": "请替换",
"recpName": "请替换"
}
],
"serviceTime": "1601282210417"
}
</pre>
</ul>

Request-headers:

| Header | Value | Type | Required | Description
--- | --- | --- | --- | --- | ---
| x-auth-token-eport-sign |  | string | true | 客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等

Body-parameters:

Parameter | Type | Required | Description
--- | --- | --- | ---
sessionID | string | true | 海关发起请求时，平台接收的会话ID
payExchangeInfoHead | object | true | 支付原始数据表头
└─guid | string | false | 系统唯一序号
└─initalRequest | string | false | 原始请求
└─initalResponse | string | false | 原始响应
└─ebpCode | string | false | 电商平台代码
└─payCode | string | false | 支付企业代码
└─payTransactionId | string | false | 交易流水号(支付报关时会有返回) 微信对应的字段是:verify_department_trade_id 支付宝对应的字段是:pay_transaction_id
└─totalAmount | double | false | 交易金额
└─currency | string | false | 币制(币制编码:142(人民币))
└─verDept | string | false | 验核机构(支付报关结果会返回),1-银联 2-网联 3-其他 微信返回的字段是:verify_department 支付宝对应的字段是:ver_dept
└─payType | string | false | 支付类型
└─tradingTime | string | false | 交易成功时间
└─note | string | false | 备注
payExchangeInfoLists | array | true | 支付原始数据表体
└─orderNo | string | false | 订单编号
└─goodsInfo | array | false | 商品信息
└─gname | string | false | 商品名称
└─itemLink | string | false | 商品展示链接地址
└─recpAccount | string | false | 收款账号
└─recpCode | string | false | 收款企业代码
└─recpName | string | false | 收款企业名称
serviceTime | string | true | 返回时的系统时间

Request-body:

    {
      "sessionID": "",
      "payExchangeInfoHead": {
        "guid": "",
        "initalRequest": "",
        "initalResponse": "",
        "ebpCode": "",
        "payCode": "",
        "payTransactionId": "",
        "totalAmount": 0.0,
        "currency": "",
        "verDept": "",
        "payType": "",
        "tradingTime": "",
        "note": ""
      },
      "payExchangeInfoLists": [
        {
          "orderNo": "",
          "goodsInfo": [
            {
              "gname": "",
              "itemLink": ""
            }
          ],
          "recpAccount": "",
          "recpCode": "",
          "recpName": ""
        }
      ],
      "serviceTime": ""
    }

Response-fields:

Field | Type | Description | Since
--- | --- | --- | ---
message | string | 返回消息 | -
success | boolean | 是否成功 | -
timestamp | string | 响应时间戳 | -
code | int32 | 状态码 | -
data | object | 响应数据 | -
└─payload | object | 请求数据载荷 | -
└─mapKey | object | A map key. | -
└─any object | object | any object. | -
└─original | string | 三方原始返回 | -
└─expected | object | 三方期望返回 | -
└─code | string | No comments found. | -
└─total | int64 | No comments found. | -
└─message | string | No comments found. | -
└─serviceTime | int64 | No comments found. | -

Response-example:

    {
      "message": "",
      "success": true,
      "timestamp": "",
      "code": 0,
      "data": {
        "payload": {
          "mapKey": {
            "waring": "You may use java.util.Object for Map value; smart-doc can't be handle."
          }
        },
        "original": "",
        "expected": {
          "code": "",
          "total": 0,
          "message": "",
          "serviceTime": 0
        }
      }
    }

Curl-example:

    curl -X POST -H 'Content-Type: application/json' -H 'x-auth-token-eport-sign:DefaultAuthToken' -i http://localhost:8080/rpc/eport/upload/179/data --data '{
      "sessionID": "",
      "payExchangeInfoHead": {
        "guid": "",
        "initalRequest": "",
        "initalResponse": "",
        "ebpCode": "",
        "payCode": "",
        "payTransactionId": "",
        "totalAmount": 0.0,
        "currency": "",
        "verDept": "",
        "payType": "",
        "tradingTime": "",
        "note": ""
      },
      "payExchangeInfoLists": [
        {
          "orderNo": "",
          "goodsInfo": [
            {
              "gname": "",
              "itemLink": ""
            }
          ],
          "recpAccount": "",
          "recpCode": "",
          "recpName": ""
        }
      ],
      "serviceTime": ""
    }'

## 4. 电子口岸X509证书

### 4.1. 下载证书

URL: http://localhost:8080/rpc/eport/cert/download

Type: GET

Author: lwj

Content-Type: application/x-www-form-urlencoded;charset=UTF-8

Description: 证书文件格式: 证书编号.cer, 遇到项目启动的首页下载证书出现文件名为 unknown.cer 的情况将下载链接复制到浏览器中打开

Request-headers:

| Header | Value | Type | Required | Description
--- | --- | --- | --- | --- | ---
| x-auth-token-eport-sign |  | string | true | 客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等

Response-example:

    Return void.

Curl-example:

    curl -X GET -H 'x-auth-token-eport-sign:DefaultAuthToken' -i http://localhost:8080/rpc/eport/cert/download

## 5. 电子口岸报文加签

### 5.1. 海关数据加签

URL: http://localhost:8080/rpc/eport/signature

Type: POST

Author: lwj

Content-Type: application/json

Description: 此接口已经整合"海关总署XML"和"海关179数据抓取"的加签<br/>
<ul><b>支持的加签类型</b><li>1. 海关CEBXxxMessage XML数据加签</li><li>2. 海关179数据加签</li></ul>

Request-headers:

| Header | Value | Type | Required | Description
--- | --- | --- | --- | --- | ---
| x-auth-token-eport-sign |  | string | true | 客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等

Body-parameters:

Parameter | Type | Required | Description
--- | --- | --- | ---
id | int32 | false | 唯一id, 用来区分是哪一次发送的消息，默认值=1，从1开始，{@code int} 最大, 231-1.
- data | string | true | 加签源数据 支持的加签数据类型 1. 不带ds:Signature节点的CEBXxxMessage.xml原文;待加签xml报文样例 2. 海关179加签数据; 数据格式请传符合「海关179数据规范」的标准字符串,入参示例: `
      "sessionID":"ad2254-8hewyf32-55616249"||"payExchangeInfoHead":"{"guid":"9D55BA71-22DE-41F4-8B50-C36C83B3B530","initalRequest":"原始请求","initalResponse":"ok","ebpCode":"4404840022","payCode":"312226T001","payTransactionId":"2018121222001354081010726129","totalAmount":100,"currency":"142","verDept":"3","payType":"1","tradingTime":"20181212041803","note":"批量订单，测试订单优化,生成多个so订单"}"||"payExchangeInfoLists":"[{"orderNo":"SO1710301150602574003","goodsInfo":[{"gname":"lhy-gnsku3","itemLink":"http://m.yunjiweidian.com/yunjibuyer/static/vue-buyer/idc/index.html#/detail?itemId=999761&shopId=453"},{"gname":"lhy-gnsku2","itemLink":"http://m.yunjiweidian.com/yunjibuyer/static/vue-buyer/idc/index.html#/detail?itemId=999760&shopId=453"}],"recpAccount":"OSA571908863132601","recpCode":"","recpName":"YUNJIHONGKONGLIMITED"}]"||"serviceTime":"1544519952469"
`

Request-body:

    {
      "id": 0,
      "data": ""
    }

Response-fields:

Field | Type | Description | Since
--- | --- | --- | ---
message | string | 返回消息 | -
success | boolean | 是否成功 | -
timestamp | string | 响应时间戳 | -
code | int32 | 状态码 | -
data | object | 响应数据 | -
└─success | boolean | 本次加签是否成功 | -
└─certNo | string | 签名的ukey的卡序列号 | -
└─x509Certificate | string | 签名的ukey证书 | -
└─digestValue | string | XML报文的数字摘要 | -
└─signatureValue | string | 调用ukey获取的签名值 | -
└─signatureNode | string | XML报文的签名节点 用来组装 ds:SignedInfo 节点 | -

Response-example:

    {
      "message": "",
      "success": true,
      "timestamp": "",
      "code": 0,
      "data": {
        "success": true,
        "certNo": "",
        "x509Certificate": "",
        "digestValue": "",
        "signatureValue": "",
        "signatureNode": ""
      }
    }

Curl-example:

    curl -X POST -H 'Content-Type: application/json' -H 'x-auth-token-eport-sign:DefaultAuthToken' -i http://localhost:8080/rpc/eport/signature --data '{
      "id": 0,
      "data": ""
    }'

Top