Sambungkan sistem anda ke Marcomm AI

1. 1
   Mohon akses

   Huraikan sistem anda dan pilih data yang diperlukan. Setiap permohonan disemak sebelum diluluskan.

2. 2
   Cipta kunci

   Selepas diluluskan, cipta kunci di Tetapan > API. Kunci hanya dipaparkan sekali, jadi simpan dalam sistem anda.

3. 3
   Hantar permintaan

   Hantar kunci dalam pengepala Authorization dan panggil salah satu titik akhir di bawah.

Contoh permintaan

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

Hantar kunci anda sebagai token Bearer bersama setiap permintaan. Kunci peribadi bertindak sebagai orang yang mencipta kunci itu, jadi ia boleh membaca dan memutuskan kelulusan atas nama orang tersebut. Kunci ruang kerja dicipta oleh pentadbir dan hanya boleh membaca. Kunci boleh dibuat tamat tempoh, dihadkan kepada alamat IP tertentu dan diputar: kunci lama terus berfungsi selama 24 jam selepas diputar.

Setiap kunci hanya membawa skop yang diluluskan untuk aplikasi anda.

news

Ringkasan berita, artikel dan media.

crisis

Berita kritikal dan insiden krisis.

approvals

Kelulusan yang menunggu, serta meluluskan atau menolaknya dengan kunci peribadi.

content

Membaca siaran media dan catatan blog.

Laluan bermula dengan /api/v1. Titik akhir bacaan menggunakan GET dan menerima parameter pertanyaan. Respons ialah JSON dalam bentuk {"data": ...}.

Hantar {"decision": "approve"} atau {"decision": "reject", "comment": "..."} kepada item itu. Penolakan memerlukan komen. Keputusan mengikut peraturan yang sama seperti dalam aplikasi dan Slack, dan direkodkan atas nama pemilik kunci. Jika teks mengandungi frasa yang memerlukan pengesahan, anda menerima 409 confirmation_required bersama amaran, dan anda boleh menghantar semula 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."}'

Had ditetapkan bagi setiap ruang kerja, setiap minit dan setiap hari (UTC). Respons membawa pengepala di bawah. Apabila had dilepasi, anda menerima 429 dengan Retry-After. Untuk menaikkan had, mohon peningkatan di Tetapan > API. Pasukan kami akan menyemaknya.

X-RateLimit-Limit

Permintaan dibenarkan seminit.

X-RateLimit-Remaining

Permintaan yang berbaki dalam minit semasa.

X-RateLimit-Reset

Masa Unix apabila tetingkap minit ditetapkan semula.

X-RateLimit-Day-Limit

Permintaan dibenarkan sehari.

X-RateLimit-Day-Remaining

Permintaan yang berbaki hari ini.

Retry-After

Saat untuk menunggu sebelum mencuba semula. Hanya pada 429.

Ralat dikembalikan sebagai JSON dalam bentuk {"error": {"code": ..., "message": ...}}.

Makluman, permintaan kelulusan dan taklimat pagi juga boleh dihantar terus ke sistem anda. Tambah destinasi di Tetapan > API > Webhook. Setiap permintaan ialah JSON dengan medan event (alert, approval atau briefing), workspace, title, text, url, data dan sentAt. Permintaan kelulusan membawa data.kind (press_release, blog atau event) dan data.id, yang boleh anda gunakan untuk membaca dan memutuskan melalui API.

Setiap permintaan ditandatangani. Kira HMAC-SHA256 bagi badan permintaan mentah dengan rahsia tandatangan anda dan bandingkan dengan pengepala X-Marcomm-Signature, yang berbentuk sha256=<hex>. Tolak permintaan yang tidak sepadan.

Mengesahkan webhook dalam 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);
}