北京无车承运人试点企业数据接口联调方案.docVIP

无车承运人试点企业数据接口联调方案V1.1联调流程收到接口规范并完成相应改造的试点企业，应先进行企业平台自查，并填报接口规范自查完成情况反馈表（附件2）至北京市运输管理技术支持中心（以下简称技术支持中心）专用邮箱：bjys_。技术支持中心核验后将企业平台接入授权信息表（附件3）发送至试点企业。试点企业根据企业平台接入授权信息表中的信息与北京交通运输物流公共信息平台对接，并按照技术支持中心安排的时间进行调试测试，结束后技术支持中心发给平台技术联调结果通知书（附件4）。调试通过的接入工作完成，调试不通过的，试点企业调整自身平台后，技术支持中心根据实际情况另行安排时间进行重测。公共平台侧：联系人崔玮子政调实时沟通渠道QQ群：285147938QQ群名称：北京平台联调联调现场支持地点运输局5楼519机房内侧办公室联调接口接口地址：36联调接口规范参看附件1附件1北京市交通运输物流公共信息平台运单数据接口规范V1.21. 范围本方案约定了物流数据上报公共信息平台的协议基础、通信连接、报文处理和服务接口描述。本方案适用于企业通过自有软件、标准软件或共用软件(以下简称客户端)向北京市交通运输物流公共信息平台服务器端上报普通货物运输电子数据的数据接口规范。2. 规范性引用文件本方案依据国家交通运输物流公共信息平台|L2000标准制定，相应协议、通信和报文均参照L2000描述，标准下载地址：交通运输物流公共信息平台标准3.1版本3. 术语和定义略4. 缩略语下列缩略语适用于本文件。XML可扩展标记语言（EXtensible Markup Language，XML）HTTP超文本传输协议(Hypertext Transfer Protocol)WS-SecurityWeb服务安全(Web Services Security, short WSS)Web Service WEB服务（Web Servicr）SOAP 简单对象访问协议（Simple Object Access Protocol）5. 协议基础5.1 通信方式本协议采用的通信方式应符合SOAP1.1中的相关规定，通信协议采用HTTP同步方式，无车承运人试点企业软件作为客户端。5.2 数据类型本协议报文中数据流遵循HTTP技术规范，报文中使用的数据类型包括：1) 出现次数：n.n：第一个n：最少出现次数，第二个n：最多出现次数。示例1： 1）0.1：最少出现0次（即可不出现），最多只能出现1次（即不能循环）。2）1.9：最少出现1次（即必须出现1次），最多能出现9次（即可以有9次循环）。2) 数据格式：数据格式中使用的字符含义如下： a = 字母字符； n = 数字字符； an = 字母数字字符； m(m=为自然数) = 定长m 个字符（字符集默认为GB2312）； .ul = 长度不确定的文本； . = 从最小长度到最大长度，前面附加最小长度，后面附加最大长度； YYYYMMDDhhmmss “YYYY”表示世纪和年份，“MM”表示月份，“dd”表示日期，“hh”表示小时，“mm”表示分钟，“ss”表示秒； True/False =布尔型。示例2： 1）an5(aannn)：表示定长5个字母数字字符，前2个为字母字符，后3个为数字字符；2）an3.8：表示最大长度为8，最小长度为3的不定长字符；3）n.8,4：表示该数值最大长度为8位整数、4位小数；4）True/False：表示该数值为布尔型。5.3 报文的组成每条报文由报文头和报文体组成，报文结构图如图1所示。报文头报文体图1 报文结构图5.3.1 报文头内容如表1所示。企业进行数据交换时，物流共用软件、重要物流及相关信息系统需在请求报文头中加入认证时获取的令牌信息。令牌信息在报文头中通过ws-security格式来描述，如示例3所示。表1 报文头内容序号报文层XML标记中文名称出现次数数据类型/数据格式（Type/Length）说明必填11soapenvsoapenv1.122soapenv:Header报文头1.133wsse:Security报文头1.144wsse:UsernameToken报文头1.155wsse:Username用户名1.1an.20必填65wsse:Password密码或令牌1.1an.50必填示例3： 5.3.2 报文体属性格式内容如表2所示，结构图如示例4所示。表2 报文体属性格式序号报文层LevelXML标记中文名称出现次数数据类型/数据格式（Type/Length）说明必填11soapenvsoapenv1.122soapenv:Body报文头1.133operate报文头1.144businessId业务编号1.1an.20必填54businessType业务类型1.1an.50必填64businessXml业务内容1.1an.2000必填示例4： f2bb59e2-a214-41ef-8dde-e2009ea84dfaFJWL_E-WAY_SEND_GENERALWVdGaA=6. 通信连接6.1 连接的建立客户端与服务器端的数据日常连接主要采用HTTP方式，上报电子运单数据前，先与服务器端建立HTTP连接，连接建立后立即向服务器端发送登录鉴权报文进行鉴权。6.2 连接的维持HTTP连接建立和客户端鉴权成功后，即客户端向服务器端发送电子运单报文信息，服务器端收到后向客户端发送报文信息后将反馈结果， 客户端在完成上报电子运单报文后，可通过调用注销接口，发送给服务器端注销请求。 客户端与服务器端之间不维持长连接，只在需要上报电子运单报文时才建立连接。6.3 连接的断开客户端可根据HTTP协议主动断开连接。客户端判断HTTP连接断开的方法： 通过发送注销请求主动断开； 数据通信链路断开； 数据通信链路正常，达到重传次数后仍未收到应答。7. 报文处理（客户端发起请求）7.1 数据通信链路正常数据通信链路正常时，所有客户端主发的HTTP报文均要求服务器端应答，应答分为鉴权应答和报文上报应答，由各具体功能协议决定。客户端等待应答超时后，应对报文进行重发。7.2 数据通信链路异常数据通信链路异常时，客户端应对需发送的位置信息汇报报文进行保存。在数据通信链路恢复正常后，立即发送保存的报文。8. 服务接口描述8.1 交换认证服务认证服务是企业接入监管平台进行数据交换时采用的安全保障机制，为交换双方提供身份安全认证和交换合法性认证，包括安全认证和退出授权等操作。企业在进行数据交换前，首先调用身份安全认证服务，该服务返回给企业一个用户令牌标识（UserTokenID）。令牌有时间限制，为自然时间的24小时有效。企业进行数据交换时，物流通用软件及其它信息系统应在请求消息头中加入认证时获取的令牌信息。令牌信息在消息头中通过ws-security格式来描述，示例如下：userNamepwdvalue 8.1.1 安全认证服务安全认证服务是一种web服务，从请求消息和响应消息两部分对服务属性进行约定,实现对用户身份的安全认证。 请求消息用户安全认证请求消息以XML方式描述了应进行认证的用户信息，请求消息包括用户名和密码，如下表：中文名称属性/元素名数据类型约束/出现次数说明帐户名称UsernameString1.1帐户密码PasswordString.2 响应消息用户认证操作将用户的令牌标识以XML格式封装返回给用户。如果认证失败，返回用户错误代码和错误原因，如下表。中文名称属性/元素名数据类型约束/出现次数说明用户令牌标识UserTokenIDString0.1异常信息GenericFaultGenericFaultType 退出授权服务退出授权服务是一种web服务，从输入消息和输出消息两部分对服务属性进行约定,实现用户退出登陆。 请求消息用户退出登录请求消息以XML方式描述了用户名称和用户令牌标识，如下表。中文名称属性/元素名数据类型约束/出现次数说明帐户名称UsernameString1.1用户令牌标识UserTokenIDString.2 响应消息用户退出登录响应以XML方式返回用户退出登录操作的结果，如下表。中文名称属性/元素名数据类型约束/出现次数说明退出结果LogoutResultBoolean1.18.2 数据交换服务支持分布或异构应用系统，通过交换平台进行信息交换的、面向SOA（面向服务架构）的一种信息系统服务模式，目前提供发送服务。8.2.1 数据发送服务数据发送服务是一种基于web的服务，从输入消息和输出消息两部分服务属性进行约定，为企业提供了数据发送功能，采用异步方式的交换传输。 请求消息请求消息以XML方式描述了通用的存储请求。请求消息由目标地址和交换事件组成，如下表。中文名称属性/元素名数据类型约束/出现次数说明目标地址ToAddressString1.1事件发送的地址交换事件ExchangeEventExchangeEventType1.n交换事件数据类型如下表。属性名元素名数据类型约束/出现次数说明事件标识EventIDString1.1企业传入的唯一流水号操作类型ActionTypeString1.1交换数据ExchangeDataXML文件1.1包Package交换数据包可以包含1个数据包单元，存放业务单据报文,或者包含2个数据包单元，分别存放业务单据报文和签收单图片附件。目前，第2种情况仅出现在业务单据报文中包含作业单状态，并且作业单状态处于70已签收状态，客户端可将签收信息作为扫描件存入系统并上传。（1）存放业务单据报文的数据包单元（ExchangeDataPackageUnit）：此数据包单元（ExchangeDataPackageUnit）存放业务单据报文，数据包单元对应的数据格式为：数据文件（DataFile）如下表。属性名元素名数据类型约束/出现次数说明文件标识DataFileIDString1.1数据文件标识文件名FileNameString1.1文件格式DataFileFormatString1.1XML嵌入式内容EdDataBase64Binary1.1（2）存放签收单图片附件的数据包单元（ExchangeDataPackageUnit）：数据包单元对应的数据格式为：附件文件（DataFile）如下表。属性名元素名数据类型约束/出现次数说明文件标识DataFileIDString1.1数据文件标识文件名FileNameString1.1主文件名和扩展名文件格式DataFileFormatString1.1File嵌入式内容AttachmentDataBase64Binary1.1图片二进制文本内容 响应消息响应消息是将操作结果封装。响应消息是发送结果类型。由执行状态，发送失败集组成，如下表。中文名称属性/元素名数据类型约束/出现次数说明发送结果ResultBoolean1.1发送是否成功服务代理内容ResultXMLBase64Binary0.1异常信息GenericFaultGenericFaultType0.1通用异常信息通用异常信息类型规定了一般的异常信息的表示方法，通用异常信息包括异常编码和异常错误信息，它的属性定义如下表。中文名称属性/元素名数据类型约束/出现次数说明异常编码CodeString1.1自定异常错误代码异常信息ErrorMessageString1.1异常发生原因的详细信息9. 普通货物运输跟踪业务接口9.1 普通货物运输托运单上传企业进行普通运输托运货物受理时，在普通运输通用软件生成托运单，并将托运单及明细发送给监管平台。一张托运单由1条托运单记录、若干条托运单货物明细、若干条容器明细组成。l 发送方：企业通过接口发送；l 发送方式：异步，通过接口的传输服务l 接收方：监管平台序号报文层数据元标识符XML标记中文名称出现次数数据类型引用文件说明11RootRoot1.122Header报文头1.1330062MessageReferenceNumber报文参考号1.1an.35报文唯一标识符，系统自动按照GUID规则生成431000DocumentName单证名称1.1an.35中文名称：普通运输托运单530052DocumentVersionNumber报文版本号1.1an.17V3.1639813SenderCode发送方代码0.1an.20交换代码，不填732863MessageSendingDateTime发送时间1.1an.19YYYYMMDDhhmmss831225MessageFunctionCode报文功能代码0.1an.3代码集4.592Body报文体1.11031802ShippingNoteNumber托运单号1.1an.201131820OriginalDocumentNumber原始单号0.1an.351232805ConsignmentDateTime托运时间1.1an.19YYYYMMDDhhmmss1338902BusinessTypeName业务类型名称0.1an.351439896OperationRequirment作业要求0.1an.351538921PriorityCode紧急程度代码1.1an.3代码集5.131638920PriorityDescription紧急程度描述0.1an.171738905GoodsPickupMethodcode提货方式代码1.1an.3代码集5.141838904GoodsPickupMethodDescription提货方式描述0.1an.171938973VehicleServiceTypeCode车辆服务类型代码0.1an.3代码集5.252033878Shipper托运人0.1an.1002133879ShipperCode托运人代码0.1an.50企业自定义223ConsignorInfo装货方信息0.12343336Consignor发货人0.1an.5122443337ConsignorCode发货人代码0.1an.17企业自定义2543412ContactName联系人姓名1.1an.256装货联系人姓名2643869TelphoneNumber联系电话1.1an.18装货联系人电话2743875MobileTelphoneNumber移动电话号码0.1an.182843228CountrySubdivisionName国家行政区划名称1.1an.702943229CountrySubdivisionCode国家行政区划代码0.1an.12代码集4.123043334PlaceOfLoading装货地点0.1an.2563132809RequestedLoadingDateTime要求装货时间0.1an.19YYYYMMDDhhmmss323ConsigneeInfo收货方信息0.13343132Consignee收货人0.1an.5123443133ConsigneeCode收货人代码0.1an.17企业自定义3543412ContactName联系人姓名1.1an.25收货联系人姓名3643869TelphoneNumber电话号码1.1an.18收货联系人电话3743875MobileTelphoneNumber移动电话号码0.1an.183843228CountrySubdivisionName国家行政区划名称1.1an.703943229CountrySubdivisionCode国家行政区划代码0.1an.12代码集4.124043160GoodsReceiptPlace收货地点1.1an.2564132821RequestedUnloadedDate要求卸货日期0.1an.19YYYYMMDDhhmmss4231825IsReturn是否回执0.1n1代码集5.244335077PriceCurrencyCode价格货币代码0.1an.3代码集4.604435004MonetaryAmount货币金额0.1n.18代收货款数量4531829ShippingNoteStatusCode托运单状态代码0.1an.3代码集4.574637824GoodsSelfNumber货物自编号0.1an.1004739842Remark备注0.1an.256483GoodsInfo货物信息1.n4947823AriticleNumber商品条码0.1an.355047819CargoHSNumber商品HS编码0.1an.10代码集4.365147820GoodsClassificationName货物分类名称0.1an.355247002DescriptionOfGoods货物名称1.1an.5125347832GoodsSpecification货物规格0.1an.355447338ArticleBatchNumber产品批次号0.1an.175547370TotalNumberOfPackages总件数1.1n.85647065PackageTypeCode包装类型代码1.1an.17代码集4.295743880GoodsOwner货主0.1an.1005849842Remark备注0.1an.255594ItemGrossWeight货物毛重0.16056292GoodsItemGrossWeight货物项毛重1.1n.166156411MeasurementUnitCode计量单位代码0.1an.3代码集4.28TNE：吨，KGM：千克，缺省千克624ItemValue货物体积0.16356322Cube体积0.1n.96456411MeasurementUnitCode计量单位代码0.1an.3代码集4.28MTQ：立方米，LTR：升，缺省立方米653ContainerInfo容器信息0.n6647828TransortEquipmentAccessoryName运输设备附件名称1.1an.206747823ArtticleNumber商品条码0.1an.356846810ContainerQuantity容器数量0.1n.6694ContainerGrossWeight容器毛重0.n7056292GoodsItemGrossWeight货物项毛重1.1n.167156411MeasurementUnitCode计量单位代码0.1an.3代码集4.28TNE：吨，KGM：千克，缺省千克724ContainerValue容器体积0.n7356322Cube体积1.1n.97456411MeasurementUnitCode计量单位代码0.1an.3代码集4.28MTQ：立方米，LTR：升，缺省立方米7549842Remark备注0.1an.2559.2 普通货物运输托运状态变化单上传当企业平台将托运状态发生改变时，需要将此托运状态变化的情况上传到监管平台。l 发送方：企业通过接口发送；l 发送方式：异步，通过接口的传输服务l 接收方：监管平台业务接口通过调用send接口来发送请求消息，在交换数据包中嵌入上传的普通运输托运状态变化单报文,其报文结构见下表。序号报文层数据元标识符XML标记中文名称出现次数数据类型引用文件说明11RootRoot1.122Header报文头1.1330062MessageReferenceNumber报文参考号1.1an.35报文唯一标识符，系统自动按照GUID规则生成431000DocumentName单证名称1.1an.35中文名称：普通运输托运状态变化单530052DocumentVersionNumber报文版本号1.1an.17V3.1639813SenderCode发送方代码0.1an.20交换代码，不填732863MessageSendingDateTime发送时间1.1an.19YYYYMMDDhhmmss831225MessageFunctionCode报文功能代码0.1an.3代码集4.592Body报文体1.11031802ShippingNoteNumber托运单号1.1an.201131820OriginalDocumentNumber原始单号0.1an.351231829ShippingNoteStatusCode托运单状态代码1.1an.3代码集4.571332867StatusChangeDateTime状态变更时间1.1an.19YYYYMMDDhhmmss1439842Remark备注1.1an.255描述关闭原因153DetailStatusInfo详细状态信息0.n1641812JobOrderNumber作业单号1.1an.501748802VehicleNumber车辆牌照号1.1an.351848819LicensePlateTypeCode牌照类型代码1.1an.20代码集4.481941833JobOrderStatusCode作业单状态代码1.1an.3代码集4.572048067TransportModeCode运输方式代码0.1an.3代码集4.39214Driver驾驶员1.12253412ContactName联系人姓名1.1an.2562353869TelphoneNumber联系电话1.1an.182443334PlaceOfLoading装货地点1.1an.2562542809RequestedLoadingDateTime要求装货时间0.1an.19YYYYMMDDhhmmss2642821RequestedUnloadedDate要求卸货日期0.1an.19YYYYMMDDhhmmss2742171DespatchActualDateTime发运实际日期1.1an.19YYYYMMDDhhmmss2842441GoodsReceiptDateTime收货日期0.1an.19YYYYMMDDhhmmss2942867StatusChangeDateTime状态变更时间1.1an.19YYYYMMDDhhmmss9.3 普通货物运输回执单上传当企业平台记录运输完成收到回执时，需要将此回执单的情况上传到监管平台。l 发送方：企业通过接口发送；l 发送方式：异步，通过接口的传输服务l 接收方：监管平台业务接口通过调用send接口来发送请求消息，在交换数据包中嵌入上传的普通运输回单报文,其报文结构见下表。序号报文层数据元标识符XML标记中文名称出现次数数据类型引用文件说明11RootRoot1.122Header报文头1.1330062MessageReferenceNumber报文参考号1.1an.35报文唯一标识符，系统自动按照GUID规则生成431000DocumentName单证名称1.1an.35中文名称：普通运输回单530052DocumentVersionNumber报文版本号1.1an.17V3.1639813SenderCode发送方代码0.1an.20交换代码，不填732863MessageSendingDateTime发送时间1.1an.19YYYYMMDDhhmmss831225MessageFunctionCode报文功能代码0.1an.3代码集4.592Body报文体1.11031802ShippingNoteNumber托运单号1.1an.201131820OriginalDocumentNumber原始单号0.1an.351231829ShippingNoteStatusCode托运单状态代码1.1an.3代码集4.571334440FreeText自由文本0.1an.512143ConsigneeInfo收货信息0.n1542441GoodsReceiptDateTime收货日期0.1an.19YYYYMMDDhhmmss1643160GoodsReceiptPlace收货地点1.1an.5121743042StreetAndNumberOrPOBox街道门牌号码/邮政信箱0.1an.2561843132Consignee收货人1.1an.701943412ContactName联系人姓名0.1an.2562043869TelphoneNumber电话号码0.1an.182143871FaxNumber传真号码0.1an.182241808IdentityDocumentNumber证件号0.1an.182351815PersonalIdentityDocumentTypeCode身份证件类别代码0.1an.3代码集5.12447817SignTypeCode签收类别代码0.1an.3代码集5.3254GoodsInfo货物信息0.n2657823 ArticleNumber商品条码 0.1an.35 2757819 CargoHSNumber货物HS编码 0.1an.10 代码集4.36 2857820GoodsClassificationName货物分类名称0.1an.352957002DecriptionOfGoods货物名称1.1an.5123057832GoodsSpecification货物规格0.1an.35315 7338 ArticleBatchNumber 产品批次号 0.1 an.35 325 7065 PackageTypeCode 包装类型代码 0.1 an.17 代码集4.29 335 7224 PackageQuantity 包装数量 1.1 n.8 345 6832 PackagesNumber 货物实收数量 1.1 n.6 355 6834 DamagePackagesNumber 货物破损数量 1.1 n.6 365 6836 RejectPackagesNumber 货物拒收数量 1.1 n.6 375 6838 MissingPackagesNumber 货物缺件数量 1.1 n.6 383 FreightCharges运输费用0.1394 5077 PriceCurrencyCode 价格货币代码 0.1 an.3 代码集4.60 404 5004 MonetaryAmount 货币金额 0.1 n.18 413CollectingFees 代收费用 0.1 424 5077 PriceCurrencyCode 价格货币代码 0.1 an.3 代码集4.60 434 5004 MonetaryAmount 货币金额 0.1 n.18 443 9842 Remark 备注 0.1 an.255 9.4 实际承运人信息上传企业平台需要每日定时将实际承运人明细数据上传到监管平台。l 发送方：企业通过接口定时发送；l 发送方式：异步，通过接口的传输服务l 接收方：监管平台业务接口通过调用send接口来发送请求消息，在交换数据包中嵌入上传的实际承运人信息报文,其报文结构见下表。序号报文层数据元标识符XML标记中文名称出现次数数据类型引用文件说明11RootRoot1.122Header报文头1.1330062MessageReferenceNumber报文参考号1.1an.35报文唯一标识符，系统自动按照GUID规则生成431000DocumentName单证名称1.1an.35中文名称：承运人信息530052DocumentVersionNumber报文版本号1.1an.17V3.1639813SenderCode发送方代码0.1an.20交换代码，不填732863MessageSendingDateTime发送时间1.1an.19YYYYMMDDhhmmss831225MessageFunctionCode报文功能代码0.1an.3代码集4.592Body报文体1.11033126CarrierName承运人名称1.1an.5121133127CarrierIdentifier承运人标识符0.1an.171233926PermitNumber营运许可证号1.1an.501339998InsureContent责任险投保详情1.1an.255143Vehicle