Hubungkan sistem Anda ke Marcomm AI

1. 1
   Ajukan akses

   Jelaskan sistem Anda dan pilih data yang dibutuhkan. Kami meninjau setiap permohonan yang masuk.

2. 2
   Buat kunci

   Setelah disetujui, buat kunci di Pengaturan, API. Kunci hanya ditampilkan sekali, jadi simpan di sistem Anda.

3. 3
   Kirim permintaan

   Kirim kunci di header Authorization lalu panggil salah satu endpoint di bawah.

Contoh permintaan

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

Kirim kunci Anda sebagai token Bearer pada setiap permintaan. Kunci pribadi bertindak sebagai orang yang membuatnya, sehingga dapat membaca dan memutuskan persetujuan atas nama orang tersebut. Kunci ruang kerja dibuat oleh admin dan hanya dapat membaca. Kunci dapat kedaluwarsa, dibatasi ke alamat IP tertentu, dan dirotasi: kunci lama tetap berfungsi selama 24 jam setelah rotasi.

Kunci hanya membawa scope yang disetujui untuk aplikasi Anda.

news

Ringkasan berita, artikel, dan media.

crisis

Berita kritis dan insiden krisis.

approvals

Persetujuan yang tertunda, serta menyetujui atau menolaknya dengan kunci pribadi.

content

Membaca siaran pers dan artikel blog.

Path diawali /api/v1. Endpoint baca memakai GET dan menerima parameter query. Responsnya JSON dengan bentuk {"data": ...}.

Kirim {"decision": "approve"} atau {"decision": "reject", "comment": "..."} ke item. Penolakan memerlukan komentar. Keputusan mengikuti aturan yang sama dengan aplikasi dan Slack, dan dicatat atas nama pemilik kunci. Jika teks memuat frasa yang perlu dikonfirmasi, Anda menerima 409 confirmation_required beserta peringatannya, dan dapat mengirim ulang permintaan dengan "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."}'

Batas ditetapkan per ruang kerja, per menit, dan per hari (UTC). Respons menyertakan header di bawah. Jika melewati batas, Anda menerima 429 dengan Retry-After. Untuk menaikkan batas, ajukan permintaan di Pengaturan, API. Tim kami akan meninjaunya.

X-RateLimit-Limit

Permintaan yang diizinkan per menit.

X-RateLimit-Remaining

Sisa permintaan pada menit berjalan.

X-RateLimit-Reset

Waktu Unix saat jendela menit direset.

X-RateLimit-Day-Limit

Permintaan yang diizinkan per hari.

X-RateLimit-Day-Remaining

Sisa permintaan hari ini.

Retry-After

Detik yang perlu ditunggu sebelum mencoba lagi. Hanya pada 429.

Kesalahan mengembalikan JSON dengan bentuk {"error": {"code": ..., "message": ...}}.

Peringatan, permintaan persetujuan, dan ringkasan pagi juga dapat dikirim ke sistem Anda. Tambahkan tujuan di Pengaturan, API, Webhook. Setiap permintaan berupa JSON dengan kolom event (alert, approval, atau briefing), workspace, title, text, url, data, dan sentAt. Permintaan persetujuan membawa data.kind (press_release, blog, atau event) dan data.id, yang dapat Anda pakai untuk membaca dan memutuskan lewat API.

Permintaan ditandatangani. Hitung HMAC-SHA256 dari isi permintaan mentah dengan rahasia penandatanganan Anda, lalu bandingkan dengan header X-Marcomm-Signature yang berbentuk sha256=<hex>. Tolak permintaan yang tidak cocok.

Memverifikasi webhook di 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);
}