Pubblicazioni e programmazione

Ottieni una chiave API

Una pubblicazione appartiene a un'attività e va a una o più reti, le sue destinazioni (targets). Ogni destinazione ha il proprio testo, i propri media, il proprio formato e il proprio stato.

Endpoint

POST/v1/postsGET/v1/postsGET/v1/posts/{id}PATCH/v1/posts/{id}DELETE/v1/posts/{id}

Il body di una pubblicazione

Campo	Significato
`establishmentId`	L'attività che pubblica (`GET /v1/establishments`)
`targets[]`	Una voce per rete: `platform`, `text`, e facoltativi `media`, `format` e `accountId`
`targets[].media[]`	Un media della mediateca tramite `id`, o un `url` https pubblico con il suo `type` (`image` o `video`)
`targets[].accountId`	L'account da usare quando l'attività ne ha più di uno su quella rete
`scheduledAt`	Una data e ora ISO 8601 futura; se assente, la pubblicazione parte subito
`status`	`draft` per salvare una bozza che non parte (senza `scheduledAt` in quel caso)

Stati

Stato	Significato
`draft`	Salvata, non parte
`scheduled`	Partirà a `scheduledAt`
`publishing`	In invio alla rete
`published`	Online, con il suo `permalink`
`failed`	La rete l'ha rifiutata; `error` dice perché
`sent_to_inbox`	Inviata all'app della rete, dove il titolare la completa (TikTok)

Lo status della pubblicazione riassume le sue destinazioni. È partial quando una rete ha pubblicato e un'altra è fallita.

Modificare prima della partenza

PATCH /v1/posts/{id} riscrive le destinazioni, sposta scheduledAt o cambia status: draft toglie l'orario e mantiene il contenuto, scheduled la riprogramma. Una volta che una rete ha inviato la pubblicazione, risponde 409 post_not_editable.

bash

curl -X PATCH https://api.sofia-post.com/api/v1/posts/$POST_ID \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":"scheduled","scheduledAt":"2026-11-20T09:00:00Z"}'

Eliminare

DELETE /v1/posts/{id} risponde 204. Mentre una rete sta inviando la pubblicazione, risponde 409 post_in_flight: riprova un momento dopo.

Elencare le pubblicazioni

GET /v1/posts elenca tutte le pubblicazioni raggiungibili dal token, dalla più recente, filtrate per establishmentId, status, from, to e createdBy (me o app). Una pubblicazione corrisponde a status quando almeno una delle sue reti è in quello stato. Vedi la paginazione.