Collega i tuoi sistemi a Marcomm AI

1. 1
   Richiedi l’accesso

   Descrivi il tuo sistema e scegli i dati che ti servono. Esaminiamo le richieste.

2. 2
   Crea una chiave

   Dopo l’approvazione, crea una chiave in Impostazioni, API. La chiave viene mostrata una sola volta, quindi salvala nel tuo sistema.

3. 3
   Invia una richiesta

   Invia la chiave nell’intestazione Authorization e chiama uno degli endpoint qui sotto.

Richiesta di esempio

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

Invia la chiave come token Bearer a ogni richiesta. Una chiave personale agisce come la persona che l’ha creata, quindi può leggere e decidere le approvazioni a suo nome. Una chiave dello spazio di lavoro viene creata da un amministratore e può solo leggere. Le chiavi possono scadere, essere limitate a indirizzi IP ed essere ruotate: la vecchia chiave continua a funzionare per 24 ore dopo la rotazione.

Una chiave porta solo gli scope per cui la tua richiesta è stata approvata.

news

Riepilogo notizie, articoli e testate.

crisis

Notizie critiche e incidenti di crisi.

approvals

Approvazioni in sospeso, con approvazione o rifiuto tramite una chiave personale.

content

Lettura di comunicati stampa e articoli del blog.

I percorsi iniziano con /api/v1. Gli endpoint di lettura usano GET e accettano parametri di query. La risposta è JSON nella forma {"data": ...}.

Invia {"decision": "approve"} oppure {"decision": "reject", "comment": "..."} all’elemento. Per rifiutare serve un commento. La decisione segue le stesse regole dell’app e di Slack ed è registrata a nome del titolare della chiave. Se il testo contiene frasi che richiedono conferma, ricevi 409 confirmation_required con gli avvisi e puoi inviare di nuovo la richiesta con "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."}'

I limiti sono impostati per spazio di lavoro, al minuto e al giorno (UTC). Le risposte includono le intestazioni qui sotto. Superato un limite ricevi 429 con Retry-After. Per aumentare un limite, invia una richiesta in Impostazioni, API. Il nostro team la valuta.

X-RateLimit-Limit

Richieste consentite al minuto.

X-RateLimit-Remaining

Richieste rimaste nel minuto corrente.

X-RateLimit-Reset

Ora Unix in cui la finestra di un minuto si azzera.

X-RateLimit-Day-Limit

Richieste consentite al giorno.

X-RateLimit-Day-Remaining

Richieste rimaste oggi.

Retry-After

Secondi da attendere prima di riprovare. Solo con 429.

Gli errori restituiscono JSON nella forma {"error": {"code": ..., "message": ...}}.

Avvisi, richieste di approvazione e briefing del mattino possono essere inviati anche al tuo sistema. Aggiungi una destinazione in Impostazioni, API, Webhook. Ogni richiesta è JSON con i campi event (alert, approval o briefing), workspace, title, text, url, data e sentAt. Una richiesta di approvazione contiene data.kind (press_release, blog o event) e data.id, che puoi usare per leggere e decidere tramite l’API.

Le richieste sono firmate. Calcola l’HMAC-SHA256 del corpo grezzo della richiesta con il tuo segreto di firma e confrontalo con l’intestazione X-Marcomm-Signature, nella forma sha256=<hex>. Rifiuta le richieste che non corrispondono.

Verificare un webhook 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);
}