乐企归集:那些文档里没写清楚,但联调一定会踩的规则

有一个误解，几乎每个刚接乐企用票的团队都有：

"发票归集下来了，不就有发票了吗？状态应该也一起回来了吧？"

答案是：没有。归集回来的只是一张票的票面明细，红没红冲、作没作废、勾没勾选、入没入账这类状态都没有。

这篇文章只讲三件事：归集、查验、入账。不讲勾选、不讲开票。因为这三件事的关系是一条链，搞清楚了，进项票池才建得起来。

一、归集能力：你拿到的只是"一张纸"，不是"一份档案" 

坑 1（本期核心）：归集回来的发票只有明细，没有状态

批量发票下载（全量下载 / 增量下载）返回的，是发票的结构化票面信息：发票代码号码、开票日期、购销方、金额、税额、明细行、税率等。

它不包含：

·发票状态（正常 / 已红冲 / 已作废 / 部分红冲） 

·增值税用途状态（未勾选 / 已勾选抵扣 / 已退税 / 不抵扣……） 

·消费税用途状态 

·入账状态（未入账 / 已入账 / 已入账撤销）

·风险 / 异常凭证状态 

想拿状态，必须单独调用归集能力下的"发票用途状态信息查询"接口。成熟的前置系统就是这么补偿的：查验或归集成功后，再调一次用途状态查询，把状态补回来。

对接建议：把"明细归集"和"状态获取"拆成两个独立任务，在票池里分两张表（或两组字段）存储：

·invoice_detail：票面明细，归集写入； 

·invoice_status：增值税用途状态 / 消费税用途状态 / 入账状态 / 风险状态，状态查询写入。 

永远不要让业务代码从明细表里读状态——读不到，而且会静默返回空值。

坑 2：用途状态查询没有批量接口，它是为"红冲前校验"设计的 

这是第二个认知断层。很多人想："状态要单独取，那我每天批量刷一遍全票池的状态不就行了？"

不行。乐企侧对"发票用途状态查询"的定位是：单笔应用场景，设定在开票方发起红冲前，校验蓝票是否允许部分红冲时参考使用。官方口径明确——不提供批量的发票用途状态接口。

有的前置系统做了折中，做成"一次最多勾选 10 张同步"。这意味着：

·想给十万张票的票池做全量状态刷新，在接口层面就不成立； 

·状态获取必须按需触发（报销时、勾选前、红冲确认前、风险巡检抽样），不能全量铺。 

·乐企平台针对发票用途状态查询接口有请求限制：每秒最多5次。

对接建议：

① 状态获取改为事件驱动：票进入报销流、进入勾选批次、被申请红冲时，才去查这一张；

② 全量状态刷新改用归集能力里的"发票状态更新 / 风险信息查询"类接口做补偿，而不是逐张查用途状态；

③ 建议设计合理的调用机制，尤其是客户要求定时全量更新发票的需求时，应主动降低客户心理预期，建议通过定时任务只更新开票日期一年内的发票

坑 3：增量归集的时间口径，是"平台归集时间"不是"开票日期" 

这条极易漏票。

增量下载按时间区间取数，但这个区间比对的是乐企平台把这张票归集进来的时间，而不是票面上的开票日期。一张 1 月 5 日开的票，平台可能 1 月 5 日归集，也可能延后几天才归集。

后果：你1 月 5 日跑任务查"1月2日—1月5日"，如果这张票实际是 1 月6 日才被平台归集，那它不在区间内，查不到。

对接建议：增量区间往前多叠 2—3 天做重叠窗口（例如每天查"前三天至当天"而不是只查当天），配合本地按票号去重。别把窗口卡成刚好一天。

坑 4：归集有三种类型，用错了票池永远缺票

·全量：按开票月份整体拉回，用来建底账； 

·增量：拉新增、变化的票，日常跑； 

·状态更新：只更新票池中已有发票的状态，不产生新票入池。 

典型事故：税局返回 100 张，你票池里只有 30 张，状态更新只会更新这 30 张的红冲/作废/勾选/入账状态，另外 70 张不会进池。定时任务只配了"状态更新"，于是永远缺票。

对接建议：全量（兜底）+ 增量（日常）+ 状态更新（刷新）三个任务都要有，缺一不可。

坑5：下载申请有配额，且区间不能跨月

·批量归集同一开票月份 + 同一发票类型，每天只能申请 1 次； 

·批量归集当前开票月份 + 同一发票类型，每月最多申请 5 次； 

·下载区间必须在同一自然月内，最大跨度就是一个自然月——想一次拉"1月1日—3月31日"会被直接拒绝。 

·增量归集只支持7天内的任意一天。

对接建议：本地建一张归集申请台账（税号 + 开票月份 + 发票类型 + 申请日期 + 流水号 + 结果），申请前先查配额；按月拆任务；申请的流水号必须落库，它是查询和重试的唯一钥匙。

坑 6：历史销项不支持归集，进项也有时间边界

官方口径很干脆：历史销项发票不支持归集。可下载的进/销项数据，是企业授权任意一种乐企能力后所取得/开具的发票（含所有开具渠道）；进项侧在完成数据迁移、申请在乐企勾选能力后，可下载近两年内取得的发票。

还有一条更隐蔽的：用票不是订阅能力就生效。乐企勾选能力需要单独向主管税务机关申请，由主管税务机关与企业确认勾选能力（数据迁移）的起始时间，通常会在当月申报期结束后。

对接建议：上线前先和主管税务机关确认用票生效时间点，历史数据大概率要从原平台导出导入，完成数据迁移后，原电子税务局中发票勾选页面会自动关闭。

后续我们将记录分享乐企发票勾选能力的对接业务和坑点；另外针对乐企沙箱测试效率低，坑点多问题，我们将提供乐企沙箱工具和乐企沙箱测试服务，有需要的小伙伴可以联系我们。