开放平台

1. 接口说明

本接口适用于开通自然人申报系统账号的纳税人完成自然人个税申报相关服务。

1.1 请求参数说明

1.1.1 请求URI、协议、方法

接口请求协议：接口使用HTTPS协议进行通信。
接口请求方法：通过POST的方式发送报文。
接口请求URI：/personal/api/v1/{serviceId} 备注：{serviceId} 具体参见各个接口说明。

POST: {
  "Accept": "application/json;charset=UTF-8",
  "appid": "UagO1xS1VX8EMX7W1",
  "Content-Length": "152",
  "Content-Type": "application/json;charset=UTF-8"
}

appid 在每个接口的header中必须添加该参数。

1.1.3 请求接口Body参数说明

请求报文明文格式如下：

json

{
  "nsrsbh": "纳税人识别号",
  "appid": "APPID，从服务商获取",
  "input": {}
}

参数	说明
appid	通过服务商获取的授权应用APPID，每个对接方唯一分配一个。
nsrsbh	一个APPID可以对应授权多个纳税人识别号，需要联系服务商关联

1.2 接口加密方式

报文通信采用AES加密，密钥由服务商提供，分为公钥和私钥。

公钥：加密整个报文
私钥：对返回参数 data 关键信息进行加解密

加密字节流需进行 Base64 编码并再次进行 URL 编码。

服务商分配的密钥请注意妥善保管，如有遗失、泄露请及时联系服务商更换。

加密示例

公钥：123456789
私钥：987654321

请求明文：

json

{
  "appid": "UagO1xS1VX8EMX7W1",
  "input": {
    "appnsrsbh": "1232314123,412341541345,12345151235",
    "dqdm": "141"
  }
}

加密后结果（Base64 + URL编码）：

jqZ%2FAqIjbvUU9EKw3hxS33Sjh05xmPbGTEFfntQefE3%2FS4%2FqfSZJsVYGkEfTQXKsVpDl%2FU6RullnWAwuwlpyPiAJZ89ct25frs%2FAGq4KXfoXaiHgguGFJhxhD4PjcoKfJ9m7t6Vpzah2dFjVntnXoA%3D%3D

接收到响应报文后，关键字段 data 需使用私钥进行解密：

json

{
  "appid": "UagO1xS1VX8EMX7W1",
  "code": "00000",
  "data": "dpkYgUpMwp0lFyG6dHpaUJ0Uw9Nh+YXuiYZiKhDIJ4eahhb1blpJACOYKEqsHU+",
  "msg": "成功",
  "nsrsbh": "15151666222332",
  "serviceid": "HQWQSBSJ",
  "sid": "2132165465"
}

解密 data 后结果：

json

{
  "skssqq": "2019-01",
  "skssqz": "2019-03"
}

后续参数说明以明文方式提供，但提交和接收报文必须使用上述加密解密流程，否则将通信失败。

1.2.1 完整请求响应示例

以 ADDAPP 批量授权接口为例：

请求明文：

json

{
  "appid": "UagO1xS1VX8EMX7W1",
  "input": {
    "appnsrsbh": "1232314123,412341541345,12345151235",
    "dqdm": "141"
  }
}

请求头：

POST: application/json
Header: {
  "Accept": "application/json;charset=UTF-8",
  "appid": "UagO1xS1VX8EMX7W1",
  "Content-Length": "166",
  "Content-Type": "application/json;charset=UTF-8"
}

请求体：

jqZ%2FAqIjbvUU9EKw3hxS33Sjh05xmPbGTEFfntQefE3%2FS4%2FqfSZJsVYGkEfTQXKsVpDl%2FU6RullnWAwuwlpyPiAJZ89ct25frs%2FAGq4KXfoXaiHgguGFJhxhD4PjcoKfJ9m7t6Vpzah2dFjVntnXoA%3D%3D

响应体：

json

{
  "code": "00000",
  "msg": "成功",
  "data": "B0/LlTFIJRca9fDSW2fm5w==",
  "serviceid": "ADDAPP",
  "nsrsbh": "",
  "appid": "UagO1xS1VX8EMX7W",
  "sid": "1892841520216276992"
}

解密后 data：

json

null

1.3 注意

服务更新时间一般安排在 21:00-21:30。
尽量避免在此时间段内跑任务，尤其是 21:00-21:05，防止请求中断造成异常。

1.4 企业常规申报流程

获取登录授权
人员信息报送（首次或变动）
获取综合所得申报累计数据
获取专项扣除信息
提交综合所得申报
查询待缴款信息
三方协议下载（首次）
三方协议扣款
开具完税证明

2. 批量授权（serviceid: `ADDAPP`）

某个税号首次使用时需授权。

请求明文：

json

{
  "nsrsbh": "",
  "appid": "APPID，从服务商获取",
  "input": {
    "appnsrsbh": "1232314123,412341541345,12345151235",
    "dqdm": "141"
  }
}

字段说明：

字段名称	字段含义	必填	说明
appnsrsbh	需授权的纳税人识别号	是	多个以逗号分隔
dqdm	地区代码	是	当前授权税号对应地区代码，详见附录3

json

{
  "code": "00000",
  "data": {},
  "msg": "成功",
  "serviceid": "ADDAPP"
}

3. 登录前置接口

3.1 获取企业基本信息（serviceid: `HQQYJBXX`）

授权后调用。获取失败将导致后续接口无法调用。

请求：

json

{
  "nsrsbh": "纳税人识别号",
  "appid": "APPID，从服务商获取",
  "input": {
    "dqbm": "13707",
    "djxh": "",
    "swjgdm": ""
  }
}

字段说明：

字段名称	字段含义	必填	说明
dqbm	地区编码	否	获取企业指定地区信息时需要
swjgdm	税务机关代码	否	获取扩展信息时传入
djxh	登记序号	否	获取扩展信息时传入

注意：如企业存在跨地区经营，会返回多个税务机关信息，默认使用第一个，如需切换，需调用“切换所属地区”接口。

响应：结构较长，保持原样返回。

3.2 税费种信息查询（serviceid: `SFZXXCX`）

请求：

json

{
  "nsrsbh": "915100000000000000",
  "appid": "APPID",
  "input": {
    "djxh": "10114501000000000002",
    "swjgdm": "14501040500",
    "dqbm": "145"
  }
}

字段说明：

字段名称	字段含义	必填	说明
djxh	登记序号	是	企业登记序号，从基本信息获取
swjgdm	税务机关代码	是	从基本信息中获取
dqbm	地区编码	是	当前企业所属地区编码

json

{
  "code": "00000",
  "msg": "成功",
  "data": [
    {
      "zsxmDm": "10101",
      "zsxmMc": "增值税",
      "zspmDm": "1010101",
      "zspmMc": "一般纳税人增值税",
      "swjgDm": "14501040500",
      "skssqq": "2023-01",
      "skssqz": "2023-03",
      "zsfsDm": "01",
      "zsfsMc": "查账征收"
    },
    {
      "zsxmDm": "10102",
      "zsxmMc": "企业所得税",
      "zspmDm": "1010201",
      "zspmMc": "季度预缴企业所得税",
      "swjgDm": "14501040500",
      "skssqq": "2023-01",
      "skssqz": "2023-03",
      "zsfsDm": "01",
      "zsfsMc": "查账征收"
    }
  ],
  "serviceid": "SFZXXCX",
  "nsrsbh": "915100000000000000",
  "appid": "APPID",
  "sid": "1892841520216276992"
}

data 字段说明：

字段名称	含义	说明
zsxmDm	税种代码	如：10101 表示增值税
zsxmMc	税种名称	如：增值税
zspmDm	税（费）种细项代码	如：1010101
zspmMc	税（费）种细项名称	如：一般纳税人增值税
swjgDm	税务机关代码	税费种认定的主管税务机关代码
skssqq	税款所属期起	格式：yyyy-MM
skssqz	税款所属期止	格式：yyyy-MM
zsfsDm	征收方式代码	如：01
zsfsMc	征收方式名称	如：查账征收

3.3 切换所属地区（serviceid: `QHSSDQ`）

请求：

json

{
  "nsrsbh": "915100000000000000",
  "appid": "APPID",
  "input": {
    "dqbm": "146"
  }
}

字段说明：

字段名称	字段含义	必填	说明
dqbm	地区编码	是	新切换的地区编码

json

{
  "code": "00000",
  "msg": "切换成功",
  "data": null,
  "serviceid": "QHSSDQ",
  "nsrsbh": "915100000000000000",
  "appid": "APPID",
  "sid": "1892841520216278000"
}

说明：

调用本接口用于在系统中切换当前纳税人操作的所属地区（如跨区申报或管理）。
切换后，该纳税人的相关查询及申报操作将基于新的地区编码进行。
dqbm 地区编码需为有效地区代码，通常为 3 位数字，如“146”表示某市辖区。

3.4 企业授权批量提交（serviceid: `QYBATCHSQ`）

请求：

json

{
  "nsrsbh": "915100000000000000",
  "appid": "APPID",
  "input": {
    "data": [
      {
        "zjhm": "510xxxxxxxxxxxxx10",
        "xm": "张三",
        "sjlx": "0",
        "lxdh": "13800000000",
        "rzfs": "1"
      },
      {
        "zjhm": "510xxxxxxxxxxxxx20",
        "xm": "李四",
        "sjlx": "0",
        "lxdh": "13900000000",
        "rzfs": "2"
      }
    ]
  }
}

字段说明：

字段名称	字段含义	必填	说明
zjhm	证件号码	是	自然人身份证号码
xm	姓名	是	自然人姓名
sjlx	手机类型	是	0：大陆手机号；1：非大陆手机号
lxdh	联系电话	是	手机号码
rzfs	认证方式	是	1：短信认证；2：扫码认证

json

{
  "code": "00000",
  "msg": "提交成功",
  "data": [
    {
      "zjhm": "510xxxxxxxxxxxxx10",
      "xm": "张三",
      "status": "T1",
      "message": "待认证"
    },
    {
      "zjhm": "510xxxxxxxxxxxxx20",
      "xm": "李四",
      "status": "T1",
      "message": "待认证"
    }
  ],
  "serviceid": "QYBATCHSQ",
  "nsrsbh": "915100000000000000",
  "appid": "APPID",
  "sid": "1892841520216279000"
}

data 字段说明：

字段名称	字段含义	说明
zjhm	证件号码	提交的证件号码
xm	姓名	提交的姓名
status	状态码	如 T1 表示待认证
message	状态说明	对应状态的中文说明

3.5 查询授权结果（serviceid: `SQJGQUERY`）

请求：

json

{
  "nsrsbh": "915100000000000000",
  "appid": "APPID",
  "input": {
    "zjhmList": [
      "510xxxxxxxxxxxxx10",
      "510xxxxxxxxxxxxx20"
    ]
  }
}

字段说明：

字段名称	字段含义	必填	说明
zjhmList	证件号码列表	是	待查询的自然人证件号码数组

json

{
  "code": "00000",
  "msg": "查询成功",
  "data": [
    {
      "zjhm": "510xxxxxxxxxxxxx10",
      "xm": "张三",
      "status": "T2",
      "message": "认证成功"
    },
    {
      "zjhm": "510xxxxxxxxxxxxx20",
      "xm": "李四",
      "status": "T1",
      "message": "待认证"
    }
  ],
  "serviceid": "SQJGQUERY",
  "nsrsbh": "915100000000000000",
  "appid": "APPID",
  "sid": "1892841520216280000"
}

data 字段说明：

字段名称	字段含义	说明
zjhm	证件号码	被查询自然人的证件号码
xm	姓名	被查询自然人的姓名
status	状态码	如 T1 表示待认证，T2 表示已认证
message	状态说明	当前认证状态说明

1. 接口说明

1.1 请求参数说明

1.1.1 请求URI、协议、方法

1.1.2 请求接口Header参数说明

1.1.3 请求接口Body参数说明

1.2 接口加密方式

加密示例

1.2.1 完整请求响应示例

1.3 注意

1.4 企业常规申报流程

2. 批量授权（serviceid: `ADDAPP`）

请求明文：

字段说明：

返回：

3. 登录前置接口

3.1 获取企业基本信息（serviceid: `HQQYJBXX`）

请求：

字段说明：

响应：结构较长，保持原样返回。

3.2 税费种信息查询（serviceid: `SFZXXCX`）

请求：

字段说明：

返回：

data 字段说明：

3.3 切换所属地区（serviceid: `QHSSDQ`）

请求：

字段说明：

返回：

说明：

3.4 企业授权批量提交（serviceid: `QYBATCHSQ`）

请求：

字段说明：

返回：

data 字段说明：

3.5 查询授权结果（serviceid: `SQJGQUERY`）

请求：

字段说明：

返回：

data 字段说明：

1. 接口说明 ​

1.1 请求参数说明 ​

1.1.1 请求URI、协议、方法 ​

1.1.2 请求接口Header参数说明 ​

1.1.3 请求接口Body参数说明 ​

1.2 接口加密方式 ​

加密示例 ​

1.2.1 完整请求响应示例 ​

1.3 注意 ​

1.4 企业常规申报流程 ​

2. 批量授权（serviceid: ADDAPP） ​

请求明文： ​

字段说明： ​

返回： ​

3. 登录前置接口 ​

3.1 获取企业基本信息（serviceid: HQQYJBXX） ​

请求： ​

字段说明： ​

响应：结构较长，保持原样返回。 ​

3.2 税费种信息查询（serviceid: SFZXXCX） ​

请求： ​

字段说明： ​

返回： ​

data 字段说明： ​

3.3 切换所属地区（serviceid: QHSSDQ） ​

请求： ​

字段说明： ​

返回： ​

说明： ​

3.4 企业授权批量提交（serviceid: QYBATCHSQ） ​

请求： ​

字段说明： ​

返回： ​

data 字段说明： ​

3.5 查询授权结果（serviceid: SQJGQUERY） ​

请求： ​

字段说明： ​

返回： ​

data 字段说明： ​

1. 接口说明

1.1 请求参数说明

1.1.1 请求URI、协议、方法

1.1.2 请求接口Header参数说明

1.1.3 请求接口Body参数说明

1.2 接口加密方式

加密示例

1.2.1 完整请求响应示例

1.3 注意

1.4 企业常规申报流程

2. 批量授权（serviceid: `ADDAPP`）

请求明文：

字段说明：

返回：

3. 登录前置接口

3.1 获取企业基本信息（serviceid: `HQQYJBXX`）

请求：

字段说明：

响应：结构较长，保持原样返回。

3.2 税费种信息查询（serviceid: `SFZXXCX`）

请求：

字段说明：

返回：

data 字段说明：

3.3 切换所属地区（serviceid: `QHSSDQ`）

请求：

字段说明：

返回：

说明：

3.4 企业授权批量提交（serviceid: `QYBATCHSQ`）

请求：

字段说明：

返回：

data 字段说明：

3.5 查询授权结果（serviceid: `SQJGQUERY`）

请求：

字段说明：

返回：

data 字段说明：