知行之桥集成 Zoho Books：创建销售订单操作指南

本文将介绍如何通过知行之桥 REST 端口完成 Zoho OAuth 授权，并调用 Zoho Books API 创建销售订单。

第 1 步：准备配置数据

开始前准备以下内容：

确认以下前置条件：

• 授权用户可以访问目标 Zoho Books 组织；
• 客户和商品均属于该组织；
• 商品或具体变体处于可销售状态；
• Zoho Books 已启用销售订单自动编号。

第 2 步：在 Zoho 创建 OAuth 客户端

1. 登录 Zoho API Console。
2. 选择 Server-based Applications。
3. 填写 Client Name 和 Homepage URL。
4. 将知行之桥显示的 Callback URL 原样填写到 Authorized Redirect URIs。
5. 创建应用，复制 Client ID 和 Client Secret。

Callback URL 必须与知行之桥显示的值完全一致，包括协议、域名、端口、路径、大小写和末尾斜杠。

示例：

https://arc.example.com/src/oauthCallback.rst

第 3 步：在知行之桥配置 OAuth

在 REST 端口的认证配置中填写：

第 4 步：配置创建销售订单的 REST 请求

OAuth 连接建立成功后，在 REST 功能端口中配置销售订单接口：

第 5 步：取得 Organization ID

在 Zoho Books 中打开：

设置（Settings）→ 组织配置文件（Organization Profile）→ Organization ID

将该值保存为 <ORG_ID>。

第 6 步：取得 Customer ID

Zoho Books 销售订单中的 customer_id 对应客户记录的 contact_id。

操作步骤

1. 登录 Zoho Books。
2. 进入 销售 → 客户。
3. 打开目标客户详情。
4. 查看浏览器地址栏。
5. 取得客户路由后的长数字 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。

操作步骤

1. 进入 商品 → 商品。
2. 打开目标商品详情。
3. 查看浏览器地址栏。
4. 取得商品路由后的长数字 ID。

URL 示例

https://books.zoho.com/app/<ORG_ID>#/items/460000000017088

其中 460000000017088 为 item_id，创建销售订单行时填入：

{
  "item_id": "460000000017088"
}

第 8 步：配置创建销售订单请求

在知行之桥 REST 端口中配置：

请求正文：

{
  "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"
}

字段要求：

不要在请求中传 salesorder_number。该字段由 Zoho Books 自动生成，客户原始订单号写入 reference_number即可。

第 9 步：发送请求

进入 REST 端口的“事务”页面，上传已准备好的 JSON 文件并单击“发送”。请求处理完成后，在“输出文件”列打开 Zoho 返回的 JSON 响应，核对订单创建结果。

知行之桥显示“成功”仅表示请求已完成处理。还需打开输出 JSON，确认 Zoho 返回 code: 0，且响应中包含 salesorder、salesorder_id 和自动生成的 salesorder_number，方可判定销售订单创建成功。

第 10 步：核对创建结果

必须同时满足以下条件，才能判定销售订单创建成功：

1. Zoho 返回成功响应，并包含 salesorder 对象。
2. 响应包含 salesorder_id。
3. salesorder_number 由 Zoho 自动生成。
4. reference_number 与客户原始订单号一致。
5. total 与订单行数量、单价及税费规则一致。
6. 在 Zoho Books UI 中能够查看对应销售订单。

结语

通过知行之桥，企业可以将 Zoho Books 与 ERP、电商平台、仓储系统及 EDI 业务流程连接起来，在统一界面中完成 REST/OAuth 连接配置、业务数据转换、流程编排和运行日志追踪，减少点对点接口的重复开发与运维工作。

如果你正在规划 Zoho Books 与现有业务系统的集成，知行软件团队可结合实际业务场景，提供流程梳理、接口验证、数据映射及测试上线支持。