知行之桥集成 Zoho Books：创建销售订单操作指南
本文将介绍如何通过知行之桥 REST 端口完成 Zoho OAuth 授权，并调用 Zoho Books API 创建销售订单。
第 1 步：准备配置数据
开始前准备以下内容：
| 数据 | 获取位置 |
|---|---|
| Callback URL | 知行之桥 REST 端口的 OAuth 配置页面 |
| Client ID、Client Secret | Zoho API Console |
| Organization ID | Zoho Books → 设置 → 组织配置文件 |
| Customer ID | Zoho 客户记录的 contact_id |
| Item ID | Zoho 商品或具体商品变体的 item_id |
| 客户原始订单号 | 外部业务系统或 EDI 订单 |
确认以下前置条件：
- 授权用户可以访问目标 Zoho Books 组织；
- 客户和商品均属于该组织；
- 商品或具体变体处于可销售状态；
- Zoho Books 已启用销售订单自动编号。
第 2 步：在 Zoho 创建 OAuth 客户端
- 登录 Zoho API Console。
- 选择
Server-based Applications。 - 填写 Client Name 和 Homepage URL。
- 将知行之桥显示的 Callback URL 原样填写到
Authorized Redirect URIs。 - 创建应用，复制 Client ID 和 Client Secret。
Callback URL 必须与知行之桥显示的值完全一致，包括协议、域名、端口、路径、大小写和末尾斜杠。
示例：
https://arc.example.com/src/oauthCallback.rst第 3 步：在知行之桥配置 OAuth
在 REST 端口的认证配置中填写：
| 配置项 | 配置值 |
|---|---|
| 身份认证类型 | OAuth 2.0 |
| 授权类型 | 选择 授权码 |
| 身份验证 URL | https://accounts.zoho.com/oauth/v2/auth?access_type=offline&prompt=consent |
| 访问令牌 URL | https://accounts.zoho.com/oauth/v2/token |
| 刷新令牌 URL | https://accounts.zoho.com/oauth/v2/token |
| 客户端 ID | <ZOHO_CLIENT_ID> |
| 客户端密钥 | <ZOHO_CLIENT_SECRET> |
| 范围 | ZohoBooks.salesorders.CREATE |
注意：上表中的 https://accounts.zoho.com 是ZOHO美国数据中心示例；其他数据中心使用对应的 Zoho Accounts 域名。
第 4 步：获取 Access Token 和 Refresh Token
- 保存 OAuth 配置。
- 单击"获取新的访问令牌"。
- 使用有权访问目标 Zoho Books 组织的账号登录。
- 在 Zoho 授权页面确认授权。
- 返回知行之桥，确认同时取得 Access Token 和 Refresh Token。
通过标准：
- Access Token 已生成；
- Refresh Token 已生成；
- 知行之桥日志中没有
invalid_client、invalid_redirect_uri或invalid_code。
授权码 由 Callback URL 接收并自动交换 Token，不需要填写到销售订单请求中。
第 5 步：取得 Organization ID
在 Zoho Books 中打开：
设置（Settings）→ 组织配置文件（Organization Profile）→ Organization ID将该值保存为 <ORG_ID>。
第 6 步：取得 Customer ID
Zoho Books 销售订单中的 customer_id 对应客户记录的 contact_id。
操作步骤
- 登录 Zoho Books。
- 进入 销售 → 客户。
- 打开目标客户详情。
- 查看浏览器地址栏。
- 取得客户路由后的长数字 ID。
URL 示例
https://books.zoho.com/app/<ORG_ID>#/contacts/460000000026049其中 460000000026049 为 contact_id，创建销售订单时填入：
{
"customer_id": "460000000026049"
}第 7 步：取得 Item ID
Zoho Books 销售订单行中的 item_id 对应具体可销售商品 ID。
操作步骤
- 进入 商品 → 商品。
- 打开目标商品详情。
- 查看浏览器地址栏。
- 取得商品路由后的长数字 ID。
URL 示例
https://books.zoho.com/app/<ORG_ID>#/items/460000000017088其中 460000000017088 为 item_id，创建销售订单行时填入：
{
"item_id": "460000000017088"
}第 8 步：配置创建销售订单请求
在知行之桥 REST 端口中配置：
| 配置项 | 配置值 |
|---|---|
| Method | POST |
| URL | https://www.zohoapis.com/books/v3/salesorders?organization_id=<ORG_ID> |
| Authentication | 选择前面已完成授权的 OAuth 连接 |
| Body Type | raw |
| Content-Type | application/json |
| Authorization Header | 由 OAuth 连接自动生成，不要手工重复添加 |
请求正文：
{
"customer_id": "<CUSTOMER_ID>",
"date": "<ORDER_DATE_YYYY-MM-DD>",
"reference_number": "<CUSTOMER_ORIGINAL_ORDER_NUMBER>",
"line_items": [
{
"item_id": "<ITEM_ID>",
"quantity": 1,
"rate": 100
}
],
"notes": "Created by integration"
}字段要求：
| Zoho 字段 | 填写规则 |
|---|---|
customer_id |
目标组织中客户的 contact_id |
date |
格式为 YYYY-MM-DD |
reference_number |
客户原始订单号 |
line_items[].item_id |
目标组织中可销售商品的 item_id |
line_items[].quantity |
数值且大于 0 |
line_items[].rate |
商品单价 |
不要在请求中传 salesorder_number。该字段由 Zoho Books 自动生成，客户原始订单号写入 reference_number即可。
第 9 步：发送请求
进入 REST 端口的"事务"页面，上传已准备好的 JSON 文件并单击"发送"。请求处理完成后，在"输出文件"列打开 Zoho 返回的 JSON 响应，核对订单创建结果。
知行之桥显示"成功"仅表示请求已完成处理。还需打开输出 JSON，确认 Zoho 返回 code: 0，且响应中包含 salesorder、salesorder_id 和自动生成的 salesorder_number，方可判定销售订单创建成功。
第 10 步：核对创建结果
必须同时满足以下条件，才能判定销售订单创建成功：
- Zoho 返回成功响应，并包含
salesorder对象。 - 响应包含
salesorder_id。 salesorder_number由 Zoho 自动生成。reference_number与客户原始订单号一致。total与订单行数量、单价及税费规则一致。- 在 Zoho Books UI 中能够查看对应销售订单。
结语
通过知行之桥，企业可以将 Zoho Books 与 ERP、电商平台、仓储系统及 EDI 业务流程连接起来，在统一界面中完成 REST/OAuth 连接配置、业务数据转换、流程编排和运行日志追踪，减少点对点接口的重复开发与运维工作。