金财数电发票开具

概述

本能力负责单一销方企业的蓝字数电专用发票与普通发票开具，覆盖出票、版式文件下载和开具结果查询。采购销售单据、电商平台对接、第三方财务软件同步、支付结算判定和号码托管均不在范围内。

入口与安全

• 先运行 python3 scripts/cli.py check-config；缺失时运行 python3 scripts/cli.py configure，在 127 配置页的“销项：数电开具”Tab 中保存独立的 JCSK_OUTPUT_API_KEY。不要让用户在聊天中粘贴 App Secret。
• 企业名称/税号/办税人和登录账号在独立的一次性 127.0.0.1 业务页填写。地区信息先按 GB 32100 校验 18 位统一社会信用代码，再读取第 3—8 位登记管理机关行政区划码：优先识别大连、宁波、厦门、青岛、深圳五个计划单列市，其余按省级代码映射。国家级登记机关代码、15 位旧税号和非标准税号不猜测地区；后续接口返回权威 dqbm/nsrdq 时覆盖推断值。销方地址、电话、开户行、账号不在首次登记页要求填写。
• 企业登记页支持按名称智能查询抬头 S000706：只为这一步读取独立的 JCSK_INPUT_API_KEY；输入企业名称关键词（至少 4 个字）后返回名称/税号候选下拉，必须由用户手选。登记、授权和开票仍使用 JCSK_OUTPUT_API_KEY，两套凭据不得混用。
• 本机业务页只负责三件事：AppKey 保存、企业登记、自主授权登录（含授权登录到哪家企业）。开票主体属于业务决策，由 Agent 层在同一会话里向用户确认，不要放到页面上让用户选。
• 企业资料、数电账号、密码、短信验证码和人脸认证必须在独立的一次性 127.0.0.1 业务页完成；AppKey 配置页和业务页每次仅等待 15 分钟，超时后须由发起任务的对话重新打开。页面使用随机端口和一次性 nonce，本地服务监听 /poll 状态。密码、验证码、二维码原文、rzid、token 永不落盘或输出。
• 企业初始化调用 yhdj 时固定 dlfs=3，自主授权不向接口发送 dlmm/dlsfmm；登记成功后仍需在浏览器页面完成授权。
• 二维码渲染零依赖：优先用已安装的 python-qrcode，缺失时自动走内置 scripts/qr_minimal.py（纯标准库编码器 + 纯标准库 PNG）。不再尝试 pip 自动安装（托管环境多为 PEP 668，必然失败）。渲染失败会显式报错，不会静默显示空图。
• 页面上任何按钮点击后都必须给出反馈：按钮立刻进入进行中状态（禁用并转圈），结束后弹出提示条说明成功或失败原因；页面断开或服务返回异常时给出明确的中文提示。不得清空用户已输入的密码和短信验证码，失败重试时无需重新填写。
• 44 号全电销项通道（roc-vip）的业务接口普遍“先受理后查询”：拿到 requestId 必须用 tycxjk 取回真实结果，code=0000 只代表受理成功，不代表业务成功。
• 真实业务请求必须显式 --execute。开票前展示脱敏预览并取得确认；网络中断返回“结果可能未知”，不得换新 fpqqlsh 重发。

开票口径（易错，务必遵守）

• hjje 始终填不含税合计，hjse 为税额，且必须满足 hjje + hjse = jshj。含税模式（hsbz=2）下明细 je 传含税金额，但 hjje 不能直接抄含税总额，否则局端报“明细行不含税金额累加与 hjje 不一致”。
• 税率必须匹配销方纳税人资格：小规模纳税人只接受 0.01 / 0.03，一般纳税人才能用 0.06 等。znfm 智能赋码返回的是税目法定税率，不等于本主体适用征收率，不能直接当 slv 用。
• 开给自然人（购方无税号）时传 gmfZrrbs=Y，否则票面不会归集到个人票夹；购方名称为自然人时须多于一个字符。
• prepare-invoice 与 issue-blue 必须基于同一份请求（含销方档案）计算指纹，否则本地任务档案会以“fpqqlsh 已绑定另一笔业务”拒绝提交。

推荐链路

1. check-config → configure：检查并填写销项 JCSK_OUTPUT_API_KEY。进项能力的 JCSK_INPUT_API_KEY 不得被覆盖。
2. enterprise-init --execute：127 页面填写企业名称/税号、办税人和数电账号；服务从税号推断省级 dqbm/nsrdq，真实调用 yhdj 后保存本地受限企业档案。dry-run 不落档，不能进入授权。
3. authorize --execute：同一 127 页面完成账密、短信或税务 App 扫码；收到多企业列表时必须用户选择。授权成功后调用 hqnsrjcxx 获取销方基础信息，打开“销方开票资料确认”页供用户核对/修改并保存，随后用 authorization-status --execute 低频确认授权存活。
4. prepare-invoice：校验购方、明细、金额税额。需要补全时，调用 zntt/znfm，展示候选并等待用户确认，不得静默选第一项。
5. preflight --execute：调用 kpxwjk。返回 sfsl=Y 时先运行 face-auth --execute，按 hqrlsbewm → hqrlsbjg 完成人脸认证；slzt=1 继续等，0/3 刷新二维码。人脸渠道由 rlsblx 决定：0 = 电子税务局 App / 个税 App（默认），1 = 国家网络身份认证 App，两种码格式完全不同，扫错 App 只会在手机上提示“暂不支持此二维码”，此时换渠道重新取码，不要当成接口故障。
6. 🔴 CHECKPOINT · 开票确认：展示购方、票种、价税合计、明细和 fpqqlsh；只有用户明确确认后才执行 issue-blue --execute --confirm --fpqqlsh <固定流水号>。
7. issue-blue 调用 lzfpkj。网络超时或未知结果时保留原 fpqqlsh，使用同一输入运行 recover-issue --execute --confirm（金财幂等返回原票面），不得换号；成功但地址为空时运行 fetch-files --execute，返回“已开具、版式生成中/已补偿”。

明确失败分支

• API Key 缺失/无效 → 停止联网，打开共享配置页的“销项：数电开具”Tab；保存失败不继续。
• 税号无法推断大陆省份 → 不猜测 dqbm/nsrdq，停止登记并提示使用有效的 18 位统一社会信用代码。
• 智能抬头返回“appid 不存在/请开通” → 先确认请求使用的是 JCSK_INPUT_API_KEY；输入凭据正确后仍失败，才判断为 S000706 未开通。不要把权限错误解释成没有企业。
• yhdj 失败 → 不写“已登记”，保留页面输入在当前进程并展示金财错误；修正后重新提交。
• 授权返回 SMS → 仅在 127 页面收验证码；验证码错误或超时 → 保留已填的密码和验证码，提示原因后允许重新发起，最多按上游限制重试。
• 授权返回 QR → 仅在 127 页面显示；二维码过期 → 获取新码；网络错误 → 查询 authorization-status，不盲目重复登录。
• 多企业 → 暂停等待选择；用户取消 → CANCELLED，不默认第一条。
• 人脸 slzt=0/3 → 标记二维码失效并重新获取；开票提示身份认证超时 → 回到人脸流程但复用原 fpqqlsh。
• 手机提示“暂不支持此二维码” → 认证渠道与 App 不匹配，切到另一渠道重新取码，不要反复重试同一张码。
• 返回“请使用如下税率：…” → 该主体是小规模纳税人，按提示改 slv 后重开，不要沿用智能赋码的法定税率。
• 返回“明细行不含税金额累加…与 hjje 不一致” → 按上文口径把 hjje 改成不含税合计。
• lzfpkj 超时 → 标记 unknown，以原输入和原 fpqqlsh 运行 recover-issue --execute --confirm，不生成新流水号；已成功但 PDF/OFD/XML 为空 → 依次使用 fpewmxz（450）和 qdfpwjhq（476）补偿。

不要做（黑名单）

• 不要调用采购销售单据、电商平台、第三方财务软件、支付结算判定或号码托管链路。
• 不要在聊天窗口收集或回显密码、短信验证码、二维码原文、rzid、token、签名或完整接口响应。
• 不要把账号密码写入企业档案、浏览器 localStorage、日志、测试快照或 ZIP。
• 不要在开票未知结果时更换 fpqqlsh，也不要未经确认自动提交 lzfpkj。
• 不要把多企业列表静默选第一项，不要把智能抬头/赋码候选静默选第一项。
• 不要把真实接口地址、appsecret 或测试凭据硬编码进发布包。

常用命令：check-config、configure、enterprise-init、authorize、authorization-status、preflight、face-auth、lookup-buyer、lookup-tax-code、prepare-invoice、issue-blue、recover-issue、fetch-files。fetch-files 可用 --format PDF|OFD|XML --execute 下载补偿文件；XML 返回 ZIP。详细字段和接口约束见 [references/flow-blueprint.md](references/flow-blueprint.md)、[references/yhdj.md](references/yhdj.md)、[references/lzfpkj.md](references/lzfpkj.md)、[references/self-auth.md](references/self-auth.md)、[references/api-contracts.md](references/api-contracts.md)。