Ordo 的 API

试试看

帮密钥取个名称，例如“Zapier”或“我们的网站”。在“密钥属于谁”选一个人，再点“创建密钥”。请马上复制密钥，Ordo 只会显示这一次

运作方式

• 密钥属于谁：每把密钥都属于一个人，只能做这个人在 Ordo 能做的事。销售的密钥只看得到销售自己的数据，经理的密钥看得到团队的数据，管理员的密钥看得到全部
• 规则都一样：密钥和画面用的是同一套规则。变更记录会把每次修改，记成密钥所属的人做的
• 只显示一次：新的密钥只会显示一次。请马上复制，贴到另一个程序里
• 收回：在密钥旁边点“收回”，这把密钥就会立刻失效
• 管理员都会知道：有人创建密钥时，其他每位管理员都会在铃铛里收到通知

每个请求都要附上密钥

请求就是程序发给 Ordo 的一条消息，例如“把公司列表发给我”。程序每次送出请求，都要在 Authorization 标头附上密钥。标头就是请求开头的一行

GET https://app.ordo-crm.com/api/v1/companies
Authorization: Bearer ordo_w1a2b3c4d5e6_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Ordo Cloud：网址是 https://app.ordo-crm.com。密钥本身就说明了它属于哪家公司
• Ordo On-site：网址是你们自己的 Ordo，例如 https://ordo.yourcompany.com。只有在你们的 Ordo 开放到互联网时，办公室以外的程序才连得到它。做法请看 Setup guide 里的“Use Ordo outside the office”

用 JSON 传数据，并加上 Content-Type: application/json。JSON 是一种用文字写数据的简单格式。时间一律是 UTC，例如 2026-11-03T08:00:00Z。日期的写法像 2026-11-03

用量上限

• 每把密钥每分钟最多 60 个请求
• 整家公司每天最多 10,000 个请求。每天从 UTC 午夜重新计算

超过上限时，Ordo 会返回 429，并附上 Retry-After 标头，告诉你要等几秒

程序可以做什么

<things> 可以是 companies（公司）、people（联系人）、deals（商机）、activities（会议和任务）或 notes（时间线上的记录）。通过 API 不会删除任何东西

列表

列表会一页一页传回来：

{ "data": [ { "id": 7, "name": "Acme Robotics", "...": "..." } ], "has_more": true, "next_offset": 50 }

想指定列表要显示什么，就在网址的 ? 后面加上下面这些，例如 /api/v1/[email protected]。两个之间用 & 隔开

字段

字段就是一条记录里的一项，例如名称或负责人。API 用的名称和 Ordo 的画面一样：公司是 companies，联系人是 people，商机是 deals

公司

联系人

商机

活动：会议和任务

同一个还没完成的任务，Ordo 不会创建两次。同一个任务的意思是主题一样，而且是同一条记录、同一个人的。这时 Ordo 会回传已经有的那个任务，并加上 "existing": true

笔记：时间线上的记录

• GET /api/v1/notes?company_id=7（或 person_id=、deal_id=）：一条记录时间线上的记录，最新的在前
• POST /api/v1/notes，内容是 { "deal_id": 42, "body": "Called Jane: budget approved" }。也可以加上 activity_id（这条记录的某场会议或某个任务）和 on_date（较早的日期）
• PATCH /api/v1/notes/<id>，送出新的 body。只有写这笔记录的人或管理员可以改

出错的时候

Ordo 会返回一个状态码，和一句告诉你该怎么做的话。状态码是一个数字，说明这个请求的结果。这句话是英文的

{ "error": "There's no field colour on companies. The fields are: name, status, ..." }

Webhook：Ordo 主动通知你的程序

Webhook 是你的程序的一个网址。发生事情时，Ordo 会发一条简短的消息到这个网址：一个带着 JSON 的 POST 请求

新建 Webhook

• 管理员在设置 → 连接 → 新建 Webhook添加：填网址，再选要发送什么。接着 Ordo 会显示它的签名密钥（whsec_…）。管理员之后可以点“显示密钥”再看一次
• 程序也可以用自己的 API 密钥新建 Webhook，用完再移除。送出 POST /api/v1/webhooks，内容是 { "url": "https://...", "events": ["deal.won"] }，Ordo 就会回传它的 id 和 secret。DELETE /api/v1/webhooks/<id> 会移除它，GET /api/v1/webhooks 会列出这把密钥自己的 Webhook。密钥被收回时，它的 Webhook 也会一起移除

Webhook 只会发送它所属的人看得到的东西。Ordo Cloud 只会传到公开的 https:// 网址

Ordo 会发送什么

消息的内容

{
  "id": "evt_5xKq2c9TfQ8a",
  "event": "deal.won",
  "created_at": "2026-11-03T08:00:00Z",
  "data": { "id": 42, "name": "40 cameras", "company": "Acme Robotics", "stage": "Won", "amount": 48000, "...": "..." }
}

data 就是这条记录在 API 里的样子。你的程序要在 10 秒内响应任何一个 2xx 的状态码，例如 200，意思是一切正常。如果你的程序没有响应，Ordo 会在 1 分钟后、10 分钟后再试，之后每小时试一次。一个 Webhook 连续失败一整天，就会被关闭，管理员也会在铃铛里收到通知

设置 → 连接 → 已发送的消息会列出每条消息和结果，还有“再发送一次”

确认消息是 Ordo 发来的

每条消息都有这个标头：

X-Ordo-Signature: t=1762156800,v1=5257a869e7ec...

v1 是用这个 Webhook 的密钥，对文字 <t>.<the body as sent>（t 的值、一个点，再接上原封不动的消息内容）算出的 HMAC-SHA256，用 hex 表示。HMAC-SHA256 是一种用密钥给文字签名的标准做法。请在你的程序里用同样的方式算一次，再比对两个值。也请确认 t 是最近的时间，例如 5 分钟以内，这样别人就没办法把旧的消息再送一次

JavaScript（Node）：

import crypto from "node:crypto";
function fromOrdo(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const want = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(t)) < 300 && v1?.length === want.length && crypto.timingSafeEqual(Buffer.from(want), Buffer.from(v1));
}

Python：

import hashlib, hmac, time
def from_ordo(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    want = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(parts["t"])) < 300 and hmac.compare_digest(want, parts["v1"])

其他标头：X-Ordo-Event（事件）和 X-Ordo-Delivery（这条消息在“已发送的消息”里的编号）

Make、n8n 和 Zapier

Make、n8n 和 Zapier 都有一个送出网络请求的步骤，和一个等待 Webhook 的步骤。在 Make 是 HTTP 和 Webhooks 模块，在 n8n 是 HTTP Request 和 Webhook 节点，在 Zapier 两个都在 Webhooks by Zapier 里

• 要读取或修改 Ordo 的数据：用送出网络请求的步骤，把 API 密钥放在它的 Authorization 标头，做法和上面一样
• 要接收 Ordo 的通知：用等待 Webhook 的步骤。复制它的网址，在 Ordo 添加一个 Webhook

小提醒

• API 和 Webhook 每个方案都有：Cloud、Cloud + AI 和 On-site，不用另外付费
• API 的第 1 版会维持不变。之后可能会增加新的字段，但不会改名或移除任何字段
• Ordo 不会保存密钥本身，只保存一份打乱过、恢复不回来的版本。所以没有人能再看到密钥，管理员也一样

常见问题

延伸阅读