附件5、电子口岸单一窗口海关预录入组件-开发白皮书

电子口岸单一窗口海关预录入组件开发白皮书目录1 文档说明 42 术语 52.1 电子口岸单一窗口海关预录入组件 53 预录入组件设计介绍 54 环境准备 74.1 运行环境要求 74.1.1 单一窗口平台服务端要求 74.1.2 客户端要求 74.2 网络环境 85 安全组件说明 95.1 安全组件接口说明 95.1.1 组件信息 95.1.2 方法说明 95.2 安全组件使用说明 105.2.1 B/S使用步骤说明 105.2.2 C/S使用步骤说明 106 业务组件说明 116.1 预录入组件接口说明 116.1.1 组件信息 116.1.2 方法说明 116.1.3 属性说明 136.2 业务组件使用说明 146.2.1 B/S应用使用步骤说明 146.2.2 C/S应用使用步骤说明 146.3 报关单业务模块说明 146.4 运输工具业务模块说明 146.5 新舱单业务模块说明 146.6 转关单业务模块说明 156.7 转关运抵报告业务模块说明 156.8 快件转运中心业务模块说明 156.9 新快件业务模块说明 156.10 展览品业务模块说明 156.11 减免税业务模块说明 156.12 公路运输工具业务模块说明 156.13 公路舱单业务模块说明 166.14 稽查作业业务模块说明 166.15 保税货物流转业务模块说明 166.16 加工贸易电子手册业务模块说明 166.17 新车辆证明书业务模块说明 166.18 数据字段规范定义 167 平台身份认证服务封装 167.1 第三方平台的身份认证说明 167.2 第三方平台身份认证流程图 177.3 第三方平台身份认证流程说明 172、 用户登录成功后，第三方平台针对每个用户生成并保存用户临时唯一编号（以下简称该编号为UserID），将该UserID返回给客户端。用户登陆第三方平台。（需第三方平台实现） 187.4 平台身份认证服务 187.5 平台身份认证代理接口定义 188 附录 198.1 B/S架构代码示例 198.1.1 安全组件代码示例 198.1.2 报关单预录入组件代码示例 218.1.3 空运航线航空器备案申报代码示例 228.2 C/S架构代码示例 238.2.1 安全组件代码示例 238.2.2 报关单预录入组件代码示例 238.2.3 空运航线航空器备案申报代码示例 248.2.4 客户端部署注意事项 24

文档更新记录更新日期更新内容备注2015.6.11报关单JSON格式中节点名称Attachment变更为DecSign#报关单JSON数据格式2015.6.15补充完善CSM101水运进出单据申报JSON格式定义水运进出单据申报JSON数据格式2015.6.15CSM002、CSM003、CSM004、CSM005、CSM007中补充了JourneyID格式的定义2015.6.16安全组件boolLogin()，变更为stringLogin()2015.6.16业务组件增加LoginResult属性，需要传入Login()登陆成功后的返回值2015.6.17附录示例代码更新2015.8.20“自动更新组件”名称更改为“安全组件”增加C/S版程序使用说明2015.9.17网络环境自动更新组件2015.10.13修改了3.2网络环境的说明2015.10.141.修改了客户端传入参数及说明;2.运输工具json格式2015.10.21接受了之前对文档的修订；统一了命名：将“平台加签”“平台签名”等命名统一为“平台身份认证”2015.10.21修改了标题有大括号的问题2015.10.26修改了”空运航空器在港动态申报JSON数据格式”2015.10.26增加了支持青岛和宁波分布式部署的情况2015.10.27修改了运输工具的JSON数据格式2015.10.30增加新舱单业务模块说明2015.11.3修改青岛和宁波分布式的传入参数2015.11.3增加客户端组件的运行环境说明2015.11.9增加第三方平台身份认证相关说明2015.11.9修改所有JSON报文格式为正文文本2015.11.9补充总体设计图2015.11.10修改新舱单空运JSON报文的Version格式2015.11.12修改新舱单删除报文的JSON格式2015.11.17删除stringPlatfromService接口2015.12.9客户端业务组件增加卡控件的8个查询方法2015.12.22将客户端业务组件查询卡控件合并成一个方法2015.12.23增加获取参数接口说明2015.12.28修改带属性的舱单变更的JSON数据格式2015.12.29修改报关单业务JSON报文及数据规范文档说明本文档供单一窗口平台系统开发团队使用，文档内容描述了如何在自己的业务平台上集成单一窗口预录入组件，以及如何调用这些组件，包括组件调用规范，数据接口规范说明等内容。术语电子口岸单一窗口海关预录入组件以下简称预录入组件，是由中国电子口岸数据中心提供的一组业务组件，用于配合单一窗口平台实现关单、运输工具等业务功能。

预录入组件设计介绍构件逻辑图说明：客户端组件的形式是AcitveX组件，通过访问数据中心的地址获得。联调测试环境地址：/DownloaderPlatform/Eport.PreInput.Setup.AutoUpdate.msi运行环境地址：/DownloaderPlatform/Eport.PreInput.Setup.AutoUpdate.msi数据在上行过程中，不经过交换平台数据在上行过程中，通过外挂服务实现数据先下发至分中心后发至数据中心，从而实现串行控制。外挂服务的接口由数据中心定义，外挂服务由分中心开发实现。该外挂可配置，功能可选。（外挂服务数据中心提供demo程序）数据回执是通过在安装在分中心的交换平台客户端来接收。部署在第三方平台上的“第三方平台身份认证服务”和“第三方平台身份认证代理服务”详见第7章。环境准备运行环境要求单一窗口平台服务端要求（一）预录入组件采用ActiveX技术开发，对单一窗口平台系统服务端的开发语言无特定要求。（二）第三方平台服务端需要部署平台身份认证服务，该服务的程序和部署方式由中国电子口岸数据中心提供，部署详见《第三方平台部署文档》。（三）第三方平台服务端需要部署加密机，加密机的技术要求详见《附件2、电子口岸单一窗口（海关）预录入组件服务器密码机技术要求》。第三方平台应根据系统服务的保障级别的需求，考虑加密机的冗余配置。部署详见《第三方平台部署文档》（四）第三方平台服务端需要封装“平台身份认证服务”，具体说明请见“平台身份认证服务封装”章节。客户端要求由于预录入组件及相关附件采用.Net技术开发，因此客户端需要安装.NetFramework2.0版本。需配合IE浏览器使用预录入组件。预录入组件的客户端运行环境：硬件环境要求：处理器：InterE8400+内存：4G及以上硬盘容量：80G及以上网络带宽：互联网4M及以上软件环境要求：操作系统：WindowsXpSp3/Windows7(32位)浏览器:IE8(32位)/IE9(32位)网络环境企业客户端需要开放Internet访问权限，至少要确保能够访问中国电子口岸数据中心提供的相关服务地址。序号地址名称URL使用说明提供者1自动更新服务地址/DownloaderPlatform/EportDll（联调环境）/DownloaderPlatform/EportDll（运行环境）预录入组件自动调用电子口岸数据中心2第三方平台身份认证代理服务地址根据服务部署情况确定预录入组件自动调用第三方平台3第三方平台身份认证服务地址根据服务部署情况确定代理服务调用第三方平台4分中心外挂服务地址http://***********预录入组件自动调用数据分中心特别说明：1、自动更新服务：用来获取预录入组件。联调环境地址和运行环境地址均提供，均可以通过互联网访问。2、第三方平台身份认证代理服务：由第三方平台根据接口定义开发，由第三方平台部署并提供地址。数据中心开发了demo程序。3、第三方平台身份认证服务：该服务的作用是访问加密机，获取平台的签名信息。该服务由数据中心提供，部署在第三方平台上。地址由第三方平台提供。4、分中心外挂服务：该服务的作用是实现数据在上行过程中将数据发送至分中心，实现串行的功能。该服务由数据分中心开发、并部署，地址由数据分中心提供。安全组件说明安全组件接口说明安全组件用于检查本地用户环境，验证组件安装情况，发现安全组件后由用户下载并更新本地组件。组件信息组件名称EportSwcAutoUpdater组件类型ActiveXclassid"clsid:E58B9A24-1F2D-4EE7-B18C-D2F151DF77F2"codebase"http://**************/Eport.PreInput.Setup.AutoUpdate.msi#version=1.0.0"方法说明方法名说明stringGetUpdateStatus()获取安全组件更新状态stringLogin()读取IKEY卡密码进行密码验证stringGetUpdateStatus()获取更新结果信息，返回JSON格式对象用于描述错误信息，以便定位问题原因。返回值类型说明String返回接口调用结果返回结果采用JSON格式定义数据结构如下{"ResultData":{"Result":bool,"Data":["Data信息"],"Error":["Error信息"]}}Rsault为true则调用成功，有返回值则存在于Data中，无返回值为nullRsault为false则调用失败，错误信息存在于Error中。stringLogin()读取界面输入的IKEY密码，调用安全组件进行电子口岸单点登陆验证。单点登录校验成功后会返回一串验证过的JSON信息，该信息需要在业务表单提交时传入到预录入组件中。返回值类型说明String返回接口调用结果返回结果采用JSON格式定义数据结构如下{"ResultData":{"Result":bool,"Data":["Data信息"],"Error":["Error信息"]}}Rsault为true则调用成功，返回登陆安全码存于Data中Rsault为false则调用失败，错误信息存在于Error中。安全组件使用说明B/S使用步骤说明下载并安装安全组件。开发人员在应用程序入口的html或aspx的页面中放置IKEY密码输入框及安全组件。开发人员需要自己调用组件提供的交互接口，传入IKEY密码完成系统的登录认证保存认证凭据，跳转至业务申报界面具体代码详见7.1B/S结构代码示例。C/S使用步骤说明下载并安装安全组件。将安装后的安全组件文件拷贝到应用程序的主目录中。在VS开发工具IDE中引用安全组件引用Eport.PreInput.AutoUpdaterAutoUpdater.dll文件，并将其中的安全组件添加到VS的工具箱中。添加后如下图所示：将安全组件拖入到登录界面中，然后调用安全组件接口中公布的方法。具体代码使用详见7.2C/S结构代码示例。业务组件说明业务组件是表单提交的主入口，通过传入的表单及业务类型等基础信息，会选择性调用对应的业务模块。该组件由安全组件自动下载并且注册完成，无需手动安装，在进入包含预录入组件业务表单填制界面前，请确保程序先进入包含安全组件的登录界面，登陆成功（调用安全组件的登陆方法校验通过）后再跳转到业务表单填制界面中，否则会导致后续流程无法正常进行。预录入组件接口说明组件信息组件名称EportSwc组件类型ActiveXclassid"clsid:B90439DC-03D4-45e9-89F7-991D4E9B16D2"方法说明方法名说明voidExecute()启动功能调用，相关信息参考属性说明stringGetCompanyInfo(stringpassword)对第三方平台公布的方法,获取企业相关信息*获取信息前必须先登录，并且不支持登录后更换IC卡查询企业信息入参:password为卡密码返回结果采用JSON格式定义数据结构如下{"Result":true,"Data":["Data信息"],"Error":["Error信息"]}Result为true则调用成功，有返回值则存在于Data中，无返回Data为空Result为false则调用失败，错误信息存在于Error中。stringGetCodeList(stringcodeType)根据参数类型，获取参数列表入参：codeType为参数类型，随后将具体根据应用需求给出返回结果采用JSON格式定义数据结构如下：{"Result":true,"Data":[{"Code1":”Value1”,……"CodeN":”ValueN”}],"Error":["Error信息"]}Result为true则调用成功，有返回值则存在于Data中，无返回Data为空Result为false则调用失败，错误信息存在于Error中。stringQueryClassifyByCode(stringcode)根据商品海关编码，获取商品信息（商品编码、商品名称、计量单位、法定单位等）入参：code为商品海关编码返回结果采用JSON格式定义数据结构如下：{"Result":true,"Data":[{"Code1":”Value1”,……"CodeN":”ValueN”}],"Error":["Error信息"]}Result为true则调用成功，有返回值则存在于Data中，无返回Data为空Result为false则调用失败，错误信息存在于Error中。stringQueryBrief(stringbriefCodeType,stringtradeCode)根据企业海关十位或者是组织机构代码返回企业名称入参：briefCodeType为企业编码类型，tradeCode为企业编码值企业编码类型为B时，企业编码值为海关十位；企业编码类型为E时，企业编码值为组织机构代码；企业编码类型为S时，企业编码值为统一社会信用代码。返回结果采用JSON格式定义数据结构如下：{"Result":true,"Data":["Data信息"],"Error":["Error信息"]}Result为true则调用成功，有返回值则存在于Data中，无返回Data为空Result为false则调用失败，错误信息存在于Error中。属性说明属性名说明stringBusinessType指定业务类型，业务类型参考业务模块说明stringOperateType指定操作类型，操作类型根据业务有所不同，具体参考相应业务模块说明stringArgument单一窗口平台调用Execute方法前传入，Execute方法执行时根据参数进行相关业务处理Structure采用JSON格式定义数据结构如下{"ArgumentData":{"ArgumentName1":"ArgumentValue","ArgumentName2":"ArgumentValue",}}stringResult返回接口调用结果返回结果采用JSON格式定义数据结构如下{"ResultData":{"Result":true,"Data":["Data信息"],"Error":["Error信息"]}}Result为true则调用成功，有返回值则存在于Data中，无返回Data为空Result为false则调用失败，错误信息存在于Error中。stringBill传入业务表单JSON实体对象，各业务JSON实体格式参考业务模块介绍stringSenderID由分中心提供的分中心数据交换平台用户编号stringPlatfromID第三方平台ID，数据中心提供stringPSignAddr第三方平台身份认证代理服务地址，第三方平台提供stringPlatfromService第三方平台用户唯一标识校验服务，第三方平台提供stringUserId企业用户临时唯一编号stringLoginResult传入登陆成功后的返回结果业务组件使用说明B/S应用使用步骤说明开发人员在业务表单提交的html或aspx的页面中调用该组件。通过接口传入认证凭据通过接口传入业务参数及表单数据调用业务组件功能方法完成业务数据申报C/S应用使用步骤说明为了不影响预录入组件的自动更新功能，业务组件需要采用Assembly.LoadFile方式加载，避免更新时文件被占用。由于采用通过动态调用的方式调用预录入组件，所以无需引用预录入组件，调用方法参考使用7.附录中的代码。报关单业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_报关单DEC》运输工具业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_运输工具CDS》新舱单业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_新舱单管理MFT》转关单业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_转关单TRN》转关运抵报告业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_转关运抵报告ETA》快件转运中心业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_快件转运中心ete》新快件业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_新快件NEXP》展览品业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_展览品EXB》减免税业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_减免税RED》公路运输工具业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_公路运输工具RCDS9》公路舱单业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_公路舱单RMFT9》稽查作业业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_稽查作业JC2006》保税货物流转业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_保税货物流转BHL》加工贸易电子手册业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_加工贸易PTS》新车辆证明书业务模块说明具体参考以下文档 《电子口岸单一窗口海关预录入组件_开发白皮书_新车辆证明书NCIC》数据字段规范定义具体参考以下文档《海关总署2014年70号公告附件3中华人民共和国海关进出境航空器数据项填制规范》《海关总署2014年70号公告附件1中华人民共和国海关国际航行船舶数据项填制规范》平台身份认证服务封装 第三方平台的身份认证说明第三方平台的身份认证，数据中心会开发一个“第三方平台身份认证服务”并部署在第三方平台的安全服务器上。同时，第三方平台要实现“第三方平台身份认证代理服务”模块。第三方平台身份认证流程图第三方平台身份认证流程说明流程说明：用户登陆第三方平台。（需第三方平台实现）用户登录成功后，第三方平台针对每个用户生成并保存用户临时唯一编号（以下简称该编号为UserID），将该UserID返回给客户端。用户登陆第三方平台。（需第三方平台实现）客户端组件向第三方平台身份认证代理服务请求平台身份认证，并传入UserID作为参数。（需第三方平台、预录入组件实现）第三方平台身份认证代理服务向第三方平台的应用服务器验证UserID是否合法。用户登陆第三方平台。（需第三方平台实现）第三方平台身份认证代理服务向第三方平台身份认证服务申请验证。用户登陆第三方平台。（需第三方平台、预录入组件实现）第三方平台身份认证服务向数据中心申请身份验证。（预录入组件实现）将数据中心返回身份认证结果返回给第三方平台身份认证服务。（预录入组件实现）第三方平台身份认证服务将身份认证结果返回给第三方平台身份认证代理服务。（需第三方平台、预录入组件实现）第三方平台身份认证代理服务将身份认证结果返回给客户端组件。（需第三方平台、预录入组件实现）平台身份认证服务程序包eport.SwcPlatSign-1.0-dev-版本号.war服务功能第三方平台身份认证，获得平台签名调用关系预录入组件<>第三方平台身份认证代理服务<>第三方平台身份认证服务备注本程序由数据中心开发，需要部署在第三方平台上，部署详情见《第三方平台部署文档》平台身份认证代理接口定义服务名swc.eport.PlatFormSignImpl服务功能第三方平台身份认证代理服务调用关系预录入组件<>第三方平台身份认证代理服务<>第三方平台身份认证服务请求参数GetTicketRequest对应XSDPlatForm.xsd响应参数GetTicketResponse对应XSDPlatForm.xsd备注该服务须由第三方平台自行开发数据中心提供了demo程序。具体配置请见《第三方平台部署文档》附录B/S架构代码示例安全组件代码示例需将以下代码添加到单一窗口平台入口页面或登录页面，确保用户进入业务单据页面之前访问本页面进行组件版本更新：<scripttype="text/javascript">//验证密码，返回登陆结果functionLoginSys(){varr=document.getElementById("AutoUpdater").Login();document.getElementById("loginResult").value=r;alert(r);}//验证密码，返回登陆结果functionLoginSysByPwd(){varr=document.getElementById("AutoUpdater").LoginByPwd("");document.getElementById("loginResult").value=r;alert(r);}//跳转到业务表单填制界面functionGoToBusiness(){if(document.getElementById("loginResult").value.indexOf('"Result":true')>=0){window.navigate("Entry.aspx?LoginResult="+escape(document.getElementById("loginResult").value));}else{alert("登陆成功后再进入");}}//获得自动更新状态functionGetUpdateStatus(){varr=document.getElementById("AutoUpdater").GetUpdateStatus();if(r!=null&&r!=""){ //输出更新状态，实际应用应当检查更新状态，确保更新完成后再进入其他页面alert(r);}}</script><objectid="AutoUpdater"classid="clsid:E58B9A24-1F2D-4EE7-B18C-D2F151DF77F2"style="font-size:11px;width:300px;"height="25px"></object><!—以实际地址为准，参考本文档第3章--><ahref="/DownloaderPlatform/Eport.PreInput.Setup.AutoUpdate.msi">手动安装</a><inputtype="button"id="btnStatus"value="查看更新状态"onclick="GetUpdateStatus()"/><inputtype="button"id="btn1"value="验证密码"onclick="LoginSys()"/> <inputtype="button"id="Button1"value="进入报关单填制"onclick="GoToBusiness()"/> <inputtype="text"id="loginResult"style="display:none"/>代码添加到页面后IE浏览器打开，如果更新组件未安装会跳出提示，可以点击“手动安装”下载进行安装，安装步骤如下图：1-1；1-2；1-3。安装后刷新页面将会在浏览器中看到IE自动加载了自动更新组件，同时自动更新组件会检查并更新。1-11-21-3报关单预录入组件代码示例将以下脚本代码放置到报关单业务填制界面：<objectid="SWC"classid="clsid:B90439DC-03D4-45e9-89F7-991D4E9B16D2"style="font-size:11px;"></object>使用以下脚本对组件进行控制操作：<scriptlanguage="javascript"type="text/javascript">functionSave(){ //获取表单JSON数据varr=document.getElementById("SWC"); //指定业务类型 r.BusinessType="DEC"; //指定操作类型 r.OperateType="Save"; //指定操作类型 r.Argument='{"ArgumentData":{"CopMsgId":"12345678"}}'; //本例为空，实际使用时需要传入JSON格式表单对象 r.Bill="";//传入登陆界面返回的登陆信息 r.LoginResult="***************"; //发送方ID，填写分中心申请的交换平台ID r.SenderID="***************"; //第三方平台ID，由数据中心分配，例如：SWC01000001 r.PlatfromID="***************"; //传入用户唯一标识,由企业应用服务器生成，测试时可临时赋值为任意值 r.UserID="***************"; //第三方平台服务(用于验证用户UserID，由第三方平台部署和提供) r.PlatformService="http://***************/checkUserID?wsdl";//第三方平台身份认证代理服务r.PSignAddr="http://*********/PlatFormSign/getPlatTicket?wsdl"; //通知预录入组件执行操作r.Execute(); //输出返回结果 alert(r.Result);}</script>页面中增加以下脚本可以增加用户操作互动：<inputtype="button"id="btnDeclare"value="申报提交"onclick="Save()"/>空运航线航空器备案申报代码示例将以下脚本代码放置到报关单业务填制界面：<objectid="SWC"classid="clsid:B90439DC-03D4-45e9-89F7-991D4E9B16D2"style="font-size:11px;"></object>使用以下脚本对组件进行控制操作：<scriptlanguage="javascript"type="text/javascript">functionDeclare(){ //获取表单JSON数据varr=document.getElementById("SWC"); //指定业务类型 r.BusinessType="CDS_CAM001"; //指定操作类型 r.OperateType="Declare"; //指定操作类型 r.Argument='{"ArgumentData":{"CopMsgId":"12345678"}}'; //本例为空，实际使用时需要传入JSON格式表单对象 r.Bill="";//传入登陆界面返回的登陆信息 r.LoginResult="***************"; //发送方ID，填写分中心申请的交换平台ID r.SenderID="***************"; //第三方平台ID，由数据中心分配，例如：SWC01000001 r.PlatfromID="***************"; //传入用户唯一标识,由企业应用服务器生成，测试时可临时赋值为任意值 r.UserID="***************"; //第三方平台服务(用于验证用户UserID，由第三方平台部署和提供) r.PlatformService="http://***************/checkUserID?wsdl";//第三方平台身份认证代理服务r.PSignAddr="http://*********/PlatFormSign/getPlatTicket?wsdl"; //通知预录入组件执行操作r.Execute(); //输出返回结果 alert(r.Result);}</script>页面中增加以下脚本可以增加用户操作互动：<inputtype="button"id="btnDeclare"value="申报提交"onclick="Declare()"/>C/S架构代码示例安全组件代码示例组件内部校验IC卡的调用方式页面设计器Designer.cs代码（autoUpdater1为安全组件控件名）：this.autoUpdater1=newEport.PreInput.AutoUpdater.AutoUpdater();this.autoUpdater1.AutoSize=true;this.autoUpdater1.Location=newSystem.Drawing.Point(18,25);this.autoUpdater1.Name="autoUpdater1";this.autoUpdater1.Size=newSystem.Drawing.Size(383,35);this.autoUpdater1.TabIndex=0;页面后台.cs代码///<summary>///验证密码///</summary>///<paramname="sender"></param>///<paramname="e"></param>privatevoidbutton1_Click(objectsender,EventArgse){stringstrResult=autoUpdater1.Login();strCheckResult=strResult;MessageBox.Show(strResult);} 注:安全组件中所包含的方法说明，请参考4.1安全组件接口说明报关单预录入组件代码示例使用以下代码对组件进行动态调用并控制操作，传入的参数值参