Social

Endpoint Social: brand, link di connessione ospitati, pubblicazione singola e massiva, pianificazione, statistiche e limite globale di connessioni.

La Social API pubblica su Facebook, Instagram, X, LinkedIn e Pinterest. L'intero modello si basa su due oggetti. Un brand è l'identità con cui pubblichi: un nome, un fuso orario e gli account social associati. Una connessione è un singolo account social autorizzato, associato a un brand su una piattaforma. Con un piano API, i brand sono illimitati e gratuiti. Il piano conteggia le connessioni, quindi il limite di connessioni è il vincolo da tenere presente nella progettazione.

Non puoi collegare un account dal tuo server. L'utente finale deve autorizzarlo sulla piattaforma, quindi devi richiedere un link ospitato e reindirizzarvi l'utente. La pubblicazione è asincrona: ogni chiamata di creazione restituisce una risposta non appena il post viene accettato, e devi effettuare richieste periodiche per ottenere il risultato per ciascun canale.

Panoramica degli endpoint

Valori che userai ovunque

I valori delle piattaforme sono nomi enum in maiuscolo. L'invio di "instagram" viene rifiutato. TWITTER corrisponde a X; il nome enum non è cambiato quando è cambiato quello del prodotto.

Crea un brand

POST /social/brands

profileName e timezone sono obbligatori. Il fuso orario è un oggetto e tzCode è il campo rilevante: è l'identificatore IANA usato per interpretare ogni scheduleDate e scheduleTime nei post di questo brand. Le altre tre chiavi sono etichette di visualizzazione.

curl -X POST https://listingsapi.com/api/v4/social/brands \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "profileName": "Jenny Home",      "timezone": {        "label": "(GMT-05:00) Eastern Time",        "tzCode": "America/New_York",        "name": "Eastern Standard Time",        "utc": "-05:00"      },      "categories": ["Furniture Store"],      "siteUrl": "https://jennyhome.example"    }  }'

Conserva l'ID del brand restituito. È il token brandId nel percorso di tutti gli altri endpoint dei brand e il campo socialProfileId del corpo quando pubblichi.

Elenca e leggi i brand

GET /social/brands restituisce una pagina di brand. GET /social/brands/{brandId} ne restituisce uno con tutti i suoi dettagli.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands?page=1&size=25"

Se una richiesta con un ID restituisce SY95043, il brand non appartiene a questo account oppure è già stato archiviato.

Aggiorna un brand

POST /social/brands/update

L'ID del brand va nel corpo come input.profileId, non nel percorso. Invia solo i campi che stai modificando; tutto ciò che ometti mantiene il valore attuale.

curl -X POST https://listingsapi.com/api/v4/social/brands/update \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"profileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "bio": "Handmade furniture for real homes."}}'

Archivia un brand

POST /social/brands/archive

Un brand deve esistere da almeno 90 giorni prima di poter essere archiviato. Prima di questa soglia, la chiamata viene rifiutata con SY95051 e non cambia nulla. Una volta raggiunta questa soglia, l'archiviazione ha effetto immediato e archivia contemporaneamente tutte le connessioni del brand.

Queste connessioni smettono subito di pubblicare, ma i loro slot continuano a essere conteggiati fino alla fine del periodo di fatturazione, esattamente come avviene con una disconnessione manuale. L'archiviazione non è un modo per liberare capacità oggi.

curl -X POST https://listingsapi.com/api/v4/social/brands/archive \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902"}}'

Ottieni un link di connessione

POST /social/brands/{brandId}/connections/link

Questo è l'unico modo per aggiungere una connessione. La risposta contiene un url ospitato, valido per expiresIn secondi. Reindirizza l'utente finale a questo indirizzo: l'utente concede l'autorizzazione sulla piattaforma e viene poi reindirizzato al tuo redirectUrl con l'esito nella stringa di query. Passa errorUrl per distinguere gli annullamenti dagli esiti positivi e state per mantenere un tuo valore di correlazione durante l'intero flusso di andata e ritorno.

Ricorda che questo corpo ha una struttura piatta, senza un contenitore input.

curl -X POST https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/connections/link \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "channel": "INSTAGRAM",    "redirectUrl": "https://app.example.com/social/connected",    "errorUrl": "https://app.example.com/social/failed"  }'

{  "data": {    "connectSocialAccount": {      "status": "success",      "url": "https://social.listingsapi.com/connect/start?token=bfac8e06-8d72-4810-9c50-ae7ee12a7b52",      "expiresIn": 900    }  }}

Controlla status prima di reindirizzare. Una risposta failed non restituisce alcun url e indica il motivo in title, il più delle volte il limite di connessioni (SY95042) o una piattaforma di cui l'account non dispone (SY95044).

Elenca le connessioni di un brand

GET /social/brands/{brandId}/connections

Restituisce gli account collegati al brand, ciascuno con il relativo id necessario per pubblicare su una connessione specifica o per disconnetterla.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/connections

Disconnetti una connessione

POST /social/connections/disconnect

Accetta il valore id della connessione dall'elenco precedente. L'account smette subito di pubblicare, ma lo slot che occupava non torna disponibile fino alla fine del periodo di fatturazione. Riconnettere lo stesso account allo stesso brand entro il periodo riutilizza quello slot e non comporta costi; collegarlo a un brand diverso occupa un secondo slot.

curl -X POST https://listingsapi.com/api/v4/social/connections/disconnect \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileConnectedChannelId": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"}}'

Pubblica un post

POST /social/posts

Una sola chiamata pubblica lo stesso contenuto su tutte le piattaforme in platforms. Ciascuna di queste piattaforme deve già avere una connessione sul brand, altrimenti la chiamata restituisce SY95045. Instagram e Pinterest richiedono almeno un elemento in mediaUrls.

Programma un post in uno dei due modi, mai con entrambi. scheduledAt è un timestamp ISO-8601 con uno scostamento rispetto a UTC. scheduleDate e scheduleTime vengono inviati insieme e interpretati nel fuso orario del brand. L'invio di entrambe le modalità di programmazione, o di una programmazione nel passato, restituisce SY95046.

curl -X POST https://listingsapi.com/api/v4/social/posts \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",      "name": "Autumn collection launch",      "platforms": ["INSTAGRAM", "FACEBOOK"],      "content": "Our autumn collection lands today.",      "mediaUrls": ["https://cdn.example.com/social/autumn-collection.jpg"],      "action": "SCHEDULE",      "scheduleDate": "2026-10-02",      "scheduleTime": "09:30",      "clientReference": "campaign-4471-slot-01"    }  }'

Imposta clientReference sul tuo identificatore. Viene memorizzato e restituito, consentendoti di associare un post ai tuoi record senza conservare l'UUID.

Leggi un singolo post

GET /social/posts/{postId}

In questo modo puoi verificare se la pubblicazione è riuscita. Il valore status del post è un riepilogo; l'esito effettivo è indicato per ciascun canale in connectedChannels, dove ogni elemento contiene il proprio status, un liveLink quando la piattaforma accetta il post e reason o error quando non lo accetta.

{  "connectedChannels": [    {      "platform": "INSTAGRAM",      "status": "SUCCESS",      "liveLink": "https://www.instagram.com/p/CxYz1234abc/",      "error": null    }  ]}

Interroga periodicamente questo endpoint dopo un PUBLISH. La pubblicazione può fallire su un canale e riuscire sugli altri, quindi controlla ogni elemento anziché soltanto il valore status al livello principale.

Elenca i post di un brand

GET /social/brands/{brandId}/posts

Una pagina di post del brand, con filtri per restringere i risultati in base allo stato. Usala per eseguire una riconciliazione in blocco invece di interrogare gli id uno alla volta.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/posts?page=1&size=25"

Annulla un post programmato

POST /social/posts/cancel

Annulla un post che non è ancora stato pubblicato. Un post già pubblicato su una piattaforma non può essere ritirato tramite questo endpoint.

curl -X POST https://listingsapi.com/api/v4/social/posts/cancel \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialPostId": "a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10"}}'

Leggi statistiche e commenti

GET /social/posts/{postId}/insights

Conteggi delle interazioni e commenti per un singolo post su un singolo canale. Il canale è obbligatorio, perché un post pubblicato su tre piattaforme ha tre insiemi distinti di dati numerici.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/posts/a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10/insights?socialConnectedChannelId=b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"

Crea post in blocco

POST /social/bulk-posts

Accetta da 1 a 500 righe in input.posts. Ogni riga è lo stesso oggetto che POST /social/posts accetta come input, e le righe possono riguardare brand diversi nella stessa richiesta.

L'intero batch viene convalidato prima che venga creato qualsiasi elemento. Se una qualsiasi riga non supera la convalida, ricevi SY95050 con gli errori per ciascuna riga e nulla viene messo in coda, quindi correggi e invia di nuovo. Con più di 500 righe viene restituito SY95048, anche in questo caso senza creare nulla. Un batch valido restituisce un job da interrogare periodicamente.

curl -X POST https://listingsapi.com/api/v4/social/bulk-posts \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "name": "October launch batch",      "posts": [        {          "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",          "name": "Launch day",          "platforms": ["FACEBOOK"],          "content": "Doors open at nine.",          "action": "SCHEDULE",          "scheduleDate": "2026-10-02",          "scheduleTime": "09:00"        }      ]    }  }'

Un'operazione in blocco conta come una sola richiesta ai fini del limite di frequenza delle richieste, il che la rende la soluzione efficiente per batch di grandi dimensioni.

Interroga periodicamente un job di elaborazione in blocco

GET /social/bulk-posts/{bulkJobId}

Restituisce lo stato del job con i risultati per ciascuna riga, inclusi l'id del post creato per ogni riga e le eventuali righe la cui elaborazione non è riuscita dopo l'inserimento in coda. I job non vengono conservati per sempre; per un id il cui periodo di conservazione è scaduto, viene restituito SY95047.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/bulk-posts/f47ac10b-58cc-4372-a567-0e02b2c3d479

Controlla limiti e utilizzo

GET /social/limits

Consulta queste informazioni prima di creare connessioni, anziché dopo aver ricevuto SY95042. Confronta usage.connections con maxConnections: il primo è il conteggio fatturabile, che comprende le connessioni attuali più quelle rilasciate in precedenza in questo periodo. usage.connectionsActive indica ciò che è attivo in questo momento, mentre usage.connectionsReleased indica quanta capacità torna disponibile al rinnovo.

brands viene restituito con il valore null, che significa illimitato. I brand non sono soggetti a conteggio in un piano API.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/limits

Errori che potresti incontrare

L'elenco completo è disponibile nella documentazione di riferimento dei codici di errore.

Passaggi successivi

Leggi Piani e componenti aggiuntivi per sapere come interagiscono il limite massimo di connessioni, i pacchetti da 5 connessioni e la regola di archiviazione dei 90 giorni, e Reagisci agli eventi con i webhook per ricevere gli eventi social_post.* e social_connection.* invece di effettuare interrogazioni periodiche.

Il Python SDK supporta questi endpoint tramite client.social.brands, client.social.connections, client.social.posts e client.social.bulk; consulta la risorsa Social. Il Node SDK non supporta ancora Social, quindi chiama gli endpoint REST direttamente da Node.