REST API MetriCRM

Pengesahan

Cipta kunci di Tetapan → Kunci API dan hantarkannya sebagai token bearer. Kunci berbentuk mck_ruang-kerja-anda_…, bertindak sebagai orang yang menciptanya dan hanya mencapai sumber dalam skopnya. Gunakan api.metricrm.com/v1 atau alamat ruang kerja anda diikuti /api/v1.

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

Penomboran dan penapis

Senarai memulangkan sehingga 100 rekod setiap halaman bersama nextCursor; hantarkannya semula sebagai cursor untuk halaman seterusnya. Isih mengikut createdAt atau updatedAt dalam mana-mana susunan, dan gunakan updatedSince untuk menyegerakkan perubahan sahaja.

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…"

Ralat

Ralat menggunakan kod status HTTP biasa dan satu bentuk JSON: kod untuk program anda, mesej yang mudah dibaca dan, bagi input tidak sah, medan yang perlu dibetulkan. 401 bermaksud kunci tiada atau tidak lagi sah; 403 bermaksud skop, peranan pemilik atau senarai IP kunci tidak membenarkan panggilan itu; 404 juga merangkumi rekod yang tidak dapat dilihat oleh kunci.

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

Had kadar

Setiap kunci mempunyai hadnya sendiri seminit (600 secara lalai, ditetapkan semasa mencipta kunci). Setiap respons menunjukkan baki anda; apabila had dicapai, tunggu bilangan saat dalam Retry-After.

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

Idempotensi

Hantar pengepala Idempotency-Key bersama permintaan POST. Jika rangkaian gagal dan anda mencuba semula dengan kunci dan kandungan yang sama dalam 24 jam, anda menerima respons pertama dan bukannya rekod pendua.

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

Tetapan → Webhook menghantar peristiwa (case.created, invoice.paid …) ke titik akhir HTTPS anda sebagai JSON. Setiap permintaan ditandatangani mengikut Standard Webhooks: sahkan webhook-signature dengan rahsia whsec_ titik akhir anda, tolak cap masa lama dan gunakan webhook-id untuk mengabaikan ulangan. Jawab dengan sebarang status 2xx; selainnya dicuba semula selama kira-kira 3½ hari.

// 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"