將您的系統串接至 Marcomm AI

1. 1
   申請存取權限

   說明您的系統並選擇所需資料。我們會逐一審查申請。

2. 2
   建立金鑰

   核准後，在「設定 → API」中建立金鑰。金鑰只會顯示一次，請將它存放在您的系統中。

3. 3
   傳送請求

   在 Authorization 標頭中帶入金鑰，然後呼叫下方任一端點。

請求範例

curl https://app.marcomm.works/api/v1/news/digest?days=7 \
  -H "Authorization: Bearer mc_live_..."

每次請求都以 Bearer 權杖的形式傳送金鑰。個人金鑰會以建立者本人的身分運作，因此能以其名義讀取並處理核准。工作區金鑰由管理員建立，只能讀取。金鑰可設定到期時間、限制 IP 位址，也可以輪替：輪替後舊金鑰仍可使用 24 小時。

每把金鑰只帶有您的申請獲准的權限範圍。

news

新聞摘要、文章與媒體。

crisis

重要新聞與危機事件。

approvals

待核准項目，以及使用個人金鑰批准或駁回。

content

讀取新聞稿與部落格文章。

路徑以 /api/v1 開頭。讀取端點使用 GET 並接受查詢參數。回應為 JSON，格式為 {"data": ...}。

向該項目傳送 {"decision": "approve"} 或 {"decision": "reject", "comment": "..."}。駁回時必須附上說明。決定遵循與應用程式及 Slack 相同的規則，並記錄在金鑰擁有者名下。當內文含有需要確認的用語時，您會收到附帶警告的 409 confirmation_required，此時可加上 "force": true 重新傳送請求。

curl -X POST https://app.marcomm.works/api/v1/approvals/press-releases/<id> \
  -H "Authorization: Bearer mc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"decision":"reject","comment":"Please fix the headline."}'

限制依工作區設定，分為每分鐘與每日（UTC）。回應都會附上下列標頭。超出限制時，您會收到 429 與 Retry-After。如需提高限制，請在「設定 → API」中申請，由我們的團隊審查。

X-RateLimit-Limit

每分鐘允許的請求數。

X-RateLimit-Remaining

目前這一分鐘剩餘的請求數。

X-RateLimit-Reset

分鐘視窗重設時的 Unix 時間。

X-RateLimit-Day-Limit

每日允許的請求數。

X-RateLimit-Day-Remaining

今日剩餘的請求數。

Retry-After

重試前需等待的秒數。僅在 429 時回傳。

錯誤以 JSON 回傳，格式為 {"error": {"code": ..., "message": ...}}。

警示、核准請求與早晨簡報也可以推送到您的系統。在「設定 → API → Webhook」中新增接收端點。每個請求都是 JSON，包含欄位 event（alert、approval 或 briefing）、workspace、title、text、url、data 與 sentAt。核准請求帶有 data.kind（press_release、blog 或 event）與 data.id，可據此透過 API 讀取並處理。

每個請求都附有簽章。使用您的簽章金鑰對原始請求本文計算 HMAC-SHA256，並與格式為 sha256=<hex> 的 X-Marcomm-Signature 標頭比對。不相符的請求應予以拒絕。

在 Node.js 中驗證 Webhook

import { createHmac, timingSafeEqual } from 'node:crypto';

export function isFromMarcomm(rawBody: string, signature: string, secret: string) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}