Verbinden Sie Ihre Systeme mit Marcomm AI

1. 1
   Zugang beantragen

   Beschreiben Sie Ihr System und wählen Sie die benötigten Daten. Wir prüfen die Anträge.

2. 2
   Schlüssel erstellen

   Nach der Freigabe erstellen Sie unter Einstellungen, API einen Schlüssel. Er wird nur einmal angezeigt, speichern Sie ihn daher in Ihrem System.

3. 3
   Anfrage senden

   Senden Sie den Schlüssel im Authorization-Header und rufen Sie einen der unten aufgeführten Endpunkte auf.

Beispielanfrage

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

Senden Sie Ihren Schlüssel bei jeder Anfrage als Bearer-Token. Ein persönlicher Schlüssel handelt als die Person, die ihn erstellt hat, und kann daher in deren Namen Freigaben lesen und entscheiden. Ein Workspace-Schlüssel wird von einem Admin erstellt und kann nur lesen. Schlüssel können ablaufen, auf IP-Adressen beschränkt und rotiert werden: Der alte Schlüssel funktioniert nach einer Rotation noch 24 Stunden.

Ein Schlüssel enthält nur die Scopes, für die Ihr Antrag genehmigt wurde.

news

Nachrichtenübersicht, Artikel und Medien.

crisis

Kritische Meldungen und Krisenvorfälle.

approvals

Offene Freigaben sowie deren Genehmigung oder Ablehnung mit einem persönlichen Schlüssel.

content

Pressemitteilungen und Blogbeiträge lesen.

Die Pfade beginnen mit /api/v1. Lesende Endpunkte nutzen GET und nehmen Query-Parameter entgegen. Die Antwort ist JSON in der Form {"data": ...}.

Senden Sie {"decision": "approve"} oder {"decision": "reject", "comment": "..."} an das Element. Für eine Ablehnung ist ein Kommentar nötig. Die Entscheidung folgt denselben Regeln wie in der App und in Slack und wird unter dem Schlüsselinhaber erfasst. Enthält der Text Formulierungen, die bestätigt werden müssen, erhalten Sie 409 confirmation_required mit den Warnungen und können die Anfrage mit "force": true erneut senden.

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."}'

Die Limits gelten pro Workspace, pro Minute und pro Tag (UTC). Die Antworten enthalten die folgenden Header. Bei Überschreitung erhalten Sie 429 mit Retry-After. Für ein höheres Limit stellen Sie unter Einstellungen, API eine Anfrage. Unser Team prüft sie.

X-RateLimit-Limit

Anfragen pro Minute.

X-RateLimit-Remaining

Verbleibende Anfragen in der aktuellen Minute.

X-RateLimit-Reset

Unix-Zeitpunkt, zu dem das Minutenfenster zurückgesetzt wird.

X-RateLimit-Day-Limit

Anfragen pro Tag.

X-RateLimit-Day-Remaining

Verbleibende Anfragen heute.

Retry-After

Sekunden bis zum nächsten Versuch. Nur bei 429.

Fehler werden als JSON in der Form {"error": {"code": ..., "message": ...}} zurückgegeben.

Warnungen, Freigabeanfragen und das Morgenbriefing können auch an Ihr System gesendet werden. Fügen Sie ein Ziel unter Einstellungen, API, Webhooks hinzu. Jede Anfrage ist JSON mit den Feldern event (alert, approval oder briefing), workspace, title, text, url, data und sentAt. Eine Freigabeanfrage enthält data.kind (press_release, blog oder event) und data.id, mit denen Sie über die API lesen und entscheiden können.

Anfragen sind signiert. Berechnen Sie den HMAC-SHA256 des rohen Anfragetexts mit Ihrem Signaturgeheimnis und vergleichen Sie ihn mit dem Header X-Marcomm-Signature im Format sha256=<hex>. Weisen Sie Anfragen ab, die nicht übereinstimmen.

Webhook in Node.js prüfen

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