Połącz swoje systemy z Marcomm AI

1. 1
   Złóż wniosek o dostęp

   Opisz swój system i wybierz potrzebne dane. Wnioski są weryfikowane.

2. 2
   Utwórz klucz

   Po akceptacji utwórz klucz w Ustawienia > API. Klucz jest pokazywany tylko raz, więc zapisz go w swoim systemie.

3. 3
   Wyślij żądanie

   Wyślij klucz w nagłówku Authorization i wywołaj wybrany z poniższych endpointów.

Przykładowe żądanie

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

Wysyłaj klucz jako token Bearer w każdym żądaniu. Klucz osobisty działa jako osoba, która go utworzyła, więc może odczytywać akceptacje i podejmować decyzje w jej imieniu. Klucz przestrzeni roboczej tworzy administrator i służy tylko do odczytu. Klucze mogą wygasać, być ograniczone do adresów IP i być rotowane: po rotacji stary klucz działa jeszcze przez 24 godziny.

Każdy klucz ma tylko te zakresy, na które zatwierdzono Twoją aplikację.

news

Zestawienie wiadomości, artykuły i media.

crisis

Krytyczne wiadomości i incydenty kryzysowe.

approvals

Oczekujące akceptacje oraz ich akceptowanie lub odrzucanie kluczem osobistym.

content

Odczyt komunikatów prasowych i wpisów na blogu.

Ścieżki zaczynają się od /api/v1. Endpointy odczytu używają GET i przyjmują parametry zapytania. Odpowiedź to JSON w postaci {"data": ...}.

Wyślij {"decision": "approve"} lub {"decision": "reject", "comment": "..."} do danego elementu. Odrzucenie wymaga komentarza. Decyzja podlega tym samym zasadom co w aplikacji i w Slacku i jest zapisywana na właściciela klucza. Jeśli tekst zawiera sformułowania wymagające potwierdzenia, otrzymasz 409 confirmation_required z ostrzeżeniami i możesz wysłać żądanie ponownie z "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."}'

Limity są ustawiane dla przestrzeni roboczej, na minutę i na dobę (UTC). Odpowiedzi zawierają poniższe nagłówki. Po przekroczeniu limitu otrzymasz 429 z nagłówkiem Retry-After. Aby podnieść limit, złóż wniosek w Ustawienia > API. Nasz zespół go rozpatrzy.

X-RateLimit-Limit

Dozwolona liczba żądań na minutę.

X-RateLimit-Remaining

Pozostała liczba żądań w bieżącej minucie.

X-RateLimit-Reset

Czas Unix, w którym okno minutowe zostanie zresetowane.

X-RateLimit-Day-Limit

Dozwolona liczba żądań na dobę.

X-RateLimit-Day-Remaining

Pozostała liczba żądań na dziś.

Retry-After

Liczba sekund do ponowienia próby. Tylko przy 429.

Błędy są zwracane jako JSON w postaci {"error": {"code": ..., "message": ...}}.

Alerty, prośby o akceptację i poranny briefing mogą być też wysyłane do Twojego systemu. Dodaj miejsce docelowe w Ustawienia > API > Webhooki. Każde żądanie to JSON z polami event (alert, approval lub briefing), workspace, title, text, url, data i sentAt. Prośba o akceptację zawiera data.kind (press_release, blog lub event) oraz data.id, których możesz użyć do odczytu i decyzji przez API.

Każde żądanie jest podpisane. Oblicz HMAC-SHA256 z surowej treści żądania za pomocą swojego sekretu podpisu i porównaj wynik z nagłówkiem X-Marcomm-Signature w postaci sha256=<hex>. Odrzucaj żądania, które się nie zgadzają.

Weryfikacja webhooka w 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);
}