报关单 (交易接口) (计划中)

• 创建报关单(方式一)
• 创建报关单(方式二)
• 创建报关单AI识别附件(方式三)
• 修改报关单(方式一)
• 修改报关单(方式二)
• 删除报关单
• 逻辑校验
• 暂存单一窗口
• 推送报关行
• 撤回推送
• 触发客户端任务
• 附：数据模型

创建报关单(方式一)

请求

• 接口路径：v1/dec?filter={filter}&refNoCheck={refNoCheck}
• 请求方法：POST
• 请求头内容：
  • Content-Type: application/json
• 请求Body内容

{
    "requestId": "38bds",
    "refNo": "客户单号",
    "businessTypeId": "01",
    "data": {
        "ieType": "EXPORT",
        "head": {},
        "freeTxt": {},
        "items": [],
        "containers": [],
        "docs": [],
        "licenses": []        
        // 详细字段请参考：报关单数据模型
    },
    "auxData": {
    },
    "resourceIds": []
}

• 业务类型：
  • 01 - 出口
  • 02 - 进口
  • 03 - 出镜备案清单
  • 04 - 进境备案清单
  • 05 - 出口转关前提报关
  • 051 - 出镜转关提前报关
  • 06 - 进口转关提前报关
  • 061 - 进境转关提前报关
  • 07 - 出口公路舱单跨境快速通关报关
  • 08 - 进口公路舱单跨境快速通关报关
  • 09 - 出口公路舱单跨境快速通关备案清单
  • 10 - 进口公路舱单跨境快速通关备案清单

响应

• HTTP状态: 200 代表调用成功

• 响应正文：

{
    "success": true,
    "message": null,
    "result": "111",
    "error": null
}

{
    "success": false,
    "message": "存在相同refNo",
    "result": "12699",
    "error": "DUP_REFNO"
}

error对应的代码:

示例

curl -X POST http://cheetah.test.yunbaoguan.cn/api/openapi/v1/dec \
  -H 'Authorization: ACCESS_KEY 4a9d1eb7-eee0-434b-9d36-38bbc68a2dce' \
  -H 'Content-TYpe: application/json' \
  --data '{"businessTypeId":"01", "requestId": "38bdsss2a", "data":{"ieType":"EXPORT","head":{"cusCiqNo":null,"customMaster":"5316","iEPort":"5316","iEDate":null,"manualNo":"AABB11223344","contrNo":"CN001","billNo":"C1807438635","noteS":null,"ownerScc":"914403003262****XF","ownerCode":"4403160**3","ownerCiqCode":"4700645324","ownerName":"深圳**信息有限公司","agentScc":"914403003262****XF","agentCode":"4403160**3","agentName":"深圳**信息有限公司","agentCiqCode":null,"tradeScc":"914403003262****XF","tradeCode":"4403160**3","tradeCiqCode":"4700645324","tradeName":"深圳**信息有限公司","overseasConsignorCode":null,"overseasConsignorEname":"Aisino","domesticConsigneeEname":null,"overseasConsignorCname":null,"overseasConsignorAddr":null,"transMode":"3","tradeModeCode":"0110","entryType":"M","supvModeCdde":"0110","cusTradeCountry":"USA","cusTradeNationCode":"USA","despPortCode":null,"distinatePort":"USA336","districtCode":"11059","cusTrafMode":"4","trafName":null,"cusVoyageNo":null,"packNo":22,"wrapType":"22","netWt":1,"grossWt":22,"markNo":"N/M","promise1":"9","promise2":"9","promise3":"9","chkSurety":"0","paperlessTax":null,"sinceNpPay":"1","voluntaryTax":null,"waterTransfer":"1","declaratioMaterialCode":null,"declTrnRelFlag":"0","specDeclFlag":"000000","billType":null,"passRmftType":null,"decOtherPacksVo":[],"cutMode":"101","licenseNo":null,"feeMark":null,"feeRate":null,"feeCurr":null,"insurMark":null,"insurRate":null,"insurCurr":null,"otherMark":null,"otherRate":null,"otherCurr":null,"goodsPlace":null,"orgCode":null,"vsaOrgCode":null,"purpOrgCode":null,"inspOrgCode":null,"correlationDeclNo":null,"correlationReasonFlag":null,"despDate":null,"ciqBillNo":null,"origBoxFlag":null,"consignorAddr":null,"cmplDschrgDt":null,"ciqEntyPortCode":"470601"},"freeTxt":{"relmanNo":null,"bonNo":null,"customsField":null,"relativeId":null,"decBpNo":null,"decNo":null,"voyNo":null},"items":[{"gNo":1,"contrItem":null,"codeTs":"9603909090","ciqCode":"101","ciqName":"其他材料制帚 ,刷 ,拖把及毛掸(包括其他材料制非机动的手工操作地板清扫器等)(含木制品)","gName":"刷子","declGoodsEname":null,"gModel":null,"gQty":22,"gUnit":"007","qty1":null,"unit1":null,"qty2":null,"unit2":null,"declPrice":22,"declTotal":484,"tradeCurr":"CNY","destinationCountry":"USA","cusOriginCountry":"CHN","origPlaceCode":null,"districtCode":"11059","exgVersion":null,"exgNo":null,"ciqDestCode":"110109","goodsAttr":null,"purpose":null,"dutyMode":"1","controlMark":null,"stuff":null,"prodValidDt":null,"prodQgp":null,"engManEntCnm":null,"goodsSpec":null,"goodsModel":null,"goodsBrand":null,"produceDate":null,"prodBatchNo":null,"mnufctrRegNo":null,"noDangFlag":null,"unCode":null,"dangName":null,"packType":null,"packSpec":null}],"containers":[],"docs":[],"markAtt":null,"licenses":[]},"resourceIds":["资源ID"]}'

创建报关单(方式二)

说明: 基本上与方式一是一致的 区别是:Body内容中的data是单一格式的xml报文, 接口路径多了/sw-message

请求

接口路径：v1/dec/sw-message?filter={filter}&refNoCheck={refNoCheck}&assignForm={assignForm}

{
    "requestId": "38bds",
    "refNo": "客户单号",
    "businessTypeId": "01",
    "data": "单一格式的xml报文 base64编码", // 与方式一不一样
    "auxData": {
    }
}

创建报关单AI识别附件(方式三)

说明: 基本上与方式一是一致的 区别是:Body内容中的resourceId是上传的资源ID集合, 接口路径多了/ai ；上传资源请看 上传资源文档

请求

接口路径：v1/dec/ai?filter={filter}&refNoCheck={refNoCheck}

{
    "requestId": "38bds",
    "refNo": "客户单号",
    "businessTypeId": "01",
    "resourceIds": ["resourceId", "..."], // 支持多个附件
    "auxData": {
    }
}

修改报关单(方式一)

请求

• 接口路径：v1/dec/{id}?filter={filter}
• {id}为创建返回的报关单内部编号
• 请求方法：PUT
• 请求头内容：
  • Content-Type: application/json
• 请求Body内容

{
    "refNo": "客户单号",
    "businessTypeId": "01", //   
    "data": {
        "ieType": "EXPORT",
        "head": {},
        "freeTxt": {},
        "items": [],
        "containers": [],
        "docs": [],
        "licenses": []        
        // 详细字段请参考：报关单数据模型
    }
}

响应

• HTTP状态: 200 代表调用成功

• 响应正文：

{
    "success": true,
    "message": null,
    "result": 2,
    "error": null
}

修改报关单(方式二)

说明: 基本上与方式一是一致的 区别是:Body内容中的data是单一格式的xml报文, 接口路径多了/sw-message

请求

• 接口路径：v1/dec/sw-message/{id}?filter={filter}
• 请求Body内容

{
    "refNo": "客户单号",
    "businessTypeId": "01",   
    "data": "单一格式的xml报文 base64编码"
}

删除报关单

请求

• 接口路径：v1/dec/{id}
• {id}为创建返回的报关单内部编号
• 请求方法：DELETE
• 请求Body内容：空

响应

• HTTP状态: 200 代表调用成功

• 响应正文：

{
    "success": true,
    "message": null,
    "result": null,
    "error": null
}

逻辑校验

请求

• 接口路径：v1/dec/{id}/validation
• {id}为创建返回的报关单内部编号
• 请求方法：POST
• 请求Body内容：空

响应

• HTTP状态: 200 代表调用成功

• 响应正文：

{
    "success": true,
    "message": null,
    "result": [
        // ValidationResult (Warning)
        {	
            "field": "/items/0/",                     // json-pointer格式 (IETF RFC 6901)
            "level": "WARN",                          // 错误等级
            "message": "第1行商品国家不能为空",           // 错误信息
            "ref": "body/country_not_empty::compare",  // 平台内部规则识别码
        }
    ],
    "error": [
        // ValidationResult (Error+Warning)
    ]
}

暂存单一窗口

请求

• 接口路径：v1/dec/{id}/submit
• {id}为创建返回的报关单内部编号
• 请求方法：POST
• 请求Body内容：

{
    "requestId": "request-id-for-idempotency-check"
}

响应

• HTTP状态: 200 代表调用成功

• 响应正文：

{
    "success": true,
    "message": null,               // 发送失败信息
    "result": "submit-process-id", // 发送进程编号
    "error": null
}

推送报关行

请求

• 接口路径：v1/dec/:id/push-other
• {id}为创建返回的报关单内部编号
• 请求方法：POST

响应

• HTTP状态: 200 代表调用成功

• 响应正文：

{
    "success": true,
    "message": null,               // 发送失败信息
    "result": null,
    "error": null
}

撤回推送

请求

• 接口路径：v1/dec/:id/cancel-push
• {id}为创建返回的报关单内部编号
• 请求方法：POST

Query 请求参数：

响应

• HTTP状态: 200 代表调用成功

• 响应正文：

{
    "success": true,
    "message": null,               // 发送失败信息
    "result": null,
    "error": null
}

触发客户端任务

说明: 触发报关单的客户端任务，用于下载单一窗口的 PDF 打印件或获取税费单数据。平台会根据传入的标识查询出报关单数据，再组装任务参数并创建客户端任务。

请求

• 接口路径：v1/dec/{identifier}/client-task?taskType={taskType}&idType={idType}
• 请求方法：POST
• 请求Body内容：空

Path 请求参数：

Query 请求参数：

• 任务类型 (taskType)：

注意：使用 identifier 自动识别或 entryId、cusCiqNo 查询时，若匹配到多条报关单将返回失败，此时请使用 idType=id 并传入内部编号精确指定。

响应

• HTTP状态: 200 代表调用成功

• 响应正文：

{
    "success": true,
    "message": "任务已触发",
    "result": "111",
    "error": null
}

附：数据模型

报关单数据模型

{                                            // 报关单表单数据
    "ieType": "EXPORT",                      // 出口 EXPORT 进口IMPORT
    "head": {                                // 单证表头
        "cusCiqNo": null,                    // 统一编号
        "customMaster": "5316",              // 申报地海关
        "iEPort": "5316",                    // 进出境关别（进口：进境关别    出口：出境关别）
        "iEDate": null,                      // 进出日期
        "manualNo": "AABB11223344",          // 备案号
        "contrNo": "CN001",                  // 合同号
        "billNo": "C1807438635",             // 提运单号
        "ownerScc": "914403003262****XF",    // 出口：生产销售单位18位社会信用代码    进口：消费使用单位18位社会信用代码
        "ownerCode": "4403160**3",           // 出口：生产销售单位10位海关编码    进口：消费使用单位10位海关编码
        "ownerCiqCode": "4700645324",        // 出口：生产销售单位10位检验检疫编码 进口：消费使用单位10位检验检疫编码
        "ownerName": "深圳**信息有限公司",      // 出口：生产销售单位名称           进口：消费使用单位名称
        "agentScc": "914403003262****XF",    // 申报单位18位信用代码
        "agentCode": "4403160**3",           // 申报单位10位海关代码
        "agentName": "深圳**信息有限公司",      // 申报单位名称
        "agentCiqCode": "4700645324",        // 申报单位检验检疫编码
        "tradeScc": "914403003262****XF",    // 境内收发货人18位编码
        "tradeCode": "4403160**3",           // 境内收发货人10位海关编码
        "tradeCiqCode": "4700645324",        // 境内收发货人10位检验检疫编码
        "tradeName": "深圳**信息有限公司",      // 境内收发货人中文名称
        "overseasConsignorCode": null,       // 境外收发货人
        "overseasConsignorEname": "Aisino",  // 境外收发货人名称（英文）
        "domesticConsigneeEname": null,      // 境内收货人名称（英文--检疫表单）
        "overseasConsignorCname": null,      // 境外发货人名称(中文--检疫表单)
        "overseasConsignorAddr": null,       // 境外发货人地址
        "transMode": "3",                    // 成交方式
        "entryType": "M",                    // 报关单类型
        "supvModeCdde": "0110",              // 监管方式
        "cusTradeCountry": "USA",            // 运抵国(地区)
        "cusTradeNationCode": "USA",         // 贸易国别(地区)
        "despPortCode": "USA336",            // 进口：启运港
        "distinatePort": "USA336",           // 出口 指运港  进口 经停港
        "cusTrafMode": "4",                  // 运输方式
        "trafName": null,                    // 运输工具名称
        "cusVoyageNo": null,                 // 航次号
        "packNo": 22,                        // 件数
        "wrapType": "22",                    // 包装种类
        "netWt": 1,                          // 净重(KG)
        "grossWt": 22,                       // 毛重(KG)
        "markNo": "N/M",                     // 标记唛码
        "promise1": "9",                     // 特殊关系确认
        "promise2": "9",                     // 价格组成确认
        "promise3": "9",                     // 特许权使用费支付确认
        "noteS": null,                       // 备注 业务事项
        "chkSurety": "0",                    // 可选 担保验放(1:是；0否)
        "paperlessTax": null,                // 可选 税单无纸化(1:是；0否)
        "sinceNpPay": "1",                   // 可选 自报自缴(1:是；0否)
        "voluntaryTax": null,                // 可选 自主报税(1:是；0否)
        "waterTransfer": "1",                // 可选 水运中转(1:是；0否)
        "declTrnRelFlag": "0",               // 报关(0)/转关(1)关系标志
        "specDeclFlag": "000000",            // 特殊业务标识(7位拼接)
        "billType": null,                    // 备案清单类型：可选 1：一般案清单 2：先进区后报关 3：分送集报备案清单 4；两单一审备案清单
        "passRmftType": null,                // 公路舱单跨境快速通关标志
        "decOtherPacksVo": [],               // 其他包装
        "cutMode": "101",                    // 征免性质
        "licenseNo": null,                   // 许可证号
        "feeMark": null,                     // 运费类型
        "feeRate": null,                     // 运费值
        "feeCurr": null,                     // 运费币种
        "insurMark": null,                   // 保险费类型
        "insurRate": null,                   // 保险费值
        "insurCurr": null,                   // 保险费币种
        "otherMark": null,                   // 杂费类型
        "otherRate": null,                   // 杂费值
        "otherCurr": null,                   // 杂费币种
        "goodsPlace": null,                  // 货物存放地点
        "orgCode": null,                     // 检验检疫受理机关
        "vsaOrgCode": null,                  // 领证机关
        "purpOrgCode": null,                 // 目的地检验检疫机关
        "inspOrgCode": null,                 // 口岸检验检疫机关
        "correlationDeclNo": null,           // 关联号码
        "correlationReasonFlag": null,       // 关联理由
        "despDate": null,                    // 进口 启运日期（只有进口有）
        "ciqBillNo": null,                   // 进口 B/L号（只有进口有）
        "origBoxFlag": null,                 // 进口 原装箱数（只有进口有）
        "consignorAddr": null,               // 进口 境外发货人地址(只进口有)
        "cmplDschrgDt": null,                // 进口 卸毕日期 (只进口有)
        "ciqEntyPortCode": "470601"          // 进口 入境口岸/ 出口 离境口岸
    },
    "freeTxt": {                             // 关联信息
        "relmanNo": null,                    // 关联备案
        "bonNo": null,                       // 保税/监管场地
        "customsField": null,                // 场地代码
        "relativeId": null,                  // 关联报关单号
    },
    "items": [                               // 商品信息
        {
            "gNo": 1,                        // 必填 序号要保持连续（1...N)
            "contrItem": null,               // 备案序号
            "codeTs": "9603909090",          // 商品编码
            "ciqCode": "101",                // 检验检疫编码
            "ciqName": "其他材料制帚(含木制品)", // 检验检疫名称
            "gName": "刷子",                  // 商品名称
            "declGoodsEname": null,          // 商品英文名称
            "gModel": null,                  // 规格型号
            "gQty": 22,                      // 成交数量
            "gUnit": "007",                  // 成交计量单位
            "qty1": null,                    // 法一数量
            "unit1": null,                   // 法一单位
            "qty2": null,                    // 法二数量
            "unit2": null,                   // 法二单位
            "declPrice": 22,                 // Decimal 单价,4位小数
            "declTotal": 484,                // Decimal 总价,2位小数
            "tradeCurr": "CNY",              // 币制
            "destinationCountry": "USA",     // 最终目的国
            "cusOriginCountry": "CHN",       // 原产国（地区）
            "origPlaceCode": null,           // 进口 原产地区（进口）
            "districtCode": "11059",         // 出口 境内货源地 进口 境内目的地
            "exgVersion": null,              // 加工成品单耗版本号
            "exgNo": null,                   // 货号
            "ciqDestCode": "110109",         // 产地代码
            "goodsAttr": null,               // 货物属性
            "purpose": null,                 // 用途
            "dutyMode": "1",                 // 征免方式
            "controlMark": null,             // 监管要求
            "stuff": null,                   // 成分/原料/组分 (检验检疫货物规则)
            "prodValidDt": null,             // 产品有效期 (检验检疫货物规则)
            "prodQgp": null,                 // 产品保质期(天) (检验检疫货物规则)
            "engManEntCnm": null,            // 境外生产企业 (检验检疫货物规则)
            "goodsSpec": null,               // 货物规格(检验检疫货物规则)
            "goodsModel": null,              // 货物型号(检验检疫货物规则)
            "goodsBrand": null,              // 货物品牌(检验检疫货物规则)
            "produceDate": null,             // 生产日期(检验检疫货物规则)
            "prodBatchNo": null,             // 生产批次(检验检疫货物规则)
            "mnufctrRegNo": null,            // 生产单位代码(检验检疫货物规则)
            "noDangFlag": null,              // 非危险化学品(危险货物信息)
            "unCode": null,                  // UN编码(危险货物信息)
            "dangName": null,                // 危险货物名称(危险货物信息)
            "packType": null,                // 危包类别(危险货物信息)
            "packSpec": null                 // 危包规格(危险货物信息)
        }
    ],
    "containers": [
        {
            "contSeqNo": "1",                           // 序号 (1..N)
            "containerMdCode": "11",                    // 集装箱容器类型编码
            "containerMdCodeName": "普通2*标准箱（L）",   // 集装箱容器类型名称
            "containerNo": "C1111221221",               // 集装箱号
            "goodsNo": "1",                             // 对应货物行序号，多个值以逗号分割
            "lclFlag": "0",                             // 拼箱标识 0代表否 1代表是
            "containerWt": 12,                          // 集装箱自重,单位 KG
        }
    ],
    "docs": [                                // 随附单据
        {
            "attTypeCode": "00000001",                          // 随附单据类型编码
            "attTypeCodeName": "发票",                          // 随附单据类型名称
            "entOrigFileName": "test.pdf",                      // 上传的随附单据档案名称
            "attEdocPath": "87b6a81adb62426ea2b3dd45e54c46f1",  // 随附单据内部资源ID,如何获取请参考上传资源API
            "contentLength": 33099,                             // 档案大小，单位 Byte
            "ref": "UPLOADED"                                   // UPLOADED 代表是上传的档案
        }
    ],
    "licenses": [
        {
            "formSeqNo": 1,                                     // 序号
            "acmpFormCode": "",                                 // 单证代码
            "acmpFormNo": "",                                   // 单证编号
            "cusEcoRels": [                                     // 原产地对应关系
                {
                    "ecoRelSeqNo": 1,                           // 序号
                    "ecoGNo": 1,                                // 项号
                    "gNo": ""                                   // 货物项号
                }
            ],                                                                
        }
    ]
}

报关单 9710/9810 数据模型

{                                            // 报关单表单数据
    "ieType": "EXPORT",                      // 出口 EXPORT 进口IMPORT
    "head": {                                // 单证表头
        "tradeScc": "914403003262****XF",    // 境内收发货人18位编码
        "tradeCode": "4403160**3",           // 境内收发货人10位海关编码
        "tradeCiqCode": "4700645324",        // 境内收发货人10位检验检疫编码
        "tradeName": "深圳**信息有限公司",      // 境内收发货人中文名称
        "supvModeCdde": "9710",              // 监管方式 (9710/9810 ....)
    },
    "items": [                               // 商品信息
        {
            "gNo": 1,                        // 必填 序号要保持连续（1...N)
            "gName": "刷子",                  // 商品名称
            "gQty": 22,                      // 成交数量
            "gUnit": "007",                  // 成交计量单位
            "declPrice": 22,                 // Decimal 单价,4位小数
            "declTotal": 484,                // Decimal 总价,2位小数
            "tradeCurr": "CNY"              // 币制
        }
    ]
}

字段说明