# 中国电子口岸（海口海关）报文加签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文档|



## 电子口岸报文加签测试
### 海关总署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 | Type | Required | Description | Since |
|--------|------|----------|-------------|-------|
|x-auth-token-eport-sign|string|true|客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等|v1.1.0|


**Request-example:**
```
curl -X GET -H 'x-auth-token-eport-sign:DefaultAuthToken' -i http://localhost:8080/rpc/eport/test/cebmessage/signature
```
**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报文的签名节点<br/><li>用来组装 ds:SignedInfo 节点</li>|-|

**Response-example:**
```
{
  "message": "",
  "success": true,
  "timestamp": "",
  "code": 0,
  "data": {
    "success": true,
    "certNo": "",
    "x509Certificate": "",
    "digestValue": "",
    "signatureValue": "",
    "signatureNode": ""
  }
}
```

### 海关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 | Type | Required | Description | Since |
|--------|------|----------|-------------|-------|
|x-auth-token-eport-sign|string|true|客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等|v1.1.0|


**Request-example:**
```
curl -X GET -H 'x-auth-token-eport-sign:DefaultAuthToken' -i http://localhost:8080/rpc/eport/test/179/signature
```
**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报文的签名节点<br/><li>用来组装 ds:SignedInfo 节点</li>|-|

**Response-example:**
```
{
  "message": "",
  "success": true,
  "timestamp": "",
  "code": 0,
  "data": {
    "success": true,
    "certNo": "",
    "x509Certificate": "",
    "digestValue": "",
    "signatureValue": "",
    "signatureNode": ""
  }
}
```

### 执行脚本命令
**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 | Type | Required | Description | Since |
|--------|------|----------|-------------|-------|
|x-auth-token-eport-sign|string|true|客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等|v1.1.0|


**Query-parameters:**

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

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

**Response-example:**
```
Return void.
```

## Ukey健康状态恢复
### 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 | Type | Required | Description | Since |
|--------|------|----------|-------------|-------|
|x-auth-token-eport-sign|string|true|客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等|v1.1.0|


**Request-example:**
```
curl -X POST -H 'x-auth-token-eport-sign:DefaultAuthToken' -i http://localhost:8080/rpc/eport/ukey/health/endpoint/{command}
```
**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": [
      ""
    ]
  }
}
```

## 电子口岸报文推送
### 推送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 | Type | Required | Description | Since |
|--------|------|----------|-------------|-------|
|x-auth-token-eport-sign|string|true|客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等|v1.1.0|


**Body-parameters:**

| Parameter | Type | Required | Description | Since |
|-----------|------|----------|-------------|-------|
|messageType|enum|true|消息类型<br/>[Enum values:<br/>CEB311Message("CEB311Message")<br/>CEB621Message("CEB621Message")<br/>]|-|
|dataType|enum|true|报文的数据类型<br/>[Enum values:<br/>JSON()<br/>XML()<br/>]|-|
|cebMessage|object|true|进口单、出口单的底层数据模型<br/><ul><br/>以CEB311Message数据类型为例<br/><li><br/><p>JSON示例</p><br/><pre><code><br/>{"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"}}<br/></code></pre><br/></li><br/><li><br/><p>XML示例: 不带ds:Signature节点的CEBXxxMessage.xml原文;<a href='http://tool.qdhuaxun.cn/ceb/CEB311Message.xml'>待加签xml报文样例</a></p><br/></li><br/></ul>|-|

**Request-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"
  }
}'
```
**Response-fields:**

| Field | Type | Description | Since |
|-------|------|-------------|-------|
|message|string|返回消息|-|
|success|boolean|是否成功|-|
|timestamp|string|响应时间戳|-|
|code|int32|状态码|-|
|data|object|响应数据|-|
|└─payload|object|请求数据载荷|-|
|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└─Message|object|No comments found.|-|
|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└─MessageHead|object|No comments found.|-|
|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└─MessageId|string|No comments found.|-|
|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└─MessageType|string|No comments found.|-|
|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└─SenderID|string|No comments found.|-|
|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└─ReceiverID|string|No comments found.|-|
|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└─SendTime|string|No comments found.|-|
|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└─Version|string|No comments found.|-|
|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└─MessageBody|object|No comments found.|-|
|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└─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": ""
  }
}
```

### 推送海关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 | Type | Required | Description | Since |
|--------|------|----------|-------------|-------|
|x-auth-token-eport-sign|string|true|客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等|v1.1.0|


**Body-parameters:**

| Parameter | Type | Required | Description | Since |
|-----------|------|----------|-------------|-------|
|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|交易流水号(支付报关时会有返回)<br/>微信对应的字段是:verify_department_trade_id<br/>支付宝对应的字段是:pay_transaction_id|-|
|└─totalAmount|double|false|交易金额|-|
|└─currency|string|false|币制(币制编码:142(人民币))|-|
|└─verDept|string|false|验核机构(支付报关结果会返回),1-银联 2-网联 3-其他<br/>微信返回的字段是:verify_department<br/>支付宝对应的字段是:ver_dept|-|
|└─payType|string|false|支付类型|-|
|└─tradingTime|string|false|交易成功时间|-|
|└─note|string|false|备注|-|
|payExchangeInfoLists|array|true|支付原始数据表体|-|
|└─orderNo|string|false|订单编号|-|
|└─goodsInfo|array|false|商品信息|-|
|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└─gname|string|false|商品名称|-|
|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;└─itemLink|string|false|商品展示链接地址|-|
|└─recpAccount|string|false|收款账号|-|
|└─recpCode|string|false|收款企业代码|-|
|└─recpName|string|false|收款企业名称|-|
|serviceTime|string|true|返回时的系统时间|-|

**Request-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": ""
}'
```
**Response-fields:**

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

## 电子口岸X509证书
### 下载证书
**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 | Type | Required | Description | Since |
|--------|------|----------|-------------|-------|
|x-auth-token-eport-sign|string|true|客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等|v1.1.0|


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

**Response-example:**
```
Return void.
```

## 电子口岸报文加签
### 海关数据加签
**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 | Type | Required | Description | Since |
|--------|------|----------|-------------|-------|
|x-auth-token-eport-sign|string|true|客户端加签时携带的请求头，token值必须和配置文件里面配置鉴权token相等|v1.1.0|


**Body-parameters:**

| Parameter | Type | Required | Description | Since |
|-----------|------|----------|-------------|-------|
|id|int32|false|唯一id, 用来区分是哪一次发送的消息，默认值=1，从1开始，{@code int} 最大, 2<sup>31</sup>-1.|-|
|data|string|true|加签源数据<br/><ul><br/>    <b>支持的加签数据类型</b><br/>    <li>1. 不带ds:Signature节点的CEBXxxMessage.xml原文;<a href='http://tool.qdhuaxun.cn/ceb/CEB311Message.xml'>待加签xml报文样例</a></li><br/>    <li>2. 海关179加签数据; 数据格式请传符合「海关179数据规范」的标准字符串,入参示例:<br/>     <code><pre>"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"</pre></code><br/>    </li><br/></ul>|-|

**Request-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": ""
}'
```
**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报文的签名节点<br/><li>用来组装 ds:SignedInfo 节点</li>|-|

**Response-example:**
```
{
  "message": "",
  "success": true,
  "timestamp": "",
  "code": 0,
  "data": {
    "success": true,
    "certNo": "",
    "x509Certificate": "",
    "digestValue": "",
    "signatureValue": "",
    "signatureNode": ""
  }
}
```


