Appearance
📋 API 接口规范文档简化版
1. 文档概述
本接口规范用于指导外部合作商与我方系统的对接,统一接口传输格式、编码、参数及安全性要求。 包含:
- 通用规范:所有接口的公共部分;
- 业务规范:根据实际业务的具体字段定义。
🔸 特别说明:请求报文需使用UTF-8编码。若包含特殊字符,请合作企业在传输前自行进行转义处理。
2. 请求URL
联系负责人
3. 请求方式
POST
Content-Type: application/x-www-form-urlencoded
4. 请求公共参数
参数名 | 类型 | 长度 | 必填 | 说明 |
---|---|---|---|---|
appid | String | 20 | 是 | 授权应用标识(由服务商提供)。不同企业对应不同 appid 。需企业提供集团税号、集团名称。 |
serviceid | String | 20 | 是 | 接口编号 |
jtnsrsbh | String | 20 | 是 | 集团纳税人识别号 |
nsrsbh | String | 20 | 是 | 纳税人识别号(企业税号) |
content | String | -- | 是 | 业务报文(Base64编码后的原始业务报文) |
signature | String | 50 | 是 | 签名串,生成方式见下说明 |
signType | String | 1 | 否 | 签名方式(0-HmacSHA256,1-MD5,默认0) |
签名计算方式(signature生成方法):
signType=0(默认,推荐): 拼接格式如下:
appid={appid}&content={content}&jtnsrsbh={jtnsrsbh}&nsrsbh={nsrsbh}&serviceid={serviceid}
用
appsecret
进行HmacSHA256加密,再进行Base64编码。signType=1: 拼接格式如下(注意无“&”符号,仅字符串拼接):
appid + appsecret + content + jtnsrsbh + nsrsbh + serviceid
使用MD5加密,最后转为大写字母。
5. 返回公共参数
参数名 | 类型 | 长度 | 必填 | 说明 |
---|---|---|---|---|
uuid | String | 32 | 是 | 交易流水号 |
code | String | 10 | 是 | 处理代码(详见接口响应Code字典表) |
msg | String | 200 | 是 | 返回信息说明 |
content | String | -- | 是 | Base64编码的业务报文 |
6. 其他说明
- 请求及返回均为Base64编码业务报文;
- UTF-8编码;
- 所有字段均为字符串类型;
- 对于有特殊字符字段需由客户端提前进行转义;
- 业务响应详情需参考《接口响应Code字典表》。
📌 典型请求/响应示例:
请求参数示例:
appid=123456
&serviceid=INV001
&jtnsrsbh=91320114MA1XXXXXX
&nsrsbh=91320114MA1YYYYYY
&content=VGhpcyBpcyBhIHRlc3QgY29udGVudA==
&signature=abcdefg123456
&signType=0
返回参数示例:
json
{
"uuid": "2024060100012345",
"code": "0000",
"msg": "处理成功",
"content": "Q29udGVudCBhZnRlciBwcm9jZXNzaW5n"
}