Koppel uw systemen aan Marcomm AI

1. 1
   Toegang aanvragen

   Beschrijf uw systeem en kies de gegevens die u nodig hebt. Elke aanvraag wordt beoordeeld.

2. 2
   Een sleutel aanmaken

   Maak na goedkeuring een sleutel aan via Instellingen > API. De sleutel wordt maar één keer getoond, dus bewaar hem in uw systeem.

3. 3
   Een verzoek versturen

   Stuur de sleutel mee in de Authorization-header en roep een van de onderstaande endpoints aan.

Voorbeeldverzoek

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

Stuur uw sleutel bij elk verzoek mee als Bearer-token. Een persoonlijke sleutel treedt op als de persoon die hem heeft aangemaakt, dus hij kan goedkeuringen lezen en beslissen namens die persoon. Een werkruimtesleutel wordt door een beheerder aangemaakt en kan alleen lezen. Sleutels kunnen verlopen, worden beperkt tot IP-adressen en worden geroteerd: na een rotatie blijft de oude sleutel nog 24 uur werken.

Elke sleutel heeft alleen de scopes waarvoor uw toepassing is goedgekeurd.

news

Nieuwsoverzicht, artikelen en media.

crisis

Kritiek nieuws en crisisincidenten.

approvals

Openstaande goedkeuringen, en deze goed- of afkeuren met een persoonlijke sleutel.

content

Persberichten en blogberichten lezen.

Paden beginnen met /api/v1. Leesendpoints gebruiken GET en accepteren queryparameters. Een antwoord is JSON in de vorm {"data": ...}.

Stuur {"decision": "approve"} of {"decision": "reject", "comment": "..."} naar het item. Bij afkeuren is een opmerking verplicht. De beslissing volgt dezelfde regels als in de app en Slack en wordt vastgelegd onder de sleuteleigenaar. Bevat de tekst formuleringen die bevestiging vereisen, dan ontvangt u 409 confirmation_required met de waarschuwingen en kunt u het verzoek opnieuw versturen met "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."}'

Limieten gelden per werkruimte, per minuut en per dag (UTC). Antwoorden bevatten de onderstaande headers. Boven de limiet ontvangt u 429 met Retry-After. Vraag een verhoging aan via Instellingen > API als u een limiet wilt verhogen. Ons team beoordeelt de aanvraag.

X-RateLimit-Limit

Toegestane verzoeken per minuut.

X-RateLimit-Remaining

Resterende verzoeken in de huidige minuut.

X-RateLimit-Reset

Unix-tijd waarop het minuutvenster wordt gereset.

X-RateLimit-Day-Limit

Toegestane verzoeken per dag.

X-RateLimit-Day-Remaining

Resterende verzoeken vandaag.

Retry-After

Seconden wachten voordat u het opnieuw probeert. Alleen bij 429.

Fouten worden teruggegeven als JSON in de vorm {"error": {"code": ..., "message": ...}}.

Meldingen, goedkeuringsverzoeken en de ochtendbriefing kunnen ook naar uw systeem worden gepusht. Voeg een bestemming toe via Instellingen > API > Webhooks. Elk verzoek is JSON met de velden event (alert, approval of briefing), workspace, title, text, url, data en sentAt. Een goedkeuringsverzoek bevat data.kind (press_release, blog of event) en data.id, waarmee u via de API kunt lezen en beslissen.

Elk verzoek is ondertekend. Bereken de HMAC-SHA256 van de ruwe verzoekbody met uw ondertekeningsgeheim en vergelijk die met de X-Marcomm-Signature-header, in de vorm sha256=<hex>. Weiger verzoeken die niet overeenkomen.

Een webhook verifiëren in 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);
}