调用模式

同步与异步

柠檬云 API 包含两类调用模式：

同步接口：请求后立即返回业务结果，如发票查验。

异步接口：由于需要与税局系统交互、处理耗时不可控，登录、归集、下载和开票等接口采用异步模式。接入方先提交请求取得任务 ID，再通过回调通知或主动轮询获取任务终态，最后按需调用结果查询接口。

字段命名说明：现有业务接口因历史兼容同时存在 taskID 和 taskId 两种字段名，请以具体接口 schema 为准，不要自动转换大小写。回调通知中的字段固定为 taskId。

异步任务推荐流程

异步接口建议按“提交任务 → 等待任务完成 → 获取业务结果”的流程接入。等待任务完成时，推荐优先配置回调通知，由柠檬云在产生任务通知后主动推送任务状态及相关数据；同时保留主动轮询作为兜底方案，避免回调地址临时不可用时影响业务闭环。

回调能力需要提前绑定应用的回调 URL。配置方式、推送报文、响应要求和签名校验请参考回调通知配置。

提交任务

调用创建类接口提交任务，接口会返回任务 ID。接入方需要完整保存该标识，后续回调通知、状态查询和结果查询都以它作为关联依据。

等待任务完成

推荐采用以下组合方式：

回调通知：产生任务通知后，柠檬云会向已绑定的回调 URL 推送 taskId、taskStatus 及相关数据。接入方完成必要的幂等记录后，应及时返回 HTTP 2xx 状态码；响应体没有固定格式要求。

主动轮询：以 3～5 秒为间隔查询任务状态，直到出现成功或失败等终态。即使已配置回调，也建议保留轮询作为降级方案。

获取业务结果

当回调或轮询确认任务成功后，再调用对应的数据查询接口或结果查询接口，获取完整结构化数据、附件地址、发票号码、PDF 链接等业务结果。

异步三步流程示例

示例一：发票数据同步

发起发票数据同步

传入纳税人识别号（uscc）、地区编码（areaCode）、取票时间范围等参数，接口返回 taskID：

POST /api/v1/open/invoice-sync/create-task

等待任务完成

如已配置回调通知，可根据通知中的 taskStatus 判断任务状态；也可以主动轮询 taskID 对应的执行状态，直到出现终态：

status=1：执行完成，可继续取数

status=-1：执行失败，参考返回的 message 排查原因

POST /api/v1/open/invoice-sync/task-status

获取结构化数据

状态为成功后，调用数据查询接口传入 taskID，获取完整发票数据。

示例二：发票开具

提交开具请求

支持单张或批量开具，接口返回 taskID：

POST /api/v1/open/invoice-issue/issue

等待开具完成

如已配置回调通知，可根据通知中的 taskStatus 判断开具进度和结果；也可以主动轮询。当状态为 1（完成）或 -1（失败）时停止等待：

POST /api/v1/open/invoice-issue/issue-status

查询开具结果

开具完成后，获取发票号码、PDF 链接等详细信息。

同步模式示例

发票查验属于同步接口，调用后即时返回查验结论：

POST /api/v1/open/invoice-check

适用于单张发票实时核验，无需轮询。

多任务并发

当需要同时处理多个税号的相同业务（如并行同步不同企业的发票数据）时，推荐如下策略：

并行提交多个任务，各自取得独立的任务 ID

建立任务 ID 与企业、业务类型、请求参数之间的映射关系

优先根据回调通知里的 taskId 定位任务并取数

对长时间未收到回调的任务，使用主动轮询补偿查询

某个任务完成后立即取数，其余任务继续等待

平台内部会自动调度登录态复用与任务排队，尽量减少短信验证码的消耗次数。

回调与轮询选择建议

场景	推荐方式	说明
生产环境异步任务	回调通知 + 轮询兜底	减少无效查询，请求量更稳定
调试阶段或本地联调	主动轮询	本地环境通常无法稳定接收公网回调
批量企业任务	回调通知	通过 `taskId` 分发处理结果，避免集中轮询压力
回调异常或超时	主动轮询	作为降级方案补偿获取任务状态

配置回调前，请先准备外网可访问的回调地址，并确保能在超时时间内返回 HTTP 2xx 状态码。响应体没有固定格式要求，可以为空；详细要求见回调通知配置。

同步与异步#

异步任务推荐流程#

异步三步流程示例#

同步模式示例#