获取access、refresh token后如何调用Zoho Invoice REST API

通用请求必填参数 #

所有REST接口调用都要满足以下要求，缺项大概率会报鉴权或参数错误：

• 基础请求地址要和你OAuth应用注册时选择的部署区域一致，不要跨区调用：
  • 海外通用区用https://invoice.zoho.com/api/v3
  • 中国区用https://invoice.zoho.com.cn/api/v3
  • 欧盟、印度等其他区域对应换域名前缀即可
• 请求头强制携带两个字段：
  • 鉴权头：Authorization: Zoho-oauthtoken 替换成你拿到的access_token，注意前缀固定是Zoho-oauthtoken，不要用常见的Bearer前缀，否则直接报鉴权失败
  • 内容类型头：查询类接口统一传Content-Type: application/json;charset=UTF-8，上传文件、提交表单类接口换成application/x-www-form-urlencoded或multipart/form-data即可
• 通用查询参数按需传：
  • 多组织账号必须传organization_id，值可以在你登录Zoho Invoice后台的浏览器地址栏里找到，单组织账号可以省略
  • 分页参数：page指定页码，per_page指定单页返回条数，最大支持200条/页
  • 业务过滤参数和具体接口绑定，比如按发票状态、创建时间范围筛选的参数，直接拼在URL查询串里就行

获取发票列表接口调用示例 #

这个接口是最基础的查询接口，参数规则如下：

• 请求方法：GET
• 接口路径：/invoices
• 支持的常用过滤参数：
  • status：按发票状态筛选，可选值包括draft（草稿）、sent（已发送）、paid（已支付）、overdue（逾期）、all（全部）等
  • date_start/date_end：按发票创建时间范围筛选，格式为yyyy-MM-dd
  • customer_id：按所属客户筛选

可参考的curl请求样例：

curl --request GET 'https://invoice.zoho.com/api/v3/invoices?page=1&per_page=25&status=all' \
--header 'Authorization: Zoho-oauthtoken 1000.abcdef123456.7890xyzabcd' \
--header 'Content-Type: application/json'

请求成功会返回HTTP 200状态码，响应体里code字段为0代表请求成功，invoices数组就是对应页的发票列表数据，page_context字段里会返回总条数、总页数等分页信息。

常见踩坑提示：如果返回401状态码，基本是access_token过期导致，access_token默认有效期1小时，过期后用之前留存的refresh_token调用OAuth刷新接口即可换新的access_token，不需要重新走全量授权流程。刷新时提交grant_type=refresh_token、refresh_token、client_id、client_secret几个参数到对应区域的OAuth令牌端点即可。

内容的提问来源于stack exchange，提问作者qmarsun