MCP服务文档

文档信息

项目	说明
文档版本	v1.4.0
最后更新	2025-12-05
文档状态	正式版
服务名称	企享云统一 MCP 服务
服务标识	MCP-Server

0. 服务概览与连接地址

本服务采用统一网关架构，不同的业务能力挂载在不同的路径下。请根据您需要调用的工具，选择正确的服务地址连接。

基础 URL:

生产环境: https://mcp.qixiangyun.com

说明:

每个服务都有独立的 mount path，在该路径下提供两种传输模式（SSE 与 HTTP）。

工具（tool）按业务职责划分在不同服务中，具体参数请参考对应服务文档。

1. 服务能力总览

说明：以下表格展示“服务 → 路径 → 核心工具（示例）”。完整参数与业务规则请参考各服务的独立文档。

业务域	服务名称	Mount Path	核心工具（示例）
登录服务	自然人登录服务	`/mcp/login`	`natural_person_login_step1`, `natural_person_login_step2`, `query_natural_enterprise_list`, `query_enterprises_by_individual`, `clear_cache`
登录服务	托管登录服务	`/mcp/request_managed_login`	`send_managed_tax_app_login_sms_code_auto`, `upload_managed_tax_app_login_sms_code_auto`
登录服务	产品相关服务	`/mcp/products`	`order_products_auto`, `creation_modification_accounts`, `verify_tax_app_quick_login`
登录服务	人脸服务	`/mcp/face`	`get_face_qr_code`, `get_face_auth_result`, `get_individual_tax_face_qr_code`, `get_individual_tax_face_auth_result`
发票服务	蓝票开票服务	`/mcp/blue_invoice`	`issue_blue_invoice_auto`, `issue_agricultural_purchase_invoice_auto`, `issue_scrap_purchase_invoice_auto`
发票服务	已开发票查询服务	`/mcp/invoice_inquiry`	`query_invoice_details_auto`, `query_invoice_list_auto`
发票服务	红字开票服务	`/mcp/red_invoice`	`apply_red_information_auto`, `query_red_information_list_auto`, `issue_red_invoice_auto`, `query_red_information_details_auto`
发票服务	发票查验服务	`/mcp/invoice_verification`	`verify_invoice`, `batch_verify_invoices`, `validate_invoice_info`
发票服务	企业信息查询服务	`/mcp/enterprise_basic_information`	`query_enterprise_basic_information_auto`, `query_invoice_issuance_quota_auto`
申报服务	初始化数据模块	`/mcp/initialize_data`	`load_init_data_task`, `get_init_data`
申报服务	财务报表模块	`/mcp/financial_report`	`upload_financial_report_data`
申报服务	企业管理服务	`/mcp/enterprise_management`	`load_org_tax_info`, `query_org_info`
申报服务	任务查询模块	`/mcp/task_query`	`query_task_info`
申报服务	任务执行模块	`/mcp/task_execution`	`load_pdf_task`, `load_payment_task`, `load_wszm_task`, `load_declare_info_task`
认证服务	获取税款所属期服务	`/mcp/get_tax_payment_period`	`get_tax_payment_period_auto`, `update_tax_payment_period_auto`, `update_tax_payment_period_task_result_auto`
认证服务	进项发票采集	`/mcp/collect_input_invoice`	`request_input_invoice_collection_auto`, `get_input_invoice_data_auto`, `query_input_invoice_collection_result_auto`
认证服务	进项发票勾选服务	`/mcp/select_invoice_for_deduction`	`select_invoice_for_deduction_auto`, `query_invoice_selection_result_auto`
认证服务	发票统计确认服务	`/mcp/invoice_authentication_statistics`	`apply_invoice_authentication_statistics_auto`, `confirm_invoice_authentication_statistics_auto`, `revoke_invoice_authentication_statistics_confirmation_auto`, `query_invoice_authentication_statistics_confirmation_result_auto`

2. 路径分层与传输模式

2.1 分层结构

业务域层：登录 / 发票 / 申报 / 认证

服务层：如“自然人登录服务”“蓝票开票服务”

传输层：SSE / HTTP Streamable

工具层：动词 + 业务对象命名，常见后缀 _auto

2.2 传输模式

模式	地址规则	适用场景
SSE	`{mount_path}/sse`	长连接、需要流式/实时反馈
HTTP Streamable	`{mount_path}-http`	标准请求-响应、易接入

示例：蓝票开票服务

SSE：https://mcp.qixiangyun.com/mcp/blue_invoice/sse

HTTP：https://mcp.qixiangyun.com/mcp/blue_invoice-http

3. 鉴权方式与注入脚本

所有工具调用必须包含：

client_appkey

client_secret

建议通过注入脚本自动补齐，避免硬编码。

3.1 Python 注入脚本（推荐）

3.2 Java 注入脚本（推荐）

.env 示例（建议加入 .gitignore）

CLIENT_APPKEY=your_appkey_here
CLIENT_SECRET=your_secret_here

4. 调用方式（SSE/HTTP）

4.1 SSE 调用示例（Python）

4.2 HTTP Streamable 示例

5. 大模型调用指南

5.1 概述

通过通义千问等大语言模型，您可以用自然语言直接操作发票服务，无需编写代码。只需告诉AI助手您的需求，它就能自动调用MCP工具完成发票开具、查询、红冲等操作。

5.2 使用效果展示

5.2.1 发票开具示例

用户输入:

请为订单ORD20*************开具一张发票
购买方：北京科技有限公司
税号：9111****************
发票类型：数电普票
商品：桌面风扇，数量1，单价59.64元，税率13%

AI助手回复:

好的，我正在为您开具发票...

✅ 发票开具成功！

发票号码：2431202*********************
开票日期：2024-03-01 04:49:19
价税合计：67.39元

发票文件：
- PDF格式：https://example.com/invoice.pdf
- OFD格式：https://example.com/invoice.ofd

5.2.2 发票查询示例

用户输入:

帮我查询发票2431202403**********的详情

AI助手回复:

正在查询发票信息...

📄 发票详情

发票号码：2431202**************
发票类型：数电普票
开票日期：2024-03-01 04:49:19

销售方：测试销售公司
购买方：测试购买公司

商品明细：
1. 桌面风扇
   数量：1
   单价：59.64元
   税率：13%
   税额：7.75元
   金额：59.64元

合计金额：59.64元
合计税额：7.75元
价税合计：67.39元

5.2.3 红字发票申请示例

用户输入:

发票24312***************开错了，需要红冲，原因是开票有误

AI助手回复:

正在为您申请红字信息表...

✅ 红字信息表申请成功

红字信息UUID：8ce2e471*******************
红字确认单编号：31022924************
状态：无需确认

是否需要现在开具红字发票？

5.2.4 多轮对话示例

对话一:

用户：我想开具一张发票
AI：好的，请提供订单信息，包括订单号、购买方信息、商品明细等。

对话二:

用户：订单号ORD2***********，购买方是北京科技有限公司
AI：收到。请提供商品信息（商品名称、数量、单价、税率）。

对话三:

用户：桌面风扇，1个，59.64元，税率13%
AI：信息已收集完整，正在为您开具发票...

✅ 发票开具成功！发票号码：24318********************

对话四:

用户：刚才开的发票能帮我查一下吗？
AI：正在查询您刚才开具的发票...

📄 发票24312****************的详细信息已显示在上方。

5.3 支持的自然语言操作

操作场景	用户指令示例	AI自动执行
开具发票	"帮我开张发票"、"为订单ORD001开具发票"	调用`issue_blue_invoice`工具
查询发票	"查询发票2431...详情"、"帮我查一下刚才开的票"	调用`query_invoice_detail`工具
申请红冲	"发票开错了，需要红冲"、"申请红字信息表"	调用`apply_red_info_form`工具
开具红字发票	"开具红字发票"、"红冲刚才的发票"	调用`issue_red_invoice`工具
查询红字信息	"查询红字信息表状态"、"待确认的红字信息有哪些"	调用`query_red_info_list`工具

6. 安全说明

6.1 认证机制

所有请求需要通过 client_appkey 与 client_secret 认证。建议通过注入脚本从环境变量读取，避免硬编码。

6.2 传输安全

所有请求必须使用HTTPS协议

支持TLS 1.2及以上版本

敏感数据加密传输和存储

7. 常见问题

7.1 认证相关

Q: 为什么提示凭证缺失？
A: 请确认 CLIENT_APPKEY 与 CLIENT_SECRET 已配置在 .env 或系统环境变量中。

7.2 发票开具相关

Q: 同步调用和异步调用的区别？
A: 同步调用立即返回结果（默认40秒超时）；异步调用返回requestId，需要后续查询结果。处理时间超过40秒时会自动转为异步。

Q: 同一个订单号可以开具多次发票吗？
A: 不可以，同一订单号（ly_ddbh）只能开具一次发票。

Q: 发票开具失败如何排查？
A: 检查参数格式、必填字段、业务规则（如金额限制、特定业务参数），查看返回的错误代码和消息。

7.3 红字发票相关

Q: 红字发票开具流程？
A: 1. 申请红字信息表 → 2. 等待确认（如需确认） → 3. 开具红字发票 → 4. 查询红字发票信息

Q: 部分红冲如何操作？
A: 在申请红字信息表时，传入bfhc参数，指定部分红冲标志和红冲明细。

7.4 查询相关

Q: 查询已开发票需要哪些参数？
A: 至少需要开票日期（kprq）和发票号码（fphm），或者来源订单编号（ly_ddbh）。

Q: 如何获取发票的勾选和入账状态？
A: 在查询时传入dataScope参数，值为1（勾选状态）或2（入账状态）或3（全部）。

7.5 错误处理

常见错误代码:

代码	说明	处理建议
2000	操作成功	-
2001	请求已转为异步处理	使用requestId查询异步结果
4001	参数错误	检查请求参数
4002	必填参数缺失	补充必填参数
6001	Access Token无效	重新获取Token
6002	Access Token已过期	刷新Token
8001	发票开具失败	检查发票数据
8002	发票号码已存在	检查订单编号是否重复

技术支持

联系方式:

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

文档反馈: xueds@qixiangyun.com

在线客服: 工作日 9:30-18:00

参考资源:

企享云API文档: https://openapi.qixiangyun.com/

文档维护: 企享云技术团队
最后更新: 2025-12-05
文档状态: 正式版

MCP集成

MCP服务文档

文档信息

目录

0. 服务概览与连接地址

1. 服务能力总览

2. 路径分层与传输模式

2.1 分层结构

2.2 传输模式

3. 鉴权方式与注入脚本

3.1 Python 注入脚本（推荐）

3.2 Java 注入脚本（推荐）

4. 调用方式（SSE/HTTP）

4.1 SSE 调用示例（Python）

4.2 HTTP Streamable 示例

5. 大模型调用指南

5.1 概述

5.2 使用效果展示

5.2.1 发票开具示例

5.2.2 发票查询示例

5.2.3 红字发票申请示例

5.2.4 多轮对话示例

5.3 支持的自然语言操作

6. 安全说明

6.1 认证机制

6.2 传输安全

7. 常见问题

7.1 认证相关

7.2 发票开具相关

7.3 红字发票相关

7.4 查询相关

7.5 错误处理

技术支持

MCP集成

MCP服务文档#

文档信息#

目录#

0. 服务概览与连接地址#

1. 服务能力总览#

2. 路径分层与传输模式#

2.1 分层结构#

2.2 传输模式#

3. 鉴权方式与注入脚本#

3.1 Python 注入脚本（推荐）#

3.2 Java 注入脚本（推荐）#

4. 调用方式（SSE/HTTP）#

4.1 SSE 调用示例（Python）#

4.2 HTTP Streamable 示例#

5. 大模型调用指南#

5.1 概述#

5.2 使用效果展示#

5.2.1 发票开具示例#

5.2.2 发票查询示例#

5.2.3 红字发票申请示例#

5.2.4 多轮对话示例#

5.3 支持的自然语言操作#

6. 安全说明#

6.1 认证机制#

6.2 传输安全#

7. 常见问题#

7.1 认证相关#

7.2 发票开具相关#

7.3 红字发票相关#

7.4 查询相关#

7.5 错误处理#

技术支持#

MCP服务文档

文档信息

目录

0. 服务概览与连接地址

1. 服务能力总览

2. 路径分层与传输模式

2.1 分层结构

2.2 传输模式

3. 鉴权方式与注入脚本

3.1 Python 注入脚本（推荐）

3.2 Java 注入脚本（推荐）

4. 调用方式（SSE/HTTP）

4.1 SSE 调用示例（Python）

4.2 HTTP Streamable 示例

5. 大模型调用指南

5.1 概述

5.2 使用效果展示

5.2.1 发票开具示例

5.2.2 发票查询示例

5.2.3 红字发票申请示例

5.2.4 多轮对话示例

5.3 支持的自然语言操作

6. 安全说明

6.1 认证机制

6.2 传输安全

7. 常见问题

7.1 认证相关

7.2 发票开具相关

7.3 红字发票相关

7.4 查询相关

7.5 错误处理

技术支持