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 不會保存金鑰本身，只保存一份打亂過、還原不回來的版本。所以沒有人能再看到金鑰，管理員也一樣

常見問題

延伸閱讀