国税网络开票机接口规范ednb.docx

网络开票机接口设计江苏爱信诺航天信息科技有限公司历 史 版 本版本日期作者修改内容批准人1.02010-07李方平初始化版本PM1.12012-03张世科接口eInfo增加减免信息增加接口更新减免品目Request报文增加isZip1.22012-3-9张世科支持税控机升级接口eInfo增加减免信息限开标志1.32012-3-21张世科接口eInfo返回数据增加时间，格式：yyyy-MM-dd hh:mm:ss，用于授时2.02012-10-21马晓龙更新支持票种，增加接口2.12012-12-04马晓龙增加作废接口2.22012-12-17马晓龙下载发票明细接口名修改为fpPmnr2.32012-12-24马晓龙修改上传发票加密需求2.42013-01-04马晓龙1.增加分机接口2.实现密码加密3.修改购票请求接口2.52013-1-16马晓龙增加zipMode结点，支持处理GZIP2.62013-3-13张伟3.2.2 lgrq 改成 gpts3.8.2 发送报文改动2.72013-4-1张伟章节3.4.2 和 章节4.8.3 的XML中增加s_fp_dm（源发票代码）s_fpqh（源发票号码）2.82013-4-2马晓龙完善3.6升级接口2.92013-4-11马晓龙章节3.4.2 和4.8.3中增加userId2.102013-4-16马晓龙增加3.12，修改3.62.112013-4-25张伟增加3.13 修改密码2.122013-6-5张伟3.2.3 返回报文中增加mbfs（每本份数）字段2.132013-11-5张伟3.4上传发票请求接口中需要上传客户端的版本号2.142013-11-7张伟报文头中增加securitysecurityModeinterfaceVersion节点目录1.开通流程62.交互说明72.1交互方式72.2交互URL72.3交互基本结构72.3.1提交报文73.报文说明93.1企业基本信息请求93.1.1功能描述93.1.2提交报文93.1.3返回报文93.2购票请求113.2.1功能描述113.2.2提交报文113.2.3返回报文113.3验证码请求133.3.1功能描述133.3.2提交报文133.3.3返回报文143.4上传发票请求143.4.1功能描述143.4.2提交报文143.4.3返回报文303.5更新减免品目303.5.1功能描述303.5.2提交报文303.5.3返回报文313.6网络开票机升级313.6.1功能描述313.6.2提交报文313.6.3返回报文313.7网络授时323.7.1功能描述323.7.2提交报文323.7.3返回报文323.8发票下载323.8.1功能描述323.8.2提交报文323.8.3返回报文333.9作废发票353.9.1功能描述353.9.2提交报文353.9.3返回报文353.10发票分发353.10.1功能描述353.10.2提交报文353.10.3返回报文383.11分机退票383.11.1功能描述383.11.2提交报文383.11.3返回报文393.12下载文件393.12.1功能描述393.12.2提交报文393.12.3返回报文393.13修改密码403.13.1功能描述403.13.2提交报文403.13.3返回报文404.附录403.14江苏国税卷式票目录403.15江苏国税平推式发票目录403.16实例423.16.1购票请求433.16.2上传发票请求435.其他451. 开通流程开通暂定由手工开通。税控机厂商提供需开通的税控机名单(格式下文中描述)，由我方开通后返回开通成功的税控机名单(含许可码)给税控机厂商。开通简要流程：税控机厂商提供如下格式的文本文件：机器码,用户ID（用户ID格式为税号+“_*”,*为两位分机号，取值01-99，如无分机，此处与税号一致）如：0712098123456780,3201010000000010712098123456790, 320101000000001_01返回许可码如下：许可码：b7876850b8331a3初始密码：机器码后6位。2. 交互说明122.1 交互方式终端访问CICS web服务器（目前各地级市分别部署）的一个URL，通过HTTP协议连接，均采用POST方法，采用XML格式进行数据封装，提交一个XML，返回一个XML，HTTP协议版本1.1以上。2.2 交互URLCICS URL格式： http:/cicsserver:port/uamsService.htm测试示例：http:/222.190.120.106:7002/uamsService.htm,此处随地级市变动而变动。升级URL: http:/222.190.120.106:7001/service.htm ，仅升级使用，此处唯一。2.3 交互基本结构2.3.1 提交报文<?xml version="1.0" encoding="GBK" ?><request><type>请求类型eInfo|fsInfo |upload</type><param><id>机器码</id><userId>用户ID（新增）</userId><nsrsbh>纳税人识别号</nsrsbh><key>许可码</key><password>登录密码（密码安全见下文）</password><csDm>厂商代码06</csDm><cpDm>产品代码06</cpDm><isZip>0-不压缩，默认1压缩</isZip><zipMode>ZIP或 GZIP(如无结点或结点为空，默认为ZIP)</zipMode><security>密文</security><securityMode>加密模式（规则见下文）</securityMode><interfaceVersion>接口报文版本号，当前版本号为1.0</interfaceVersion></param><content><!CDATA></content></request>1.请求类型：type=如下表所示序号请求类型说明备注1eInfo获取企业信息2fsInfo获取购票信息3verifyUser上传验证请求上传发票前4upload上传发票5updateJmpm更新减免品目6updateSkj升级税控机注意服务器地址是升级URL7syncTime时间同步8fpPmnr下载发票9fpCancel作废发票10dispense发票分发11withdrawal分机退票12downloadFile下载文件13password修改密码2.password采用密文方式传输，加密规则：password+“JSAISINO”,使用MD5加密（16位），编码为GBK。输入：admin密码JSAISINO输出：7044199e707bd3623.interfaceVersion报文版本号，目前版本是1.03. securityMode规则 暂时只支持MD5（16位）方式加密填写1或留空则为MD5（16位）加密，编码GBK 4. security 存放密文 例如，加密串：2013110711，MD5加密后：7e7e051d1c357eb1<security>7e7e051d1c357eb1</ security>返回报文服务端根据相应请求返回相关细细，返回的xml会写入如下结构CDATA中，并把如下整个xml返回。<?xml version="1.0" encoding="GBK"?><RESPONSE STATUS=”SUCCESS|FATAL”><TYPE>请求类型</TYPE><ALERT>若STATUS为FATAL时在此处写入失败原因</ALERT><CONTENT><!CDATA></CONTENT></RESPONSE>3. 报文说明33.1 企业基本信息请求3.1.1 功能描述根据纳税人识别号返回企业基本信息。3.1.2 提交报文发送时遵从2.3.1的结构请求类型(type)为eInfo,依次写入相关参数(param)。3.1.3 返回报文<?xml version="1.0" encoding="GBK"?><business><group> <nsrsbh>纳税人识别号</nsrsbh> <nsrmc>纳税人名称</nsrmc> <nsrSwjgDm>纳税人税务机关代码</nsrSwjgDm> <khyh>开户银行</khyh><yhzh>银行账号</yhzh><scjydz>生产经营地址</scjydz><dhhm>电话号码</dhhm><lxsj>离线时间 单位为天，例：2</lxsj><jmXx> <zqjmfsDm>征前减免方式</zqjmfsDm> <jms>减免数</jms> <jmyyDm>减免原因代码</jmyyDm> <xkbz>限开标志</xkbz></jmXx><jmXx><zqjmfsDm>征前减免方式</zqjmfsDm><jms>减免数</jms><jmyyDm>减免原因代码</jmyyDm><xkbz>限开标志</xkbz></jmXx><sj>时间，格式：yyyy-MM-dd hh:mm:ss</sj></group>只支持单户企业下载<business>说明：jmXx 减免信息，没有减免就没有该节点，将来有多个减免种类时，可能多节点,有该节点时可以调用updateJmpm接口，下载减免品目。zqjmfsDm征前减免方式:01按幅度减免,02按额度减免,03优惠税率。jms减免数，zqjmfsDm=01 时，jms为减免百分比,0.3就是减免30%，1就是全免。jmyyDm 减免原因代码，如：A_2011_137，财税2011137号免征蔬菜。xkbz限开标志 1限制只能开指定品目，0不限开。3.2 购票请求3.2.1 功能描述根据参数获取企业购票信息。3.2.2 提交报文发送购票请求根据2.3.1中定义，type为fsInfo，依次写入相关信息。<gpts>购票天数（数字，例如：90）</gpts>3.2.3 返回报文<?xml version="1.0" encoding="GBK"?><business ><group><fpDm>发票代码</fpDm><fpqh>发票号码起</fpqh><dqhm>当前号码</dqhm><fpzh>发票号码止</fpzh><userId >用户ID</userId ><fpzlDm>发票种类代码</fpzlDm><fpzlMc>发票名称</fpzlMc><lgrq>领购日期</lgrq><jobId>领购ID</jobId><kjlx></kjlx><kpxe>开票限额</kpxe><jgsj>间隔时间</jgsj><mbfs>每本份数</mbfs></group><group> 多条购票记录</group ></business>实例：<?xml version="1.0" encoding="GBK"?><business JSAISINO_QR="TRUE"><group><fp_dm>132061280530</fp_dm><fpqh>00698001</fpqh><dqhm>00698031</dqhm><fpzh>00702000</fpzh><userId>32060207WT06030</userId><fpzl_dm>28053</fpzl_dm><fpzl_mc>通用机打平推式发票</fpzl_mc><lgrq>2012-11-19</lgrq><jxqx></jxqx><jobId>32060207WT06030_132061280530_00698001</jobId><kjlx></kjlx><kpxe></kpxe><jgsj>2</jgsj><mbfs>200</mbfs></group></business>税控机开发商在开发时应注意一下几点：1）该购票信息为实时购票信息，剔除了验旧缴销票；2) 用户第一次使用(即请求的gpts为空值时)返回该企业三个月前到现在的所有可开票记录；3) 非第一次使用(即请求的gpts有值时)返回从最后一次购票日期开始，到当前止的所有可开票记录4) CTAIS的EJB取票时最小时间单位只精确到月。因此在开发过程中应注意，下载购票信息时返回的票，有可能会与税控机前几次下载的票相等或有交集，开发商在开发过程中应注意比对。5）kpxe如为空，则不限票面金额；如有值，票面金额不得大于限额。6）jgsj如为空，默认为2。7）购票记录返回的是该企业所有领购的发票，机具应根据自身票种支持性过滤其他种类发票；3.3 验证码请求3.3.1 功能描述从后台服务器获取上传所需验证码。3.3.2 提交报文上传发票前先上传一个验证的请求，获取返回验证码<?xml version="1.0" encoding="GBK" ?><request><type>verifyUser</type><param><id>机器码</id><nsrsbh>纳税人识别号</nsrsbh><password>登录密码</password><key>许可码</key><csDm>厂商代码06</csDm><cpDm>产品代码06</cpDm></param><content><!CDATA></content></request>3.3.3 返回报文验证返回，如验证成功会在CDATA中返回一个验证码。<?xml version="1.0" encoding="GBK"?>< RESPONSE STATUS=”SUCCESS|FATAL”><TYPE>请求类型</TYPE><ALERT>若STATUS为FATAL时在此处写入失败原因</ALERT><CONTENT><!CDATA验证码></CONTENT></RESPONSE>3.4 上传发票请求3.4.1 功能描述将企业开具发票上传至后台服务器。注：801804为限额票，金额不能大于10000元。 805808不限额，但税局也可以对个别企业开票金额进行限制。在购票请求中可以取到限额。3.4.2 提交报文上传处理为确保开票信息传输的效率与安全性，税控机开发商需把XML文件先压缩再加密，再采用Base64编码后放入CDATA中上传。打包只针对上传发票请求，其他请求与返回不采用此方式。之所以先压缩再加密，是因为直接对发票内容XML压缩效率高。采用标准ZIP算法压缩采用对称加密DES算法密钥： NjtwxXmJ密钥编码：UTF8由于DES算法采用的是64位加密方法，所以有8字节补齐的事项。加密前：数据字节长度对8取余，余数为m，若m>0,则补足8-m个字节，字节数值为8-m，即差几个字节就补几个字节，字节数值即为补充的字节数，若为0则补充8个字节的8    解密后：取最后一个字节，值为m，则从数据尾部删除m个字节，剩余数据即为加密前的原文   比如差三个字节就要填补3个3: XXXXX333    没有差就填补8个8:88888888采用BASE64编码上传发票请求，存放在基本结构里的CDATA中，上传发票要等验证请求通过后才能上传，且上传时要把验证码加入上传xml中，存放在基本结构中作为<param>的子节点，节点名称为code。<?xml version="1.0" encoding="GBK" ?><request><type> upload </type><param><id>机器码</id><nsrsbh>纳税人识别号</nsrsbh><password>登录密码（此处为新增内容）</password><key>许可码</key><csDm>厂商代码06</csDm><cpDm>产品代码06</cpDm><code>验证码</code><security>密文</security><securityMode>加密模式</securityMode><interfaceVersion>报文版本号</interfaceVersion></param><content><!CDATA></content></request><?xml version="1.0" encoding="GBK" ?><park><nsrsbh>开票方纳税人识别号</nsrsbh><param><version>客户端版本号</version></param><invoice> <item> <id.fpDm>发票代码</id.fpDm> <id.fpqh>发票起号</id.fpqh><fpzh>发票止号</fpzh> <fpzlDm3>3位发票代码，根据12位发票代码获取第8位到第10位</fpzlDm3> <fpzlDm>发票种类代码</fpzlDm> <fs>份数</fs> <lylx>来源类型，类型为8</lylx><pm>最大金额品名</pm> <sl>最大金额数量</sl> <je>金额</je> <kprq>日期（yyyyMMdd）</kprq> <zfbz>作废标志，1表示作废，0表示正常</zfbz> <kpfNsrsbh>售货方税号</kpfNsrsbh> <kpfMc>售货方名称</kpfMc> <kpfLxdh>售货方电话</kpfLxdh> <kpfLxdz>售货方地址</kpfLxdz> <kpfKhyh>售货方开户银行</kpfKhyh> <kpfYhzh>售货方银行账号</kpfYhzh> <ghfNsrsbh>购货方税号</ghfNsrsbh> <ghfMc>购货方名称</ghfMc> <ghfLxdz>购货方地址</ghfLxdz> <ghfLxdh>购货方电话</ghfLxdh> <ghfKhyh>购货方开户银行</ghfKhyh> <ghfYhzh>购货方银行账号</ghfYhzh> <kpr>开票人</kpr><skr>收款人</skr><sjKpfNsrsbh>实际开票方纳税人识别号</sjKpfNsrsbh><sjKpfMc>实际开票方名称</sjKpfMc><nsrSwjgDm>实际开票方税务机关代码</nsrSwjgDm><s_fp_dm>原发票代码（开具负数发票时需有值，正常发票留空即可）</s_fp_dm><s_fpqh>原发票号码（开具负数发票时需有值，正常发票留空即可）</s_fpqh><userId>用户登录名</userId>(一般为税号，如果是分机用户，则为分机名称) <detail> <record> <pm>品名即项目</pm> <ggxh>规格型号</ggxh> <jldw>计量单位</jldw> <sl>数量</sl> <dj>单价</dj> <je>金额</je> </record> 多个发票明细. </detail> </item> 多张发票. </invoice></park>注意：XML节点名称有大小写区分；id.fpDm、id.fpqh由于是复合主键，注意这种点分隔的表达方式；行政区划取意为CTAIS相关概念，尽量明细到开票方所在地区；3位发票种类代码来自于江苏省国家税务局发票样本2010年版本。发票主体内容数据类型描述：名称对应字段数据类型为主键不能为空发票代码id.fpDmvarchar(12)TRUETRUE发票起号id.fpqhvarchar(8)TRUETRUE发票止号fpzhvarchar(8)FALSEFALSE3位发票种类fpzlDm3varchar(3)FALSETRUE发票种类代码fpzlDmvarchar(5)FALSETRUE份数fsnumeric(10,0)FALSETRUE来源类型lylxintFALSETRUE最大金额品名pmvarchar(128)FALSEFALSE最大金额数量slnumeric(16,8)FALSEFALSE金额jenumeric(16,2)FALSETRUE开票日期kprqDatetimeFALSETRUE作废标志zfbzSmallintFALSETRUE售货方税号kpfNsrsbhvarchar(32)FALSEFALSE售货方名称kpfMcvarchar(128)FALSEFALSE售货方电话kpfLxdhvarchar(60)FALSEFALSE售货方地址kpfLxdzvarchar(200)FALSEFALSE售货方开户银行kpfKhyhvarchar(200)FALSEFALSE售货方银行账号kpfYhzhvarchar(50)FALSEFALSE购货方税号ghfNsrsbhvarchar(20)FALSEFALSE购货方名称ghfMcvarchar(128)FALSEFALSE购货方地址ghfLxdzvarchar(200)FALSEFALSE购货方电话ghfLxdhvarchar(60)FALSEFALSE购货方开户银行ghfKhyhvarchar(200)FALSEFALSE购货方银行账号ghfYhzhvarchar(50)FALSEFALSE开票人kprvarchar(16)FALSEFALSE收款人skrvarchar(16)FALSEFALSE实际开票方纳税人识别号sjKpfNsrsbhvarchar(32)FALSETRUE实际开票方名称sjKpfMcvarchar(128)FALSETRUE实际开票方税务机关代码nsrSwjgDmvarchar(11)FALSETRUE原发票代码s_fp_dmvarchar(12)FALSEFALSE原发票起号s_fpqhvarchar(8)FALSEFALSE3.4.2.1 明细说明（平推票）发票明细内容数据结构描述：明细主表名称对应字段数据类型为主键不能为空品名pmvarchar(16)FALSEFALSE规格型号ggvarchar(16)FALSEFALSE计量单位jldwvarchar(16)FALSEFALSE数量slvarchar(16)FALSEFALSE金额jevarchar(16)FALSEFALSE单价djvarchar(16)FALSEFALSE以下各发票代码中的明细都继承此表。例如：发票代码 80111 发票的XML内容格式是：<?xml version="1.0" encoding="GBK" ?><park><param><version>客户端版本号</version></param><invoice><item><id.fpDm>发票代码</id.fpDm><id.fpqh>发票起号</id.fpqh><fpzh>发票止号</fpzh>略过其他节点<detail> <record><bz>备注</bz><dj>单价</dj><gg>规格</gg><je>金额</je><jldw>单位</jldw><pm>品名</pm><sl>数量</sl></record>.record可以有多个</detail><fhr>复核人</fhr><invoice></ park>3.4.2.1.1 工商业（11）主表：名称说明fhr复核人明细：不同的票种不同的行数：80111、80511：3行80211、80611：4行80311、80711：15行80411、80811：5行名称对应字段继承明细主表bz备注3.4.2.1.2 出口（12）主表：名称说明hth合同号contractNo合同号英文myfs贸易方式trade贸易方式英文xyzh信用证号lcNo信用证号英文receivUnit出售单位英文payUnit购货方英文date日期英文ybh运编号issued开证银行英文qtsx其他事项csfdz出售方英文地址ghfdz购售方英文地址telNo电话英文wbdxje外币大写金额wbJe外币金额biZhong币种bzMc币种名称huiLv汇率hlSz汇率数值slhj数量合计明细：不同的票种不同的行数：80312、80712：15行80812：5行名称对应字段继承明细主表bj标记3.4.2.1.3 废旧物资/粮食等收购（41）主表：名称说明fkr付款人scr司秤人明细：不同的票种不同的行数：80141、80541：3行80241、80641：4行80341、70741：15行80441、80841：5行名称对应字段继承明细主表sf水分dengj等级mz毛重bz备注3.4.2.1.4 废旧物资/粮食等销售（42）主表：名称说明jsfs结算方式scr司秤人xhdd销货地点cydw承运单位明细：不同的票种不同的行数：80141、80541：3行80241、80641：5行80341、70741：15行80441、80841：5行名称对应字段继承明细主表3.4.2.1.5 水电气（51）主表：名称说明zhh总户号dhh段户号cbr抄表人jfy缴费月bz备注明细：不同的票种不同的行数：80151、80551：3行名称对应字段继承明细主表byss本月示数syss上月示数3.4.2.1.6 其他代理服务（国际货代船代）（61）主表：名称说明hb航班qyd起运地mdd目的地dgrq到港日期zhg装货港xhg卸货港fz附注bz备注wbdxje外币大写金额wbJe外币金额biZhong币种bzMc币种名称huiLv汇率hlSz汇率数值pjrX牌价日pjr牌价日rmbjeX人民币小写fhr复核人明细：不同的票种不同的行数：80461、80861：10行名称对应字段继承明细主表tdh提单号bz备注3.4.2.1.7 其他代理服务（报关代理）（62）主表：名称说明wtsh委托书号bz备注tgfjexj通关费金额小计ddfjexj代垫费金额小计明细：不同的票种不同的行数：80462、80862：10行名称对应字段继承明细主表tgxm通关项目tgje通关金额ddfxm代垫项目ddfje代垫金额fz附注bz备注3.4.2.1.8 航空客运（代售服务）（63）主表：名称说明hc航程pzhm票证号码jlbh记录编号fkfs付款方式fhr复核人明细：不同的票种不同的行数：80163、80563：3行名称对应字段继承明细主表bz备注3.4.2.1.9 交通运输（64）主表：名称说明bz备注fhr复核人明细：不同的票种不同的行数：80164、80564：4行80264、80664：8行80364、80764：15行80464、80864：10行名称对应字段继承明细主表kce折扣额fz附注bz备注3.4.2.1.10 其他服业（91）主表：名称说明fhr复核人bz备注明细：不同的票种不同的行数：801191、80591：4行802191、80691：8行803191、80791：15行804191、80891：10行名称对应字段继承明细主表kce折扣额fz附注bz备注3.4.2.2 明细说明（卷式票）发票明细内容数据结构描述：明细主表名称对应字段数据类型为主键不能为空品名pmvarchar(16)FALSEFALSE规格型号ggvarchar(16)FALSEFALSE计量单位jldwvarchar(16)FALSEFALSE数量slvarchar(16)FALSEFALSE金额jevarchar(16)FALSEFALSE单价djvarchar(16)FALSEFALSE以下各发票代码中的明细都继承此表。例如：发票代码 810 发票的XML内容格式是：<?xml version="1.0" encoding="GBK" ?><park><param><version>客户端版本号</version></param><invoice><item><id.fpDm>发票代码</id.fpDm><id.fpqh>发票起号</id.fpqh><fpzh>发票止号</fpzh>略过其他节点<detail> <record><dj>单价</dj><gg>规格</gg><je>金额</je><jldw>单位</jldw><pm>品名</pm><sl>数量</sl></record>.record可以有多个</detail><jqbm>机器编码</jqbm><invoice></ park>主表：名称说明jqbm机器编码明细：810：7行名称对应字段继承明细主表3.4.3 返回报文上传发票返回<?xml version="1.0" encoding="GBK"?><business><group><fpzlDm>发票种类代码</fpzlDm><fpDm>发票代码</fpDm><fphm>发票号码</fphm><sbbz>申报标志 1成功；2失败</sbbz><!CDATA预留接口，准备返回二维条形码及防伪码，格式待定></group><group> 多条发票返回记录</group></business>3.5 更新减免品目3.5.1 功能描述 根据企业信息获取需要减免品目内容。3.5.2 提交报文发送时遵从2.3.1的结构请求类型(type)为updateJmpm,依次写入相关参数(param)。3.5.3 返回报文返回的xml会写入CDATA中，A_2011_137，财税2011137号免征蔬菜 返回Xml见附件A_2011_137.xml3.6 网络开票机升级3.6.1 功能描述用于提供网络开票机的升级文件。3.6.2 提交报文发送时遵从2.3.1的结构请求类型(type)为updateSkj