接口调用

柠檬云通过 HTTPS 提供 JSON API。业务接口当前统一使用 POST 方法，路径和请求结构以具体接口文档为准。接入方可使用任意支持 HTTP 的编程语言完成对接。

公共请求头

需要鉴权的 JSON API 请求须携带以下头信息；获取令牌、刷新令牌及回调通知等接口以各自文档为准：

参数名称	参数类型	是否必填	说明
Content-Type	String	是	固定值 `application/json;charset=UTF-8`
Authorization	String	是	格式 `Bearer <access_token>`，获取方式见获取access_token

公共响应结构

业务接口通常返回统一的 JSON 结构，包含业务状态码、响应描述和业务数据。不同接口的 data 结构以具体接口文档为准。

参数名称	参数类型	说明
code	Integer	业务状态码，`0` 表示成功，非 `0` 表示失败
message	String	响应描述，成功时通常为 `success`，失败时返回错误原因
data	Object	业务数据，具体字段以各接口文档为准；失败时可能为空或不返回

以获取 access_token 为例，成功响应如下：

{
    "code": 0,
    "message": "success",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expires_in": 7200,
        "refresh_token": "v1.7Jf9...opaque-token...q2K",
        "refresh_expires_in": 2592000
    }
}

异常响应

接口调用失败时，响应体仍以 code 和 message 表示错误类型与原因。HTTP 状态码可能为 400、401 等，具体以接口实际返回为准。

令牌失效或过期

{
    "code": 401,
    "message": "Unauthorized"
}

请求参数错误，以获取 access_token 时 appId 或 appSecret 不正确为例：

{
    "code": 400,
    "message": "appId 或 appSecret 不正确"
}

注意事项

令牌有效期：access_token 最长有效期为 2 小时。临近过期时应使用 refresh_token 刷新；刷新失败并返回 HTTP 401 时重新获取令牌，详见获取 access_token

编码规范：请求体与响应体统一使用 UTF-8

异步接口：登录、归集、下载和开票等耗时操作采用异步模式，调用后通过回调通知或主动轮询获取任务状态，详见调用模式

公共请求头#

公共响应结构#

异常响应#

注意事项#

公共请求头

公共响应结构

异常响应

注意事项