Panoramica dell'API

URL di base https://api.sofia-post.com/api · Documento OpenAPI

Sofia API dà al tuo codice accesso al tuo account Sofia: le attività dei tuoi Workspace, le loro reti collegate, la loro libreria media, i loro post e le loro statistiche. È un’API REST su HTTPS; richieste e risposte sono in JSON. Permette di:

• Pubblicare: subito, a una data o come bozza, su una o più reti alla volta.
• Verificare prima di pubblicare: una simulazione ti dice se ogni rete accetterebbe il post, senza scrivere nulla.
• Gestire i media: carica un file o importalo da un URL nella libreria media di un’attività.
• Seguire i post: leggi lo stato di ogni rete, il suo permalink o il motivo del fallimento. Un webhook firmato può anche avvisarti.
• Leggere le statistiche: gli ultimi numeri raccolti da Sofia per ogni account collegato.
• Collegare le reti: crea un link ospitato che permette al titolare di collegare una rete mancante.

SDK e integrazioni

• CLI `sofia`: la CLI, pubblicata su npm con il nome sofia-post, per controllare Sofia da un terminale.
• Server MCP: collega Sofia ai tuoi agenti IA.
• Zapier: l’integrazione Sofia si collega con la tua chiave personale. Offre i trigger «Post Published» e «Post Failed», l’azione «Create Post» (pubblicare, programmare o salvare una bozza) e la ricerca «Find Post». Non è ancora stata sottoposta alla directory pubblica di Zapier.

Autenticazione

Ogni chiamata porta un token Bearer nell’header Authorization. Sofia rilegge i diritti collegati a ogni chiamata: una persona rimossa da un Workspace, o un’autorizzazione revocata, ferma il token dalla richiesta successiva.

Ci sono due modi per autenticarti:

Chiave API

Se automatizzi il tuo Workspace, basta una chiave personale. Nell’app Sofia apri Impostazioni › API, scheda Accesso personale, e crea una chiave. Scegli il suo nome, la sua scadenza e i suoi permessi. La chiave viene mostrata una sola volta: copiala e conservala in un vault di segreti, mai nel tuo codice.

Crea una chiave in Impostazioni › API › Accesso personale. Agisce per te su tutti i tuoi Workspace: l’attività che indichi determina il Workspace, e il tuo ruolo al suo interno decide cosa la chiave può fare.

Invia la chiave nell’header Authorization, come token Bearer:

curl https://api.sofia-post.com/api/v1/establishments \
  -H "Authorization: Bearer sofia_pk_live_…"

`GET /v1/me` ti indica per chi agisce la chiave, i suoi Workspace e i suoi permessi.

Una chiamata senza il permesso (lo scope) richiesto risponde 403 insufficient_scope.

Token OAuth2

Per un prodotto SaaS che agisce per i suoi utenti sui loro Workspace, registra un client OAuth: ogni persona autorizza la tua applicazione sul Workspace che sceglie. I token di accesso OAuth iniziano con sofia_live_at_…, durano un’ora e si usano allo stesso modo:

curl https://api.sofia-post.com/api/v1/establishments \
  -H "Authorization: Bearer sofia_live_at_…"

Crei un’app a cui si collegano altri account Sofia? Il suo flusso authorization code con PKCE, le sue client credentials e i suoi scope sono descritti in OAuth2.

URL di base

Ogni endpoint si trova sotto un unico URL di base:

https://api.sofia-post.com/api/v1

Limiti di frequenza

Sofia API conta le richieste su tre finestre: 15 minuti, 24 ore e 30 giorni.

Header

Ogni risposta ti dice cosa resta, nel formato IETF:

RateLimit: "15m";r=144;t=43, "24h";r=994;t=13543, "30d";r=9994;t=13543
RateLimit-Policy: "15m";q=150;w=900, "24h";q=1000;w=86400, "30d";q=10000;w=2592000

r è il numero di richieste rimanenti, t i secondi prima del reset della finestra, q la quota e w la finestra in secondi.

Quando una finestra è piena

La risposta è 429 rate_limit_exceeded, con un header Retry-After e la finestra esaurita in details. Aspetta questo intervallo prima di riprovare.

Usare l’API in modo efficiente

• Registra un webhook invece di interrogare un post in continuazione.
• Usa limit fino a 100 per leggere le liste con meno pagine.
• Metti in cache ciò che cambia raramente: piattaforme, attività, account collegati.

Errori

Ogni errore risponde con uno stato HTTP e la stessa busta JSON. code è il contratto che legge il tuo codice; message è scritto per una persona e può cambiare.

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": [
      { "field": "targets[0].text", "code": "required", "message": "targets[0].text is required" }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#invalid_request",
    "requestId": "2aab5943-6333-4caf-8478-25a85ebd4abf"
  }
}

• details dice di più: il campo rifiutato, il motivo di una rete, la finestra di limite esaurita.
• docUrl porta alla spiegazione del codice in questa pagina.
• requestId identifica la richiesta: comunicalo all’assistenza.

Codici di errore

Motivi di un post rifiutato

Un post_refused elenca ogni motivo in details[].code:

Gestire gli errori

• Basa la tua logica su code, mai su message.
• Riprova un 429 dopo Retry-After, e un 5xx con un backoff esponenziale.
• Non riprovare mai un 4xx identico: correggi prima la richiesta.
• Registra requestId a ogni fallimento.

Paginazione

Le liste (GET /v1/posts, GET /v1/media) arrivano dalle più recenti, una pagina alla volta. limit fissa la dimensione della pagina, da 1 a 100 (20 per impostazione predefinita).

{
  "data": [ … ],
  "nextCursor": "WyIyMDI2LTEwLTI3VDE1OjExOjU5LjAxN1oiLCIx…"
}

Passa nextCursor come cursor per leggere la pagina successiva. Quando nextCursor è assente, sei arrivato alla fine.

let cursor;
do {
  const url = new URL('https://api.sofia-post.com/api/v1/posts');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);
  const page = await globalThis.fetch(url, { headers: { Authorization: `Bearer ${key}` } }).then((r) => r.json());
  handle(page.data);
  cursor = page.nextCursor;
} while (cursor);

Un cursore è opaco: non costruirlo né modificarlo mai. Un cursore che Sofia non ha restituito risponde 400 invalid_cursor.

Idempotenza

Un errore di rete può lasciarti nel dubbio sulla creazione di un post. Invia un header Idempotency-Key con POST /v1/posts e POST /v1/media, e riprova con la stessa chiave: Sofia risponde ciò che ha risposto la prima volta e non crea duplicati.

curl -X POST https://api.sofia-post.com/api/v1/posts \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d @post.json

• Usa una nuova chiave casuale (un UUID) per ogni nuovo post, e la stessa chiave per ogni nuovo tentativo di quel post.
• La stessa chiave con un corpo diverso risponde 422 idempotency_key_reused.
• Finché la prima richiesta è in corso, la stessa chiave risponde 409 idempotency_in_progress: riprova poco dopo.

Modalità test e simulazione

Simulazione. Aggiungi ?dry_run=true a POST /v1/posts: Sofia esegue i controlli di un vero post (le regole di ogni rete, l’account collegato, i media, la data e il tuo piano) senza salvare né inviare nulla. Il dettaglio delle risposte è nella pagina Pubblicare.

Modalità test. Un’applicazione creata in modalità test (token sofia_test_at_…) legge il tuo vero Workspace ma non vi scrive mai: i suoi post sono simulati e valutati con le stesse regole, e ogni scrittura reale risponde 403 live_mode_required. Le chiavi e i client creati in Impostazioni › API sono in modalità live; usa la simulazione per verificare senza pubblicare.