开发必读

本文档面向首次对接柠檬云 API 的开发人员，梳理了从商务接入到业务调用的完整流程。建议按顺序阅读并完成各步骤，确认每一环节通过后再进入下一步。

请先与柠檬云商务团队取得联系，沟通您的业务场景与集成需求。合作确认后，我们会为您开通相应产品权限，并提供接入凭证：

appId：您的应用唯一标识，用于身份识别

appSecret：配套密钥，请妥善保管，切勿在客户端或公开渠道暴露

商务团队会随凭证一并提供接口基础地址（apiHost），环境与地址详情请查看对接地址.md。

使用 appId 与 appSecret 调用登录接口，换取 JWT Bearer Token：

POST /api/v1/open/auth/login

access_token 最长有效期为 2 小时，refresh_token 最长有效期为 30 天。接入方应缓存令牌，并在访问令牌临近过期时调用刷新令牌接口。完整说明见认证鉴权和获取 access_token。

除获取令牌、刷新令牌等明确标注无需鉴权的接口外，业务请求须在 HTTP Header 中携带访问令牌：

Authorization: Bearer <access_token>

请求规范、公共返回结构及异常码说明请查看接口调用。

根据实际业务场景选择对应接口模块：

发票数据同步：异步三步流程（发起同步 → 获取状态通知或主动查询 → 查询同步结果）

发票开具：异步流程（创建开具任务 → 获取状态通知或主动查询 → 查询开具结果）

发票查验：同步调用，实时返回查验结论

税务登录：支持账密登录与短信验证码登录，登录成功后方可执行归集、开票等操作

异步接口的轮询逻辑与批量调用建议请查看调用模式；如需接收任务状态通知，请参考回调通知配置。

完成以上步骤后即可正式使用柠檬云 API，更多接口细节请查阅各业务模块文档。