Programma i post sui social con un’API REST

La sequenza completa

Per programmare un post tramite Mellow Hub, verifica cosa può fare la credenziale, seleziona i canali collegati, valida una richiesta e poi creala con una chiave di idempotenza stabile. Quindi rileggi il post risultante per stabilire cosa è successo su ogni destinazione. Una risposta di creazione positiva non prova che ogni social lo abbia pubblicato.

Questa ricetta usa REST. Un client MCP segue la sequenza equivalente whoami → list_channels → validate_post → create_post → get_post descritta nella guida MCP per i social.

Prova il controllo dell’input con un esempio pronto da eseguire

Scarica lo script di controllo dell’input per Node.js e il template post.example.json nella stessa cartella. Lo script richiede Node.js 22 o successivo e non ha bisogno di pacchetti. Leggine il codice sorgente, poi fornisci una credenziale di Hub esistente come MELLOW_HUB_KEY, tramite le tue variabili d’ambiente segrete.

Per questo controllo bastano channels:read e posts:read. Nelle impostazioni di accesso di Hub scegli solo i canali che intendi usare. Per elencare i canali basta il primo permesso. Per questo controllo dell’input non servono permessi di pubblicazione né un abbonamento.

node mellow-hub-check.mjs --channels
# Sostituisci gli ID dei canali e l'URL dei media in post.example.json.
node mellow-hub-check.mjs post.example.json

Lo script controlla i canali disponibili per la credenziale, invia il JSON che hai modificato all’endpoint di validazione autenticato di Mellow Hub e stampa i problemi bloccanti e le note. Esce con 0 se quei controlli dell’input vengono superati, con 1 se ci sono problemi nell’input, o con 2 in caso di errore di file, di permessi, di connessione o di risposta inattesa. Un HTTP 200 con ok: false fa comunque fallire il controllo.

Non crea alcun post, non scarica media e non invia richieste a nessun social. Superare questo controllo non verifica la durata del file, le proporzioni, l’autorizzazione finale dell’account né la pubblicazione. Il codice scaricabile è testato con fixture isolate; non si tratta della registrazione di una pubblicazione reale di un cliente. Per le richieste curl qui sotto, salva il file modificato come post.json.

1. Controlla l’account e la credenziale

Collega i tuoi canali in Hub e crea una credenziale con i canali e la modalità che intendi delegare. Conservala come MELLOW_HUB_KEY tra le variabili d’ambiente segrete del tuo server; non inserirla mai nel JavaScript del frontend né in un repository pubblico. Gli esempi leggono quella variabile d’ambiente senza mostrarne il valore.

curl --fail-with-body https://www.mellow.world/api/hub/v1/whoami \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

curl --fail-with-body https://www.mellow.world/api/hub/v1/channels \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

Usa gli ID dei canali restituiti per questo account. I valori spc_… qui sotto sono segnaposto. Prima di creare qualsiasi cosa, controlla la modalità e la quota disponibile. Una credenziale in modalità revisione prepara un post che una persona dovrà approvare. Una credenziale in pilota automatico può agire entro l’ambito, il tetto e la scadenza che le sono stati delegati.

2. Descrivi il post reale

Salva la struttura seguente come post.json. Sostituisci entrambi gli ID dei canali, l’indirizzo del file multimediale di esempio, il testo e la data di esempio. Usa un offset di fuso orario ISO 8601 esplicito o una Z UTC; il timestamp rappresenta un istante, non l’ora locale di chi legge. La data del 2030 nell’esempio è volutamente illustrativa.

{
  "caption": "A short look at how this piece was made.",
  "channels": [
    "spc_your_instagram_channel",
    "spc_your_youtube_channel"
  ],
  "media": [
    "https://cdn.example.com/your-video.mp4"
  ],
  "scheduledAt": "2030-01-15T10:00:00Z",
  "options": {
    "instagram": {
      "placement": "reels"
    },
    "youtube": {
      "title": "How this piece was made",
      "privacyStatus": "public"
    }
  }
}

Il social scarica i media al momento della pubblicazione, quindi in quel momento l’URL HTTPS reale deve essere ancora raggiungibile. Un file locale privato o un URL firmato scaduto non funzioneranno. Questo esempio assegna a YouTube un titolo a parte e seleziona per Instagram il posizionamento Reels. La disponibilità dei formati dipende comunque dagli account collegati e dal provider.

3. Valida senza pubblicare

curl --fail-with-body https://www.mellow.world/api/hub/v1/validate \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @post.json

Controlla ok, issues e notes nella risposta. Correggi ogni problema bloccante prima di proseguire. La validazione può restituire HTTP 200 con ok: false, quindi controllare solo lo stato HTTP non basta. L’endpoint autenticato verifica che i canali siano davvero tuoi, oltre alle regole di input.

Per un’anteprima senza account dei controlli su didascalia, titolo e numero di file, usa il verificatore di post gratuito. Nessuna delle due anteprime misura la durata o le proporzioni del tuo file reale, e un provider può comunque rifiutare la consegna.

4. Crea una volta, riprova in modo coerente

La credenziale in sola lettura del controllo iniziale non può creare post. Prima di questo passaggio, usa una connessione con posts:write e posts:publish per i canali previsti. Questi permessi servono anche in modalità revisione, che comunque lascia la decisione di pubblicare a una persona. Senza di essi la richiesta restituisce un errore di permessi.

La richiesta seguente crea il post. Eseguila solo quando il contenuto e l’autorizzazione sulle destinazioni sono corretti. In modalità revisione il post attende l’approvazione; in pilota automatico l’azione delegata può procedere all’orario programmato.

curl --fail-with-body https://www.mellow.world/api/hub/v1/posts \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: studio-process-video-slot-001" \
  --data-binary @post.json

Salva la chiave di idempotenza insieme al job nella tua applicazione. Se la risposta va persa, ripeti la stessa richiesta con la stessa chiave. Non creare una chiave nuova solo perché c’è stato un timeout. Un post diverso richiede una chiave diversa; se ne riutilizzi una con un contenuto modificato, la richiesta viene rifiutata.

5. Leggi il risultato per ogni destinazione

Salva il post.id restituito e recupera il post con GET /api/hub/v1/posts/{id}, usando lo stesso header di autorizzazione. Ispeziona ogni voce in targets e il relativo URL pubblico. Un post su più social può avere un esito parziale: una destinazione può riuscire mentre un’altra fallisce.

Conserva insieme, nel tuo record del job, l’orario previsto, l’ID del post di Hub, la chiave di idempotenza e gli esiti delle destinazioni. Evita di scrivere nei log le credenziali o gli header di autorizzazione completi. Quando una destinazione fallisce, usa l’errore segnalato per decidere il passo successivo, invece di ricreare alla cieca l’intero post.

Recupera un post andato in timeout o pubblicato solo in parte

Un timeout significa che chi ha fatto la chiamata non conosce l’esito. Un risultato partial significa che Hub ha registrato esiti diversi per le destinazioni selezionate. Tieni distinti i due casi quando decidi cosa inviare dopo.

La risposta di creazione è andata persa

Salva il payload originale e la chiave di idempotenza nel record del job prima di inviare la prima richiesta. Ripeti quella richiesta, senza modifiche, con la stessa chiave e un’autorizzazione valida. Se Hub ha già il post, restituisce il suo ID e il suo stato attuale. La risposta REST è comunque HTTP 201, quindi un 201 da solo non ti dice se questo tentativo ha creato un nuovo record. Una volta ottenuto l’ID, usa GET per seguirne lo stato.

Se ricevi 409 idempotency_key_reused, confronta la richiesta con il job salvato. Non generare automaticamente un’altra chiave per aggirare l’errore: descriverebbe un’operazione nuova e potrebbe duplicare la pubblicazione originale.

Una destinazione è fallita dopo che un’altra ha pubblicato

Leggi targets prima di preparare un recupero. Per esempio, se Instagram è published e YouTube è failed, correggi il problema segnalato per YouTube e valida un nuovo payload che contenga solo quel canale YouTube. Un recupero intenzionale usa una chiave nuova, come studio-process-video-slot-001-youtube-recovery-1. Conserva il suo nuovo ID del post insieme al job originale. Si applicano comunque i soliti permessi dei canali, la modalità revisione e la quota di pubblicazioni.

Ripetere la richiesta con la chiave originale restituisce il post esistente; non fa ripartire le destinazioni fallite. Una destinazione ancora in attesa o in pubblicazione non è un errore confermato. Non reinviarla solo perché chi ha fatto la chiamata ha smesso di aspettare, e non includere nella richiesta di recupero le destinazioni che hanno già pubblicato.

Domande che emergono nelle integrazioni reali

Posso usare una didascalia diversa su un social?

Sì. Una voce di perChannel con l’ID reale del canale come chiave sostituisce la didascalia o i media di quel canale. I campi che valgono per tutta la piattaforma vanno in options. Consulta gli esempi svolti nel riferimento di Hub.

Un agente può collegare da solo i miei account social?

No. È il titolare dell’account a completare il flusso di collegamento. Una chiave API è una delega per azioni già autorizzate, non il permesso di sostituirsi al titolare nella schermata di accesso di un social.

Una richiesta consuma una sola pubblicazione del mio piano?

La quota si conta per ogni destinazione sui social. Consulta i piani attuali e la quota residua della credenziale prima di scegliere le destinazioni.