Kết nối hệ thống của bạn với Marcomm AI

1. 1
   Đăng ký quyền truy cập

   Mô tả hệ thống của bạn và chọn dữ liệu cần dùng. Chúng tôi xem xét từng đơn đăng ký.

2. 2
   Tạo khóa

   Sau khi được duyệt, hãy tạo khóa tại Cài đặt, API. Khóa chỉ hiển thị một lần, vì vậy hãy lưu vào hệ thống của bạn.

3. 3
   Gửi yêu cầu

   Gửi khóa trong header Authorization rồi gọi bất kỳ endpoint nào bên dưới.

Yêu cầu mẫu

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

Gửi khóa dưới dạng token Bearer trong mỗi yêu cầu. Khóa cá nhân hoạt động với tư cách người tạo ra nó, nên có thể đọc và quyết định các mục phê duyệt nhân danh người đó. Khóa không gian làm việc do quản trị viên tạo và chỉ có quyền đọc. Khóa có thể hết hạn, giới hạn theo địa chỉ IP và xoay vòng: sau khi xoay vòng, khóa cũ vẫn dùng được thêm 24 giờ.

Mỗi khóa chỉ mang các phạm vi mà đơn đăng ký của bạn được duyệt.

news

Bản tin tổng hợp, bài viết và cơ quan báo chí.

crisis

Tin nghiêm trọng và sự cố khủng hoảng.

approvals

Các mục chờ phê duyệt, cùng việc phê duyệt hoặc từ chối chúng bằng khóa cá nhân.

content

Đọc thông cáo báo chí và bài blog.

Đường dẫn bắt đầu bằng /api/v1. Endpoint đọc dùng GET và nhận tham số truy vấn. Phản hồi là JSON có dạng {"data": ...}.

Gửi {"decision": "approve"} hoặc {"decision": "reject", "comment": "..."} tới mục cần xử lý. Từ chối cần có nhận xét. Quyết định tuân theo cùng quy tắc như trong ứng dụng và Slack, và được ghi nhận dưới tên chủ khóa. Khi nội dung có cụm từ cần xác nhận, bạn sẽ nhận 409 confirmation_required kèm các cảnh báo, và có thể gửi lại yêu cầu với "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."}'

Giới hạn được đặt theo từng không gian làm việc, theo phút và theo ngày (UTC). Các phản hồi đều kèm các header bên dưới. Khi vượt giới hạn, bạn nhận 429 cùng Retry-After. Để tăng giới hạn, hãy gửi yêu cầu tại Cài đặt, API. Đội ngũ của chúng tôi sẽ xem xét.

X-RateLimit-Limit

Số yêu cầu được phép mỗi phút.

X-RateLimit-Remaining

Số yêu cầu còn lại trong phút hiện tại.

X-RateLimit-Reset

Thời điểm Unix khi cửa sổ phút được đặt lại.

X-RateLimit-Day-Limit

Số yêu cầu được phép mỗi ngày.

X-RateLimit-Day-Remaining

Số yêu cầu còn lại trong hôm nay.

Retry-After

Số giây cần chờ trước khi thử lại. Chỉ có với 429.

Lỗi được trả về dưới dạng JSON có dạng {"error": {"code": ..., "message": ...}}.

Cảnh báo, yêu cầu phê duyệt và bản tin buổi sáng cũng có thể được đẩy tới hệ thống của bạn. Thêm đích nhận tại Cài đặt, API, Webhook. Mỗi yêu cầu là JSON với các trường event (alert, approval hoặc briefing), workspace, title, text, url, data và sentAt. Yêu cầu phê duyệt mang data.kind (press_release, blog hoặc event) và data.id, dùng để đọc và quyết định qua API.

Các yêu cầu đều được ký. Hãy tính HMAC-SHA256 của nội dung thô của yêu cầu bằng khóa bí mật ký của bạn rồi so sánh với header X-Marcomm-Signature có dạng sha256=<hex>. Từ chối những yêu cầu không khớp.

Xác minh Webhook trong Node.js

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);
}