API di programmazione social media: una guida completa

Pubblicare immediatamente tramite un’API è semplice. La programmazione è dove stanno i problemi interessanti, perché un post programmato è una promessa sul futuro e il futuro contiene ora legale, interruzioni e post di cui cambi idea.

Fusi orari: passane uno esplicitamente

Il bug di programmazione più comune è un post che si sposta di un’ora due volte l’anno.

Un orario programmato ha bisogno di due cose: l’istante, come timestamp ISO-8601, e il fuso in cui è stato espresso, come nome IANA tipo America/New_York.

await bp.posts.create({
  content: 'Morning update.',
  channels: [{ channelId: 1, platform: 'linkedin' }],
  status: 'scheduled',
  scheduledAt: '2026-04-10T14:00:00Z',
  timezone: 'America/New_York',
});

Salvare solo un istante UTC va bene per un evento singolo. È sbagliato per qualsiasi cosa ricorrente, perché “ogni giorno feriale alle 9 del mattino locali” è un istante UTC diverso prima e dopo un cambio dell’ora legale. Il fuso è ciò che lo rende corretto.

Non salvare mai un offset grezzo come -05:00 come sostituto di un fuso. Gli offset cambiano; i fusi no.

Modella più di due stati

Un post non è solo programmato o pubblicato. Costruisci per almeno:

• draft, creato ma non messo in coda
• scheduled, in coda per un orario
• processing, inviato alla piattaforma, esito sconosciuto
• published, confermato in diretta
• failed, con un motivo
• partial, pubblicato su alcuni target e non su altri

I due che la gente dimentica sono processing e partial.

processing esiste perché diverse piattaforme accettano un post e lo pubblicano in modo asincrono. Un 200 non è una pubblicazione, e l’esito reale arriva più tardi.

partial esiste perché un post di solito ha come target diverse piattaforme. Se tre riescono e una fallisce, né “pubblicato” né “fallito” è vero, e forzarlo in uno dei due produce un’interfaccia che mente all’utente.

Cosa succede quando una piattaforma è offline

Progetta per questo, perché succede.

I fallimenti transitori dovrebbero riprovare con backoff. Una piattaforma che restituisce 503 per due minuti non dovrebbe perdere il post.

I retry devono essere sicuri. Una creazione andata in timeout potrebbe essere riuscita comunque. Riprovare alla cieca duplica il post, che è peggio del fallimento originale. Controlla prima di riprovare.

I fallimenti permanenti non dovrebbero riprovare affatto. Un token scaduto o una didascalia non valida non si risolveranno da soli, e riprovare brucia solo quota e ritarda la notifica.

Qualcuno deve essere avvisato. Un post programmato fallito alle 3 del mattino è silenzioso a meno che tu non l’abbia reso rumoroso. I webhook sono il meccanismo giusto.

Modificare e annullare

Un post programmato è una promessa che potresti dover infrangere. La tua integrazione dovrebbe supportare il cambio dell’orario, la modifica del contenuto, e l’annullamento totale.

Nota che le piattaforme differiscono su se permettano questo una volta che loro detengono il post, il che è uno dei motivi per cui programmare nel tuo stesso livello e inviare all’ultimo momento si comporta meglio che consegnare alla piattaforma un post datato nel futuro.

Slot di coda contro orari espliciti

Due modelli di programmazione, ed entrambi hanno un posto.

Gli orari espliciti sono ciò che vuoi quando un post deve atterrare in un momento preciso: un lancio, un evento, un annuncio coordinato.

Gli slot di coda sono ciò che vuoi per un flusso costante. Definisci un ritmo di pubblicazione e il prossimo post prende il prossimo slot libero, così non stai scegliendo timestamp per ogni post in un lotto.

Per il lavoro in blocco il secondo è molto meno tedioso, ed è il modello che rende “metti in coda trenta post” un’operazione sensata invece di trenta decisioni.

Programmazioni ricorrenti

Distinte da un post programmato. Una programmazione ricorrente è una regola che continua a produrre post su una frequenza: giornaliera, settimanale, bisettimanale o mensile.

Due cose da progettare. Il fuso conta ancora di più qui, per il motivo dell’ora legale sopra. E i media allegati a un post ricorrente devono essere mantenuti piuttosto che ripuliti dopo la pubblicazione, perché la programmazione ne avrà di nuovo bisogno la prossima volta.

Limiti del piano

La versione breve

Passa un fuso orario IANA insieme a ogni timestamp programmato, specialmente per qualsiasi cosa ricorrente. Modella processing e partial come stati reali, perché la pubblicazione asincrona e i post multi-piattaforma li rendono entrambi genuinamente possibili. Riprova i fallimenti transitori con backoff, non riprovare mai una creazione alla cieca, e usa i webhook così un fallimento alle 3 del mattino non è silenzioso.