⑤ 发票统计与对账

月底对账用。一个接口，靠 URL 上的 type 参数决定查什么，共 5 种。★统计类都是「先发起、再查结果」的两步式：发起时给回调地址，拿到 record_id，再用对应的 -query 拿数据。

属「正向开票 · 腾讯联用」——开票通道的签名与加密全在开灵中台，你只调这一个。

接口

POST  https://openapi.kailingteck.com/api/v1/invoice/forward/statistic?type=detail

鉴权：X-App-Key ＋ X-Timestamp（Unix 秒）＋ X-Sign（＝ sha256(appKey ＋时间戳＋报文原文＋ appSecret) 小写十六进制）。与开灵其它接口完全一致。

请求参数

字段	必填	大白话说明
`type（URL 参数）`	必填	★决定查什么，5 选 1：detail 销项发票明细 / tax-rate 发起税率统计 / tax-rate-query 查税率统计结果 / declare 发起申报统计 / declare-query 查申报统计结果
`（其余参数按 type 不同而不同）`	—	★请展开下面对应的业务块，看该 type 具体要传什么、返回什么

请求示例

POST /api/v1/invoice/forward/statistic?type=detail

{
  "tax_code": "91110119MABQDU249D",
  "invoice_type_code": "026",
  "tax_rate": "0.13",
  "year": 2026,
  "month": 8,
  "page": 0,
  "size": 10,
  "callback_url": "https://你们的域名/statistic-callback"
}

按业务展开（点开看各自的参数）

统一信封 code／msg／requestId／timestamp／data，业务字段都在 data 里。code 为 CYT_00000 表示调用成功。

返回参数（data）

字段	大白话说明
`（返回随 type 不同）`	★发起类（detail / tax-rate / declare）统一只返回一个 record_id；数据本身走回调，或用对应的 -query 接口拿
`record_id`	统计任务 ID。拿着它去调 tax-rate-query 或 declare-query 取结果

返回示例（成功）

{
  "code": "CYT_00000",
  "data": { "record_id": "5f082009b4ff7d6b03389fbf", "mock": false }
}

异常与报错

情形	含义与处理
type 不合法	只能是 detail / tax-rate / tax-rate-query / declare / declare-query 五个之一
统计结果为空 / record_id 查不到数据	★统计是异步的。发起后要等上游算完，隔几秒再用 -query 查，或者干脆等 callback_url 推送
明细查不到第二页	page 从 ★0 开始，不是 1
申报统计数字对不上	确认 declare_type 传对了——免税和即征即退各档是分开统计的，不是一次出全

前端怎么用

// 两步式：先发起，拿 record_id，再取结果
const t = await post('/api/v1/invoice/forward/statistic?type=tax-rate', {
  tax_code, invoice_type_code: '026', year: 2026, month: 8, callback_url,
});
await sleep(3000);
const r = await post('/api/v1/invoice/forward/statistic?type=tax-rate-query', {
  record_id: t.data.record_id,
});
// 对账看 record_list[].sell_price / sell_tax（已扣红冲作废）

★本接口不计费，随便查。只有开票计费，一张票算一次。detail 明细只走回调，没有配套的 -query。⚠ 实测提示（2026-08-29 复测）：本接口的 5 个 type 目前一律返回通道 503——发票统计服务在上游是独立开通的模块，开灵当前账号尚未开通；同账号同签名的开票、查票、红冲均正常。下面的请求与返回字段依据通道方接口文档整理，参数结构可直接照用，待开通后我们会补上实测报文。接入前请先找开灵确认贵司账号已开通统计服务。

← ④ 查红票