自然人登录服务 MCP 文档

文档信息

项目	说明
文档版本	v1.1.0
最后更新	2025-12-05
文档状态	正式版
服务名称	自然人登录服务
服务标识	MCP-Server

1. 服务概述

1.1 服务简介

自然人登录MCP服务是基于 MCP（Model Context Protocol）协议的自然人身份认证服务，提供完整的自然人APP登录流程，支持两步验证登录（自动登录 + 短信验证码），自动处理登录状态判断和流程切换。

1.2 核心功能

功能模块	说明	新增特性
自然人APP登录	支持两步验证登录，自动判断登录状态	自动认证，智能流程切换
短信验证码登录	上传短信验证码完成登录验证	自动状态检测，缓存管理
企业列表查询	查询自然人关联的企业列表信息	自动认证，企业信息完整展示
订购产品	产品订购是客户对接税号维度产品的起点	自动认证，企业信息完整展示
通用账号创建/修改	该接口用于税局已注册的登录账号信息在平台侧进行创建维护和修改	自动认证
校验税务APP是否能快速登录	校验税务APP账密登录快速登录	自动认证

1.3 调用方式

两步验证登录：第一步尝试自动登录，如需要验证码则发送短信，第二步完成验证

自动认证：内置OAuth2认证管理，自动处理令牌刷新和缓存

安全加密：支持明文密码自动RSA加密，保护敏感信息安全

2. 快速开始

2.1 前置条件

使用本服务需要准备：

client_appkey（客户端应用密钥）

client_secret（客户端密钥）

自然人账号信息（用户名、密码）

地区编码（如上海地区：3100）

2.2 基本调用示例

2.3 自动认证示例

3. 接口说明

3.1 MCP工具列表

为便于外部调用，接口按类别列出（登录认证、企业查询、缓存管理），请参见下方各表格。

自然人登录工具

工具名称	功能说明	对应原API
`natural_person_login_step1`	自然人APP登录第一步：尝试自动登录或获取验证码	内部封装（自动认证）
`natural_person_login_step2`	自然人APP登录第二步：使用短信验证码完成登录	内部封装（自动认证）
`query_natural_enterprise_list`	查询自然人关联的企业列表	内部封装（自动认证）
`order_products_auto`	产品订购服务	内部封装（自动认证）
`creation_modification_accounts`	通用账号创建/修改服务	内部封装（自动认证）
`verify_tax_app_quick_login`	校验税务APP是否能快速登录服务	内部封装（自动认证）
`clear_cache`	清除登录缓存	内部封装

3.2 自然人APP登录第一步

工具名称: natural_person_login_step1

功能说明: 尝试使用提供的用户名和密码进行自动登录。如果cookie未过期，会直接返回登录成功的结果；如果cookie已过期，会发送短信验证码并返回taskId，用于第二步验证。

必填参数:

area_code: 地区编码（必填），例如上海地区为 "3100"

gryhm: 个人用户名/用户账号（必填），通常是手机号或用户ID，例如："156*******"

gryhmm: 个人用户密码（必填），可以是明文密码或已加密的密码。如果是明文密码，MCP层会自动使用RSA加密

可选参数:

sjhm: 手机号码（可选），用于接收验证码或通知

client_appkey: 客户端应用密钥（可选，默认从配置获取），例如: "100******"

client_secret: 客户端密钥（可选，默认从配置获取），用于OAuth2认证

返回示例:

{
  "code": "2000",
  "success": true,
  "message": "登录成功",
  "data": {
    "tpass": {
      "cookie": "登录cookie字符串"
    }
  },
  "login_status": "success",
  "next_step": "登录完成，无需第二步验证"
}

{
  "code": "2000",
  "success": true,
  "message": "登录需要短信验证码，验证码已发送到 132****5344",
  "data": {
    "taskId": "1864275***********",
    "mobile": "132********",
    "msg": "验证码发送成功"
  },
  "login_status": "sms_required",
  "next_step": "请使用 natural_person_login_step2 工具，传入收到的短信验证码和返回的taskId"
}

3.3 自然人APP登录第二步

工具名称: natural_person_login_step2

功能说明: 在第一步登录返回需要短信验证码的情况下，使用用户收到的短信验证码和返回的taskId完成登录流程。

必填参数:

task_id: 第一步登录返回的任务ID（必填）

sms_code: 用户收到的短信验证码（必填），通常为6位数字

可选参数:

client_appkey: 客户端应用密钥（可选，默认从配置获取）

client_secret: 客户端密钥（可选，默认从配置获取）

返回示例:

{
  "code": "2000",
  "success": true,
  "message": "登录成功",
  "data": {
    "tpass": {
      "cookie": "完整的登录cookie",
      "localStorage": {
        "naturepublicKey": "公钥信息",
        "clientId": "客户端ID",
        "token": "访问令牌"
      }
    }
  },
  "reqId": "请求ID",
  "login_completed": true
}

3.4 查询自然人企业列表

工具名称: query_natural_enterprise_list

功能说明: 根据提供的个人用户名和密码，查询该自然人关联的所有企业信息，包括纳税人识别号、企业名称等详细信息。

必填参数:

gryhm: 个人用户名/用户账号（必填），通常是手机号或用户ID，例如："1565*******"

gryhmm: 个人用户密码（必填），可以是明文密码或已加密的密码。如果是明文密码，MCP层会自动使用RSA加密

areaCode: 地区编码（必填），例如上海地区为 "3100"

可选参数:

sjhm: 手机号码（可选），用于接收验证码或通知

client_appkey: 客户端应用密钥（可选，默认从配置获取），例如: "100******"

client_secret: 客户端密钥（可选，默认从配置获取），用于OAuth2认证

返回示例:

{
  "code": "2000",
  "success": true,
  "message": "查询成功",
  "data": {
    "total": 2,
    "details": [
      {
        "nsrsbh": "913**********",
        "name": "测试信息技术有限公司",
        "areaCode": "3100"
      },
      {
        "nsrsbh": "9131***********",
        "name": "上海测试科技有限公司",
        "areaCode": "3100"
      }
    ]
  }
}

3.5 产品订购服务

工具名称: order_products_auto

功能说明: 产品订购是客户对接税号维度产品的起点，对于首次订购产品的企业，该接口还会进行企业创建。该接口返回唯一标识aggOrgId，此aggOrgId作为双方平台企业关联的唯一标识，在之后的接口中都要用到，所以应该保存起来。

必填参数:

nsrsbh: 税号（必填）

aggOrgName: 企业名称

db: 地区编码（必填）具体参看地区代码

productCodeList: 具体参考产品码列表(英文逗号分隔)产品码

可选参数:

client_appkey: 客户端应用密钥（可选，默认从配置获取），例如: "100******"

client_secret: 客户端密钥（可选，默认从配置获取），用于OAuth2认证

返回示例:

{
    "reqId": "c835d3478de34f17b479e269fe96c826",
    "code": "SUCCESS",
    "success": true,
    "message": "",
    "data": {
        "aggOrgId": 5107*******5344,
        "purchaseDetailList": [
            {
                "productCode": "0002",
                "success": true,
                "message": "订购成功"
            },
            {
                "productCode": "0003",
                "success": false,
                "message": "订购失败"
            },
            {
                "productCode": "0020",
                "success": true,
                "message": "订购成功(已订购)"
            }
        ]
    }
}

3.6 产品订购服务

工具名称: creation_modification_accounts

功能说明: 该接口用于税局已注册的登录账号信息在平台侧进行创建维护和修改。
1.适用于不需要使用多账号的场景, 多账号典型场景例如“多开票员”, 以及同一个用户账号多身份类型, 既有“开票员”又有“办税员”两个角色, 其中办税员身份可以做申报、发票勾选认证等, 开票员只可做开票业务;
2.如果您的应用场景明确有多种角色, 或者一个人有多个手机号码，请使用托管账号创建进行创建;

必填参数:

aggOrgId: 企业id

dlfs: 登录方式

枚举值:

9 企业业务登录需使用办税小号

14 企业业务登录自传验证码

15 代理业务登录办税小号或自传验证码

gryhm: 个人用户名 dlfs=9时需传办税小号；dlfs=14或15时，可为身份证号/手机号码/用户名，建议统一用手机号码；

gryhmm: 个人用户密码传入明文密码,自动进行RSA加密加密说明

sflx: 身份类型

sjhm: 手机号码 dlfs=9时需传办税小号

可选参数:

proxyNsrsbh: 代理机构税号代理登录 dlfs=15时,必填

client_appkey: 客户端应用密钥（可选，默认从配置获取），例如: "100******"

client_secret: 客户端密钥（可选，默认从配置获取），用于OAuth2认证

返回示例:

{
    "code": "2000",
    "data": {
        "dlmm": "+mjI3liekvY=",
        "sflx": "KPY",
        "dq": "11",
        "accountId": 50432********992,
        "gryhm": "13*********52",
        "nsrsbh": "911101*************XXU",
        "createTime": "2023-12-19 14:24:24",
        "gryhmm": "G1I7f*************Vw==",
        "dlzh": "dl******04",
        "appKey": 100*******9,
        "dlfs": 9,
        "aggOrgId": 7583**************015,
        "state": 1
    },
    "success": true,
    "message": "",
    "reqId": "1f4bf3651c734b94b08daaed42408ef0"
}

3.7 校验税务APP是否能快速登录

工具名称: verify_tax_app_quick_login

功能说明: 校验税务APP账密登录快速登录

必填参数:

aggOrgId: 企业id

可选参数:

accountId: 多账户id

client_appkey: 客户端应用密钥（可选，默认从配置获取），例如: "100******"

client_secret: 客户端密钥（可选，默认从配置获取），用于OAuth2认证

返回示例:

{
    "code": "2000",
    "data": true,
    "success": true,
    "message": "可以快速登录",
    "reqId": "b026400e32f54ed7a5846f42b3c4ddd0"
}

3.8 清除登录缓存

工具名称: clear_cache

功能说明: 清除登录过程中的缓存数据，包括OAuth2认证令牌缓存和API客户端连接缓存。通常在需要强制刷新认证状态或遇到认证相关的异常时使用。

参数: 无

返回示例:

{
  "code": "2000",
  "success": true,
  "message": "登录缓存清除成功",
  "data": null
}

3.6 错误码说明

错误码	说明	解决方案
`2000`	成功	操作成功完成
`2001`	查询成功（特殊返回码）	业务逻辑成功，继续处理
`AUTH_ERROR`	认证失败	检查client_appkey和client_secret是否正确
`PARAMETER_ERROR`	参数错误	检查必填参数是否完整且格式正确
`ENCRYPT_ERROR`	加密错误	检查密码格式或加密配置
`NETWORK_ERROR`	网络错误	检查网络连接和服务器状态
`DATA_ERROR`	数据错误	检查输入数据的格式和有效性
`BUSINESS_ERROR`	业务错误	检查业务逻辑和参数是否符合要求
`SERVICE_ERROR`	服务错误	联系技术支持或重试操作

3.7 使用场景

3.7.1 完整登录流程

3.7.2 企业信息查询

3.7.3 缓存管理

3.8 最佳实践

密码安全: 建议使用明文密码，让MCP层自动进行RSA加密

错误处理: 检查每个步骤的返回状态，特别是login_status字段

缓存管理: 定期清除缓存以避免认证状态异常

参数验证: 确保地区编码、用户名等必填参数格式正确

异常重试: 网络错误时可以进行适当重试

3.9 注意事项

两步验证: 必须按照第一步、第二步的顺序进行登录

验证码有效期: 短信验证码通常有效期较短（5-10分钟）

地区编码: 不同地区的编码不同，请确认正确的地区码

缓存管理: 建议在遇到认证异常时清除缓存

并发限制: 避免同时进行多个登录请求

4. 技术支持

如有技术问题，请联系：

技术支持邮箱：xueds@qixiangyun.com

文档更新日期：2025-12-05

服务版本：v1.1.0

统一登录服务

自然人登录服务 MCP 文档

文档信息

目录

1. 服务概述

1.1 服务简介

1.2 核心功能

1.3 调用方式

2. 快速开始

2.1 前置条件

2.2 基本调用示例

2.3 自动认证示例

3. 接口说明

3.1 MCP工具列表

自然人登录工具

3.2 自然人APP登录第一步

3.3 自然人APP登录第二步

3.4 查询自然人企业列表

3.5 产品订购服务

3.6 产品订购服务

3.7 校验税务APP是否能快速登录

3.8 清除登录缓存

3.6 错误码说明

3.7 使用场景

3.7.1 完整登录流程

3.7.2 企业信息查询

3.7.3 缓存管理

3.8 最佳实践

3.9 注意事项

4. 技术支持

统一登录服务

自然人登录服务 MCP 文档#

文档信息#

目录#

1. 服务概述#

1.1 服务简介#

1.2 核心功能#

1.3 调用方式#

2. 快速开始#

2.1 前置条件#

2.2 基本调用示例#

2.3 自动认证示例#

3. 接口说明#

3.1 MCP工具列表#

自然人登录工具#

3.2 自然人APP登录第一步#

3.3 自然人APP登录第二步#

3.4 查询自然人企业列表#

3.5 产品订购服务#

3.6 产品订购服务#

3.7 校验税务APP是否能快速登录#

3.8 清除登录缓存#

3.6 错误码说明#

3.7 使用场景#

3.7.1 完整登录流程#

3.7.2 企业信息查询#

3.7.3 缓存管理#

3.8 最佳实践#

3.9 注意事项#

4. 技术支持#

自然人登录服务 MCP 文档

文档信息

目录

1. 服务概述

1.1 服务简介

1.2 核心功能

1.3 调用方式

2. 快速开始

2.1 前置条件

2.2 基本调用示例

2.3 自动认证示例

3. 接口说明

3.1 MCP工具列表

自然人登录工具

3.2 自然人APP登录第一步

3.3 自然人APP登录第二步

3.4 查询自然人企业列表

3.5 产品订购服务

3.6 产品订购服务

3.7 校验税务APP是否能快速登录

3.8 清除登录缓存

3.6 错误码说明

3.7 使用场景

3.7.1 完整登录流程

3.7.2 企业信息查询

3.7.3 缓存管理

3.8 最佳实践

3.9 注意事项

4. 技术支持