MetriCRM REST API

身份验证

在 设置 → API 密钥 中创建密钥，并作为 Bearer 令牌发送。密钥格式为 mck_您的工作区_…，以创建者的身份操作，且只能访问其范围内的资源。使用 api.metricrm.com/v1，或您的工作区地址加 /api/v1。

curl https://api.metricrm.com/v1/me \
  -H "Authorization: Bearer mck_your-workspace_…"

分页与筛选

列表每页最多返回 100 条记录并附带 nextCursor；将其作为 cursor 传回即可获取下一页。可按 createdAt 或 updatedAt 升序或降序排序，并使用 updatedSince 只同步有变化的记录。

curl "https://api.metricrm.com/v1/contacts?limit=50&updatedSince=2026-10-01T00:00:00Z&order=asc&sort=updatedAt"
# → { "data": [ … ], "nextCursor": "WyIyMDI2LTEwLTEz…" }
curl "https://api.metricrm.com/v1/contacts?limit=50&cursor=WyIyMDI2LTEwLTEz…"

错误

错误使用标准 HTTP 状态码和统一的 JSON 格式：可供程序判断的代码、易读的消息，以及输入无效时需要修正的字段。401 表示缺少密钥或密钥已失效；403 表示其范围、所有者角色或 IP 允许列表不允许该调用；404 也包括密钥无法查看的记录。

HTTP/1.1 400 Bad Request
{ "error": { "code": "invalid_request",
    "message": "Some fields are missing or invalid.",
    "details": [ { "path": "email", "message": "Invalid email address" } ] } }

速率限制

每个密钥有自己的每分钟限额（默认 600，在创建密钥时设置）。每个响应都会告诉您剩余额度；达到限额时，请等待 Retry-After 中的秒数。

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 42
Retry-After: 42

幂等性

POST 请求请附带 Idempotency-Key 请求头。如果网络失败而您在 24 小时内以相同的键和内容重试，您将得到第一次的响应，而不会产生重复记录。

curl https://api.metricrm.com/v1/contacts \
  -H "Authorization: Bearer $METRICRM_API_KEY" \
  -H "Idempotency-Key: 6f1c2a9e-0b6d-4c1e-9a55-2f1d0e7b3c11" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Aisyah","lastName":"Rahman","email":"aisyah@sinar.my"}'

Webhook

设置 → Webhook 会把事件（case.created、invoice.paid 等）以 JSON 发送到您的 HTTPS 端点。每个请求按 Standard Webhooks 签名：用端点的 whsec_ 密钥校验 webhook-signature，拒绝过旧的时间戳，并用 webhook-id 忽略重复请求。返回任意 2xx 状态即可；其他响应会重试约 3.5 天。

// Node.js: verify a MetriCRM webhook (Standard Webhooks)
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, headers, rawBody) {
  const id = headers["webhook-id"], ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // too old
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest();
  return headers["webhook-signature"].split(" ").some((s) => {
    const sig = Buffer.from(s.split(",")[1] ?? "", "base64");
    return sig.length === expected.length && timingSafeEqual(sig, expected);
  });
}

// Body: { "type": "case.created", "timestamp": "…",
//         "data": { "id": "…", "entityType": "case", "object": { … }, "changes": { … } } }

curl "https://api.metricrm.com/v1/me?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/accounts?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/contacts?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/cases?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/comments?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/leads?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/opportunities?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/quotations?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/orders?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/invoices?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/payments?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/products?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/tasks?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/activities?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/articles?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/messages?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"

curl "https://api.metricrm.com/v1/users?limit=10" \
  -H "Authorization: Bearer $METRICRM_API_KEY"