统一开放 API

统一 POST 地址已部署 · 按授权开通

查验、发票同步、连接管理及已实现的开票能力共用 HTTPS、AccessKey 请求签名和 JSON 信封。以下列出全部 32 个业务操作；扫码和短信共用创建连接地址，通过 method 区分。所有业务 JSON 调用统一为 POST，认证规则一致，参数按各接口定义传递。

统一 POST 地址已部署。请先开通企业能力及目标税号权限，再使用对应凭证调用；具体税务通道仍以验证状态及授权范围为准，不能把地址已部署理解为所有税局业务已经完成真机验证。旧版业务链路继续运行。

版本与接入顺序

  • 统一基础地址为 https://open.yifeihuilian.com/api/v2，地址形状为 /{资源}/{操作}。业务查询、创建与修改都使用 POST；资源 ID、筛选和分页条件放入 JSON 请求体，不放 URL 查询参数。
  • /api/v3/tax/* 只作为兼容地址；旧版 /api/v2/tax/*、/access/v2/invoke/* 和旧版查验入口保持各自原协议。票慧联原有调用路径不重定向、不自动切换。
  • 平台使用统一发布开关启用或关闭新版；关闭时新版返回 HTTP 503 / OPENAPI_DISABLED，旧链路继续工作。
  • 已开启新版的接入方按明确配置选择协议。认证或授权失败时不会自动回退到旧版，避免掩盖配置问题。

接入顺序：确认开通状态 → 申请凭证和税号授权 → 使用 服务端 SDK 生成签名 → 调用业务接口。所有新版调用均需企业及目标税号授权；服务端从凭证确定企业身份。签名凭证和旧版密钥相互独立。申请凭证后请先阅读 统一认证与安全。

查验中心：单张和批量

POST /api/v2/invoices/check

请求体示例

JSON
{
  "tax_no": "<已授权企业税号>",
  "invoices": [
    {
      "fphm": "<发票号码>",
      "kprq": "20261023",
      "kpje": "100.00"
    }
  ]
}

HTTP 200 响应结构示例

JSON
{
  "code": "OK",
  "message": "成功",
  "request_id": "req_example_001",
  "data": {
    "status": "COMPLETED",
    "results": [
      {
        "channel": "NATIONAL",
        "billable": true,
        "http_status": 200,
        "response": {
          "说明": "此处为查验渠道的实际业务结果，字段按渠道定义"
        }
      }
    ]
  }
}

tax_no 为已授权税号，invoices 一个元素表示单张，多个表示批量；上述发票字段均为 String。kprq 使用 YYYYMMDD（例如 20261023）；每项必填 fphm、kprq、kpje，fpdm 可选。数电发票不传代码时，号码为 20 位数字；传统发票代码为 10 或 12 位数字。kpje 按票种表示金额或右上角 6 位校验码，不是所有票种都填价税合计。可使用 Idempotency-Key 按企业隔离同一业务请求。查验结论位于 data.results，接口受理成功不等于每张发票查验一致。响应示例仅展示结构，response 中的说明占位不是实际税局字段。

建议对消耗查验次数的请求提供 Idempotency-Key（1–128 位英文字母、数字、下划线或连字符）。同企业相同键和相同业务参数返回已完成结果；换请求 ID、时间戳和随机数不改变该业务键。不同业务参数复用同一键返回 IDEMPOTENCY_CONFLICT。不提供业务键不承诺去重。

IDEMPOTENCY_IN_PROGRESS 表示尚在处理，可稍后用原业务键及新签名重试；BUSINESS_RESULT_UNKNOWN（HTTP 503）表示无法确认结果，请保留原业务键与请求号联系平台核实，禁止更换业务键自动重复查验。权限撤销后，即使有历史结果也不再允许读取。

税局会话通道的 POST /api/v2/tax-connections/check-invoice 保留其独立业务契约与通道响应；认证统一不会把两个不同接口的业务字段强行改成同一套。

连接管理调用示例

POST /api/v2/tax-connections/create，method=QR（扫码）或 method=SMS（短信）。先按统一规则生成请求签名，直接发送 JSON；响应无需解密或二次 JSON.parse。

JSON
{
  "method": "QR",
  "nsrsbh": "<已授权企业税号>"
}
JSON
{
  "code": "OK",
  "message": "成功",
  "request_id": "req_example_002",
  "data": {
    "lsh": "<会话流水号>",
    "ewmdz": "<平台返回的短期二维码图片地址>",
    "yxq": "20261023120500"
  }
}

将返回的 ewmdz 作为短期图片资源地址获取 PNG；用 lsh 在 JSON 请求体中调用 POST /api/v2/tax-connections/detail 查询状态。示例占位值不可直接用于真实请求。

全部业务入口

本轮统一英文语义地址和 POST 方法，继续复用已验证的业务参数和处理逻辑；除创建连接新增 method 外，不会自动把 nsrsbh、lsh、kprq 等旧字段改名。英文业务字段、ISO 日期和任务模型仍为后续契约目标，不应混用。外层改为统一响应；旧版 returncode / returnmsg 不再作为新版外层字段返回。正常连接状态仍保留 data.ljzt 等业务字段；查无数据增加 data.status=NO_DATA，处理中返回 HTTP 202 并增加 data.status=PROCESSING。

连接管理

发票归集

  • 查询增量下载发票信息invoice.sync

    POST /api/v2/invoices/query-incremental

    请求字段摘要：nsrsbh、gjrq（归集日期）、sjlx、fplx、packageno；与按开票日期区间查询的 FPJCXX 是两种契约。

    查看业务字段和返回字段说明（新版使用本页路径及信封）
  • 按开票日期查询发票清单invoice.sync

    POST /api/v2/invoices/query

    请求字段摘要：nsrsbh、gjbq（1 销项 / 2 进项）、kprqq、kprqz；可选 fpztDm、fplyDm、fplxDm、sflzfp、dtBz、pageNumber、pageSize。

    查看业务字段和返回字段说明（新版使用本页路径及信封）
  • 批量发票下载申请invoice.sync

    POST /api/v2/invoice-download-jobs/create

    请求字段摘要：nsrsbh、kprqq、kprqz、fplx、sjlx；返回批次流水号用于申请反馈，不能混用其他企业或旧版批次。

    乐企直连（NATURAL 通道）能力，tax-hub 已实现，E6 侧对接代码已完成（2026-09-21，commit e851fdf7），尚未真机/沙箱端到端验证

  • 批量发票下载申请反馈invoice.sync

    POST /api/v2/invoice-download-jobs/query

    请求字段摘要：lsh、packageno：本企业通过新版申请得到的批次流水号及分包号。

    同上

  • 发票用途状态信息查询invoice.sync

    POST /api/v2/invoices/query-usage-status

    请求字段摘要：nsrsbh、fplx、fphm、kprq；可选 fpdm，按发票用途状态查询业务定义传递。

    tax-hub 已实现，ERP 尚未接入调用

  • 发票风险信息查询invoice.sync

    POST /api/v2/invoices/query-risks

    请求字段摘要：nsrsbh、fplx、qsrq、zzrq、pagesize；其余筛选和分页字段按风险查询定义。

    tax-hub 已实现，ERP 尚未接入调用

发票明细

发票查验

基础版开票

  • 获取数电票批量预赋码信息invoice.issue

    POST /api/v2/invoice-numbers/reserve

    请求字段摘要：nsrsbh；lysl 为领用数量，ywlsh 为业务流水号，按预赋码业务约束传递。

    对应 Natural System NS-API-001。tax-hub 已实现，E6 侧对接代码已完成（2026-09-21，commit e851fdf7），尚未真机/沙箱端到端验证

  • 查询发票额度invoice.issue

    POST /api/v2/invoice-quotas/query

    请求字段摘要：nsrsbh：已授权企业税号。

    对应 Natural System NS-API-002。tax-hub 已实现，ERP 尚未接入调用

  • 下载/退回发票额度invoice.issue

    POST /api/v2/invoice-quotas/apply

    请求字段摘要：nsrsbh、ptbh、sqlx；sqed、ywlsh 按申请类型传递。写操作，先确认申请类型与额度。

    对应 Natural System NS-API-003。写操作。tax-hub 已实现，ERP 尚未接入调用

  • 调整发票额度有效期invoice.issue

    POST /api/v2/invoice-quotas/update-validity

    请求字段摘要：xsfnsrsbh、sxedsq（额度所属月份）。税号字段是 xsfnsrsbh，不是 nsrsbh。

    对应 Natural System NS-API-004。写操作，请求字段是 xsfnsrsbh，不是 nsrsbh。tax-hub 已实现，ERP 尚未接入调用

  • 查询纳税人风险信息invoice.issue

    POST /api/v2/taxpayers/query-risks

    请求字段摘要：nsrsbh：已授权企业税号。

    对应 Natural System NS-API-005。tax-hub 已实现，ERP 尚未接入调用

  • 查询纳税人基本信息invoice.issue

    POST /api/v2/taxpayers/detail

    请求字段摘要：nsrsbh：已授权企业税号。

    对应 Natural System NS-API-006。tax-hub 已实现，ERP 尚未接入调用

  • 查询可用税率信息invoice.issue

    POST /api/v2/tax-rates/query

    请求字段摘要：nsrsbh：用于校验本次调用的企业及税号权限，仍须在请求体中提供。

    对应 Natural System NS-API-007。tax-hub 已实现，ERP 尚未接入调用

  • 查询税收分类编码信息invoice.issue

    POST /api/v2/tax-categories/query

    请求字段摘要：nsrsbh；可选 sjc、sjswjgdm。sjc 为业务时间戳，不替代签名头 X-Timestamp。

    对应 Natural System NS-API-008。tax-hub 已实现，ERP 尚未接入调用

  • 查询数电红字确认单列表信息invoice.issue

    POST /api/v2/red-letter-confirmations/query

    请求字段摘要：yhjslx、xsfnsrsbh；可选购销双方名称/税号、录入日期区间、蓝字发票、确认单及 pageNumber、pageSize 等筛选字段。

    对应 Natural System NS-API-009。tax-hub 已实现，ERP 尚未接入调用

  • 查询数电红字确认单明细信息invoice.issue

    POST /api/v2/red-letter-confirmations/detail

    请求字段摘要：uuid、xsfnsrsbh：确认单 UUID 及销售方税号。

    对应 Natural System NS-API-010。tax-hub 已实现，ERP 尚未接入调用

  • 数电票上传invoice.issue

    POST /api/v2/invoice-batches/issue

    请求字段摘要：非空 JSON 发票数组；每项包含 xsfnsrsbh 及完整数电票业务字段（含开票方式、开票模式、发票明细等）。同一批次必须为同一销售方，须专门开通开票能力。

    对应 Natural System NS-API-011。⚠ 写操作，会真实开出发票——CAP-01 核心接口，18 个行业变体母版，接入前需要专门授权，不可当成普通只读查询对待。tax-hub 已实现，E6 侧对接代码已完成（2026-09-21，commit e851fdf7），尚未真机/沙箱端到端验证

  • 查询数电票上传结果invoice.issue

    POST /api/v2/invoice-batches/query-issue-result

    请求字段摘要：sllsh：本企业通过新版上传获得的受理流水号；逐项判断 data.resultList 中的业务结果。

    对应 Natural System NS-API-012。tax-hub 已实现，E6 侧对接代码已完成（2026-09-21，commit e851fdf7），尚未真机/沙箱端到端验证

  • 数电红字确认单申请invoice.issue

    POST /api/v2/red-letter-confirmations/create

    请求字段摘要：xsfnsrsbh、lzfphm、lzkprq 及录入身份、红冲原因、金额税额、hzqrdmxList 等完整申请字段。lzkprq 保留原蓝字发票的精确值，不自行改写。

    对应 Natural System NS-API-013。写操作。tax-hub 已实现，ERP 尚未接入调用

  • 数电红字确认单确认invoice.issue

    POST /api/v2/red-letter-confirmations/respond

    请求字段摘要：xsfnsrsbh、uuid、hzqrdbh、qrlx。申请与确认是两个独立步骤，不自动串联。

    对应 Natural System NS-API-014。写操作。tax-hub 已实现，ERP 尚未接入调用

  • 上传发票汇总确认信息invoice.issue

    POST /api/v2/invoice-summaries/submit-confirmation

    请求字段摘要：xsfnsrsbh、xsfsjswjgdm、ywlx、ptbh、yf；传递业务要求的蓝字/红字发票数量、金额与税额汇总。

    对应 Natural System NS-API-015。写操作。tax-hub 已实现，ERP 尚未接入调用

  • 查询发票汇总确认信息invoice.issue

    POST /api/v2/invoice-summaries/query-confirmation

    请求字段摘要：xsfnsrsbh、xsfsjswjgdm；可选 yf、ptbh。

    对应 Natural System NS-API-016。tax-hub 已实现，ERP 尚未接入调用

发票开具

  • 蓝字发票开具invoice.issue

    POST /api/v2/invoices/issue

    请求字段摘要：nsrsbh、bizNo 及 sellerName、buyerTaxNo、lines 等完整开票业务对象。bizNo 是业务幂等标识；结果未知时禁止换值重复开具。

    已实现，写操作；bizNo 保持既有业务幂等语义，不自动重试。

发票查验中心

  • 统一发票查验（单张 / 批量）invoice.check

    POST /api/v2/invoices/check

    请求字段摘要：tax_no：已授权企业税号；invoices：非空发票数组，每项 fphm、kprq、kpje 必填，fpdm 可选。

    按 tax_no + invoices 调用；与税局会话通道 check-invoice 的业务字段和结果不同。

会话、流水号与重试

同步的 Web 通道仍需建立税局会话。按会话流水号调用时，平台先解析真实税号再检查权限；批次反馈仅能访问本企业通过新版提交的批次。数电票批量上传要求同一批次属于同一销售方，并校验销售方税号授权。

切换版本前应先完成旧版批次；旧版产生的上传或下载流水不能直接用新版反馈接口查询。开票、上传、红字确认等写操作的业务幂等规则保持不变；超时或结果未知时先核对业务状态，不能盲目重发。调用重试必须更新随机数和签名，保留原业务幂等键。