描述地区编码

统一物流接入规范(征求意见稿)GDZWxxxx-2019GDZWICSXxx备案号:201x-xx-xx发布201x-xx-xx实施xxx发布广东政务服务平台标准GDZWxxxx-201xI目次前言.
2引言.
31范围.
42规范性引用文件.
43术语和定义.
44接入要求.
44.
1网络要求.
44.
1.
1互联网接入.
44.
1.
2政务外网接入.
44.
2政务业务系统接入的前提要求.
55接入方式.
56接口定义.
56.
1获取邮件号服务接口.
56.
2查询省市县目录结构服务接口.
76.
3寄送邮件(新增物流信息)服务接口.
106.
4查询寄件记录服务接口.
136.
5查询寄件详细信息服务接口.
166.
6查询物流流转信息服务接口.
19GDZWxxxx-201x2前言本标准按GB/T1.
1-2009给出的规则起草.
GDZWxxxx-201x3引言统一物流服务是数字政府与第三方物流商的平台进行寄递请求、物流跟踪信息交换的平台.
通过统一物流服务,实现办事"不跑腿",物流信息自动传递,用户选择办件材料递送,平台可自动获取用户基本信息、办件编号信息,并且物流状态主动提醒,做到寄件"免填单",收件"不着急",办事无忧.
本规范提出了政务业务系统与统一物流服务平台之间快递物流数据对接的技术规范要求.
GDZWxxxx-201x4统一物流接入规范1范围本标准规定了政务业务系统与统一物流服务平台之间快递物流数据对接的技术规范要求.
本标准适用了政务业务系统接入省统一物流服务平台的技术要求.
2规范性引用文件下列文件对于本文件的应用是必不可少的.
凡是注日期的引用文件,仅注日期的版本适用于本文件.
凡是不注日期的引用文件,其最新版本(包括所有的修改单)适用于本文件.
《省公共支撑平台智能网关接入规范》3术语和定义下列术语和定义适用于本文件.
3.
1能力Capacity应用负责人可以在服务管理里对服务进行全生命周期的管理.
注:包括增、删、改、查、设置服务的高级属性、查找第三方服务、订阅服务、发布服务等操作.
3.
2API一些预先定义的函数,应用将自身的服务能力封装成API,并通过API网关开放给用户调用.
3.
3政务业务系统基于互联网技术的面向政府机关内部,其他政府机构的信息服务和信息处理系统.
3.
4统一物流服务平台提供了统一的物流服务接入、用户下单和用户查单能力,满足了统一物流服务需求的信息处理系统.
4接入要求4.
1网络要求4.
1.
1互联网接入互联网接入有:——提供HTTPS协议的接口;——提供内容加密的HTTP协议接口.
4.
1.
2政务外网接入使用与互联网服务保持相同加密级别.
GDZWxxxx-201x54.
2政务业务系统接入的前提要求接入服务的政务业务系统需申请智能网关应用授权,并订阅发布在智能网关上的统一物流平台服务.
通过后获得分配的凭证信息(passid和passtoken),再凭借passid、passtoken通过智能网关鉴权后才能调用接口服务.
具体申请智能网关应用授权请参考《省公共支撑平台智能网关接入规范》.
5接入方式5.
1通过API接口集成的方式,提供统一物流服务能力,实现对物流业务处理.
5.
2通过【获取邮件号服务接口】、【查询省市县目录结构服务接口】、【寄送邮件(新增物流信息)服务接口】进行集成下单寄件.
5.
3通过【查询寄件记录服务接口】、【查询寄件详细信息服务接口】、【查询物流流转信息服务接口】进行集成查询订单.
6接口定义接口是一组定义、程序及协议的集合,通过API接口实现系统间的相互通信.
统一物流服务能力通过API接口集成的方式进行提供.
6.
1获取邮件号服务接口1).
接口描述此接口用于预先获取邮件号,作为快递的唯一标识.
2).
请求方式POST3).
请求域名/tywl/openapi/getMailNums4).
输入参数参数名中文名称类型长度必选描述cust_token接入IDString32是由统一物流平台分配给业务接入方.
express_type物流类型String0~30是GD-EMS:广东邮政EMS;amount请求的邮件号个数Number-是请求的邮件编码个数;最大50个.
输入示例:{"amount":1,"cust_token":"e8ca2eecdea46815423d06cbccccaaaa","express_type":"GD-EMS"}GDZWxxxx-201x65).
返回参数参数名中文名称类型长度必选描述errcode请求结果代码Number-是0:成功;-1:系统内部异常;1:参数错误;2:业务失败.
errormsg错误描述String-否错误描述,当errcode不为0时,描述发生错误的信息.
detailErrMsg错误详细描述String-否错误详细信息描述.
hintString-否result结果描述String-否data邮件号信息集合Object[]-否数组集合,一个邮件号一个Object.
结构体参数:【data】:序号参数名中文名称类型长度必选描述1mail_num邮件号String0~50是邮件号.
输出示例1:数据新增成功示例{"result":null,"errcode":0,"errormsg":null,"detailErrMsg":null,"hint":null,"data":[{"mail_num":"1112223334445"},{"mail_num":"1112223334446"},{"mail_num":"1112223334447"}]}输出示例2:数据新增失败示例{"result":null,"errcode":1,GDZWxxxx-201x7"errormsg":"接入授权信息不存在","detailErrMsg":null,"hint":null,"data":null}6.
2查询省市县目录结构服务接口1).
接口描述此接口用于获取省市县的目录结构,联动查询.
2).
请求方式POST3).
请求域名/tywl/openapi/getDist4).
输入参数参数名中文名称类型长度必选描述cust_token接入IDString32是由统一物流平台分配给业务接入方.
parent_code上级地区编码String-否如:"440100";level为1时,parent_code可以为空.
level地区级别Number-是1:省级;2:市级;3:县级.
输入示例:{"parent_code":"440100","cust_token":"e8ca2eecdea46815423d06cbccccaaaa","level":3}5).
返回参数参数名中文名称类型长度必选描述errcode结果代码Number-是0:成功;-1:系统内部异常;1:参数错误;2:业务失败.
errormsg错误描述String-否错误描述,当errcode不为0时,描述发生错误的信息.
detailErrMsg错误详细描述String-否错误详细信息描述.
hintString-否result结果描述String-否GDZWxxxx-201x8参数名中文名称类型长度必选描述data省市县地区信息集合Object[]-否数据集合;一个地区信息一个Object.
结构体参数:【data】:序号参数名中文名称类型长度必选描述1address_code地区编码String-是如:"440100".
2address_name地区名称String-是如:广州市3level地区级别Number-是1:省级;2:市级;3:县级.
4parent_code上级地区编码String-是输出示例1:数据新增成功示例{"result":null,"errcode":0,"errormsg":null,"detailErrMsg":null,"hint":null,"data":[{"level":3,"parent_code":"440100","address_code":"440103","address_name":"荔湾区"},{"level":3,"parent_code":"440100","address_code":"440104","address_name":"越秀区"},{"level":3,"parent_code":"440100","address_code":"440105","address_name":"海珠区"},{"level":3,"parent_code":"440100","address_code":"440106","address_name":"天河区"GDZWxxxx-201x9},{"level":3,"parent_code":"440100","address_code":"440111","address_name":"白云区"},{"level":3,"parent_code":"440100","address_code":"440112","address_name":"黄埔区"},{"level":3,"parent_code":"440100","address_code":"440113","address_name":"番禺区"},{"level":3,"parent_code":"440100","address_code":"440114","address_name":"花都区"},{"level":3,"parent_code":"440100","address_code":"440115","address_name":"南沙新区"},{"level":3,"parent_code":"440100","address_code":"440117","address_name":"从化区"},{"level":3,"parent_code":"440100","address_code":"440118","address_name":"增城区"}]}GDZWxxxx-201x10输出示例2:数据新增失败示例{"result":null,"errcode":1,"errormsg":"接入授权信息不存在","detailErrMsg":null,"hint":null,"data":null}6.
3寄送邮件(新增物流信息)服务接口1).
接口描述此接口用于寄送邮件,根据用户填写的收寄信息和物流类型进行寄件,在物流系统中新增邮件订单信息2).
请求方式POST3).
请求域名/tywl/openapi/addOrder4).
输入参数参数名中文名称类型长度必选描述cust_token接入IDString32是由统一物流平台分配给业务接入方.
express_type物流类型String-是GD-EMS:广东邮政EMS;mail_info_list邮件信息集合Object[]-是数组集合,寄送的邮件信息集合;一份邮件信息一个Object.
remarks备注String0~100是如:"请优先收件"等备注信息.
结构体参数:【mail_info_list】:序号参数名中文名称类型长度必选描述1mail_num邮件号String0~50否邮件号,可从"获取邮件号"接口获取.
2receiver_info邮件收件方信息Object-是3sender_info邮件寄件方信息Object-是结构体参数:【receiver_info】:序号参数名中文名称类型长度必选描述GDZWxxxx-201x11序号参数名中文名称类型长度必选描述1person_name收件方联系人姓名String0~30是2person_phone收件方联系电话String0~30是3province收件方所在省String0~20是如:"广东省"4city收件方所在市String0~20是如:"广州市"5county收件方所在区县String0~20是如:"海珠区"6detail_address收件方详细地址String0~50是如:"新港中路1000号"7post_num收件方邮编String0~20是如:"510000"结构体参数:【sender_info】:序号参数名中文名称类型长度必选描述1person_name寄件方联系人姓名String0~30是2person_phone寄件方联系电话String0~30是3province寄件方所在省String0~20是如:"广东省"4city寄件方所在市String0~20是如:"广州市"5county寄件方所在区县String0~20是如:"海珠区"6detail_address寄件方详细地址String0~50是如:"新港中路1000号"7post_num寄件方邮编String0~20是如:"510000"输入示例:{"express_type":"GD-EMS","cust_token":"e8ca2eecdea46815423d06cbccccaaaa","remarks":"请优先派送","mail_info_list":[{"mail_num":"2381927481","receiver_info":{"person_phone":"15678908987","detail_address":"华南理工大学","province":"广东省","county":"白云区","person_name":"lisi","city":"广州市","post_num":"500089"},"sender_info":{"post_num":"500072","county":"白云区",GDZWxxxx-201x12"person_phone":"13467862345","province":"广东省","person_name":"zahngsan","detail_address":"TIT创意园氪空间110","city":"广州市"}}]}5).
返回参数参数名中文名称类型长度必选描述errcode结果代码Number-是0:成功;-1:系统内部异常;1:参数错误;2:业务失败.
errormsg错误描述String-否错误描述,当errcode不为0时,描述发生错误的信息.
detailErrMsg错误详细描述String-否错误详细信息描述.
hintString-否result结果描述String-否data邮件信息集合Object[]-否业务成功时,返回寄件成功的邮件信息,一个邮件信息一个Object结构体参数:【data】:序号参数名中文名称类型长度必选描述1id邮件IdString32是邮件信息在物流平台中的唯一Id.
输出示例1:数据新增成功示例{"result":null,"errcode":0,"errormsg":null,"detailErrMsg":null,"hint":null,"data":[{"id":"585791566442921885"}]}GDZWxxxx-201x13输出示例2:数据新增失败示例{"result":null,"errcode":1,"errormsg":"接入授权信息不存在","detailErrMsg":null,"hint":null,"data":null}6.
4查询寄件记录服务接口1).
接口描述此接口用于根据指定条件查询寄件订单记录2).
请求方式POST3).
请求域名/tywl/openapi/queryOrder4).
输入参数参数名中文名称类型长度必选描述cust_token接入IDString32是由统一物流平台分配给业务接入方.
express_type物流类型String-否GD-EMS:广东邮政EMSmail_num邮件号String-否sender_person_name寄件方联系人姓名String-否receiver_person_name收件方联系人姓名String-否receiver_province收件方所在省String-否如:"内蒙古"、"内蒙"receiver_city收件方所在市String-否如"广州"、"广州市"receiver_county收件方所在区县String-否如:"海珠"、"海珠区"receiver_detail_address收件方详细地址String-否如:"新港中路"page页码Number-是page<1时,默认为1.
size每页显示的数据量Number-是Size<1时,默认为15.
GDZWxxxx-201x14输入示例:{"cust_token":"e8ca2eecdea46815423d06cbccccaaaa","size":15,"page":1,"express_type":"","receiver_province":"","mail_num":"","receiver_city":"","sender_person_name":"zahngsan","receiver_county":"","receiver_person_name":"","receiver_detail_address":"大学"}5).
返回参数参数名中文名称类型长度必选描述errcode结果代码Number-是0:成功;-1:系统内部异常;1:参数错误;2:业务失败.
errormsg错误描述String-否错误描述,当errcode不为0时,描述发生错误的信息.
detailErrMsg错误详细描述String-否错误详细信息描述.
hintString-否result结果描述String-否data寄件信息记录查询结果Object-否结构体参数:【data】:序号参数名中文名称类型长度必选描述1page页码-是2size每页显示的数据量-是3rows寄件信息记录Object[]-否数据集合,一条寄件信息记录一个Object.
结构体参数:【rows】:序号参数名中文名称类型长度必选描述1id邮件IdString32是邮件信息在物流平台中的唯一Id.
2express_type物流类型String-否GD-EMS:广东邮政GDZWxxxx-201x15序号参数名中文名称类型长度必选描述EMS;3mail_num邮件号String-否4sender_person_name寄件方联系人姓名String0~30是5sender_province寄件方所在省String0~20是如:"广东省"6sender_city寄件方所在市String0~20是如:"广州市"7sender_county寄件方所在区县String0~20是如:"海珠区"8sender_detail_address寄件方详细地址String0~50是如:"新港中路1000号"9receiver_person_name收件方联系人姓名String0~30是10receiver_province收件方所在省String0~20是如:"广东省"11receiver_city收件方所在市String0~20是如:"广州市"12receiver_county收件方所在区县String0~20是如:"海珠区"13sender_detail_address收件方详细地址String0~50是如:"新港中路1000号"14status邮件状态String2是00:收寄10:妥投20:未妥投30:经转过程中40:离开处理中心41:到达处理中心50:安排投递51:正在投递60:揽收输出示例1:数据新增成功示例{"result":null,"errcode":0,"errormsg":null,"detailErrMsg":null,"hint":null,"data":{"size":15,"page":1,"rows":[{GDZWxxxx-201x16"id":"585791566442921885","express_type":"EMS","mail_num":"1117825261013","sender_person_name":"zahngsan","sender_province":"广东省","sender_city":"广州市","sender_county":"白云区","sender_detail_address":"TIT创意园氪空间110","receiver_person_name":"lisi","receiver_province":"广东省","receiver_city":"广州市","receiver_county":"白云区","receiver_detail_address":"华南理工大学","status":"01"},{"id":"588395082307075897","express_type":"EMS","mail_num":"1117825261013","sender_person_name":"zahngsan","sender_province":"广东省","sender_city":"广州市","sender_county":"白云区","sender_detail_address":"TIT创意园氪空间110","receiver_person_name":"lisi","receiver_province":"广东省","receiver_city":"广州市","receiver_county":"白云区","receiver_detail_address":"华南理工大学","status":"02"}]}}输出示例2:数据新增失败示例{"result":null,"errcode":1,"errormsg":"接入授权信息不存在","detailErrMsg":null,"hint":null,"data":null}6.
5查询寄件详细信息服务接口GDZWxxxx-201x171).
接口描述此接口用于根据邮件Id查询寄件详细信息2).
请求方式POST3).
请求域名/tywl/openapi/queryOrderDetail4).
输入参数参数名中文名称类型长度必选描述cust_token接入IDString32是由统一物流平台分配给业务接入方.
id邮件IdString32是邮件信息在物流平台中的唯一Id.
输入示例:{"cust_token":"e8ca2eecdea46815423d06cbccccaaaa","id":"585791566442921885"}5).
返回参数参数名中文名称类型长度必选描述errcode结果代码Number-是0:成功;-1:系统内部异常;1:参数错误;2:业务失败.
errormsg错误描述String-否错误描述,当errcode不为0时,描述发生错误的信息.
detailErrMsg错误详细描述String-否错误详细信息描述.
hintString-否result结果描述String-否data邮件详细信息Object-否结构体参数:【data】:序号参数名中文名称类型长度必选描述1id邮件IdString32是邮件信息在物流平台中的唯一Id.
2express_type物流类型String-否GD-EMS:广东邮政EMS;3mail_num邮件号String-否GDZWxxxx-201x18序号参数名中文名称类型长度必选描述4sender_person_name寄件方联系人姓名String0~30是5sender_phone寄件方联系电话String0~30是6sender_province寄件方所在省String0~20是如:"广东省"7sender_city寄件方所在市String0~20是如:"广州市"8sender_county寄件方所在区县String0~20是如:"海珠区"9sender_detail_address寄件方详细地址String0~50是如:"新港中路1000号"10receiver_person_name收件方联系人姓名String0~30是11receiver_phone收件方联系电话String0~30是12receiver_province收件方所在省String0~20是如:"广东省"13receiver_city收件方所在市String0~20是如:"广州市"14receiver_county收件方所在区县String0~20是如:"海珠区"15sender_detail_address收件方详细地址String0~50是如:"新港中路1000号"16status邮件状态String2是00:收寄10:妥投20:未妥投30:经转过程中40:离开处理中心41:到达处理中心50:安排投递51:正在投递60:揽收17remarks备注String0~100否输出示例1:数据新增成功示例{"result":null,"errcode":0,"errormsg":null,"detailErrMsg":null,"hint":null,"data":{"id":"585791566442921885","express_type":"EMS",GDZWxxxx-201x19"mail_num":"1117825261013","sender_person_name":"zahngsan","sender_province":"广东省","sender_city":"广州市","sender_county":"白云区","sender_detail_address":"TIT创意园氪空间110","receiver_person_name":"lisi","receiver_province":"广东省","receiver_city":"广州市","receiver_county":"白云区","receiver_detail_address":"华南理工大学","status":"01","sender_phone":"13467862345","receiver_phone":"15678908987","remarks":null}}输出示例2:数据新增失败示例{"result":null,"errcode":1,"errormsg":"接入授权信息不存在","detailErrMsg":null,"hint":null,"data":null}6.
6查询物流流转信息服务接口1).
接口描述此接口用于查询物流流转信息.
2).
请求方式POST3).
请求域名/tywl/openapi/queryTrackInfo4).
输入参数参数名中文名称类型长度必选描述cust_token接入IDString32是由统一物流平台分配给业务接入方.
express_type物流类型String-是GD-EMS:广东邮政EMS;GDZWxxxx-201x20参数名中文名称类型长度必选描述mail_num邮件号String-是mail_send_info_id邮件IdString32是邮件信息在物流平台中的唯一Id.
输入示例:{"mail_send_info_id":"585791566442921885","cust_token":"e8ca2eecdea46815423d06cbccccaaaa","express_type":"GD-EMS","mail_num":"dskflk"}5).
返回参数参数名中文名称类型长度必选描述errcode结果代码Number-是0:成功;-1:系统内部异常;1:参数错误;2:业务失败.
errormsg错误描述String-否错误描述,当errcode不为0时,描述发生错误的信息.
detailErrMsg错误详细描述String-否错误详细信息描述.
hintString-否result结果描述String-否data邮件物流流转信息集合Object[]-否数据集合,一条物流流转信息一个Object结构体参数:【data】:序号参数名中文名称类型长度必选描述1mail_num邮件号String-是2track_info物流流转信息Object-是结构体参数:【track_info】:序号参数名中文名称类型长度必选描述1deal_address流转地点String-否2deal_time流转时间String-否格式:yyyy-mm-ddhh24:mi:ss3remarks流转描述String-否GDZWxxxx-201x21输出示例1:数据新增成功示例{"result":null,"errcode":1,"errormsg":"接入授权信息不存在","detailErrMsg":null,"hint":null,"data":{"mail_num":"XXXXX","track_info":[{"remarks":"XXXX","deal_address":"XXX","deal_time":"XXXXXXX"},{"remarks":"XXXX","deal_address":"XXX","deal_time":"XXXXXXX"}]}}输出示例2:数据新增失败示例{"result":null,"errcode":1,"errormsg":"接入授权信息不存在","detailErrMsg":null,"hint":null,"data":null}