Social

Endpoints Social : marques, liens de connexion hébergés, publication unitaire et en masse, planification, statistiques et plafond global de connexions.

L'API Social permet de publier sur Facebook, Instagram, X, LinkedIn et Pinterest. Deux objets constituent l'ensemble du modèle. Une marque est l'identité sous laquelle vous publiez : un nom, un fuseau horaire et les comptes de réseaux sociaux qui lui sont rattachés. Une connexion correspond à un compte de réseau social autorisé, rattaché à une marque sur une plateforme. Le nombre de marques est illimité avec un forfait API et leur création est gratuite. Les connexions sont les éléments comptabilisés par le forfait ; le plafond de connexions est donc la contrainte à prendre en compte dans votre conception.

La connexion d'un compte ne peut pas être effectuée depuis votre serveur. L'utilisateur final doit l'autoriser sur la plateforme ; vous devez donc demander un lien hébergé et l'y rediriger. La publication est asynchrone : chaque appel de création renvoie une réponse dès que la publication est acceptée, puis vous interrogez périodiquement l'API pour obtenir le résultat par canal.

Aperçu des endpoints

Valeurs utilisées partout

Les valeurs des plateformes sont des noms d'énumération en majuscules. L'envoi de "instagram" est rejeté. TWITTER correspond à X ; le nom de l'énumération n'a pas changé lorsque le produit a changé de nom.

Créer une marque

POST /social/brands

profileName et timezone sont obligatoires. Le fuseau horaire est un objet, et tzCode est le champ déterminant : il s'agit de l'identifiant IANA utilisé pour interpréter chaque valeur de scheduleDate et de scheduleTime dans les publications de cette marque. Les trois autres clés sont des libellés d'affichage.

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"    }  }'

Conservez l'identifiant de marque renvoyé. Il correspond au paramètre de chemin brandId de tous les autres endpoints de marque, ainsi qu'au champ socialProfileId du corps lorsque vous publiez.

Lister et consulter les marques

GET /social/brands renvoie une page de marques. GET /social/brands/{brandId} en renvoie une avec tous ses détails.

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

Un identifiant pour lequel l'endpoint renvoie SY95043 correspond à une marque qui n'appartient pas à ce compte ou qui est déjà archivée.

Mettre à jour une marque

POST /social/brands/update

L’identifiant de la marque se place dans le corps sous la forme input.profileId, et non dans le chemin. Envoyez uniquement les champs que vous modifiez ; tout champ omis conserve sa valeur actuelle.

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."}}'

Archiver une marque

POST /social/brands/archive

Une marque doit exister depuis au moins 90 jours pour pouvoir être archivée. Avant ce délai, l’appel est refusé avec SY95051 et rien ne change. Une fois ce délai atteint, l’archivage prend effet immédiatement et archive simultanément toutes les connexions de la marque.

Ces connexions cessent immédiatement de publier, mais leurs emplacements restent comptabilisés jusqu’à la fin de la période de facturation, exactement comme lors d’une déconnexion manuelle. L’archivage ne permet pas de libérer de la capacité dès aujourd’hui.

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"}}'

Obtenir un lien de connexion

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

C’est le seul moyen d’ajouter une connexion. La réponse contient un lien hébergé url valable pendant expiresIn secondes. Redirigez l’utilisateur final vers ce lien : il accorde son autorisation sur la plateforme, puis est redirigé vers votre redirectUrl avec le résultat dans la chaîne de requête. Transmettez errorUrl pour distinguer les annulations des réussites, et state pour conserver votre propre valeur de corrélation tout au long de l’aller-retour.

N’oubliez pas que ce corps est plat, sans enveloppe 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    }  }}

Vérifiez status avant de rediriger l’utilisateur. Une réponse failed ne renvoie aucun url et indique la raison dans title, le plus souvent la limite de connexions (SY95042) ou une plateforme dont le compte ne dispose pas (SY95044).

Lister les connexions d’une marque

GET /social/brands/{brandId}/connections

Renvoie les comptes rattachés à la marque, chacun accompagné de la valeur id dont vous avez besoin pour publier via une connexion précise ou pour la déconnecter.

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

Déconnecter une connexion

POST /social/connections/disconnect

Prend la valeur id de la connexion dans la liste ci-dessus. Le compte cesse immédiatement de publier, mais l’emplacement qu’il occupait n’est remis à disposition qu’à la fin de la période de facturation. Reconnecter le même compte à la même marque pendant cette période réutilise cet emplacement et ne coûte rien ; le rattacher à une autre marque occupe un deuxième emplacement.

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"}}'

Publier du contenu

POST /social/posts

Un seul appel publie le même contenu sur toutes les plateformes figurant dans platforms. Chacune de ces plateformes doit déjà disposer d’une connexion sur la marque, sinon l’appel renvoie SY95045. Instagram et Pinterest exigent au moins une entrée dans mediaUrls.

Programmez une publication selon l’une des deux méthodes, jamais les deux. scheduledAt est un horodatage ISO-8601 avec un décalage horaire. scheduleDate et scheduleTime sont envoyés ensemble et interprétés dans le fuseau horaire de la marque. Envoyer les deux méthodes de programmation, ou une date de programmation dans le passé, entraîne le renvoi de 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"    }  }'

Définissez clientReference sur votre propre identifiant. Il est stocké et renvoyé, ce qui vous permet de rapprocher une publication de vos enregistrements sans conserver l’UUID.

Lire une publication

GET /social/posts/{postId}

C’est ainsi que vous pouvez vérifier si la publication a réussi. Le champ status de la publication elle-même est un résumé ; le résultat réel est indiqué pour chaque canal dans connectedChannels, où chaque entrée contient sa propre valeur status, une valeur liveLink une fois que la plateforme accepte la publication, et reason ou error lorsqu’elle ne l’accepte pas.

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

Interrogez régulièrement ce point de terminaison après une réponse PUBLISH. Un canal peut échouer alors que les autres réussissent ; vérifiez donc chaque entrée plutôt que le seul champ status de premier niveau.

Lister les publications d'une marque

GET /social/brands/{brandId}/posts

Une page de publications de la marque, avec des filtres pour affiner les résultats par état. Utilisez-la pour effectuer un rapprochement en masse au lieu d'interroger les identifiants un par un.

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

Annuler une publication programmée

POST /social/posts/cancel

Annule une publication qui n'a pas encore été publiée. Une publication déjà en ligne sur une plateforme ne peut pas être retirée via cet 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"}}'

Consulter les statistiques et les commentaires

GET /social/posts/{postId}/insights

Les compteurs d'engagement et les commentaires pour une publication sur un canal. Le canal est obligatoire, car une publication diffusée sur 3 plateformes possède 3 ensembles de chiffres distincts.

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"

Créer des publications en masse

POST /social/bulk-posts

Accepte de 1 à 500 lignes dans input.posts. Chaque ligne est un objet identique à celui que POST /social/posts accepte comme input, et les lignes peuvent cibler différentes marques dans une même requête.

L'ensemble du lot est validé avant toute création. Si une ligne échoue, vous recevez SY95050 avec des erreurs par ligne et rien n'est mis en file d'attente ; corrigez donc les erreurs et renvoyez le lot. L'envoi de plus de 500 lignes renvoie SY95048, là encore sans aucune création. Un lot valide renvoie une tâche dont vous devez interroger l'état.

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"        }      ]    }  }'

Une opération en masse compte comme une seule requête dans votre limite de débit, ce qui en fait une solution efficace pour les lots volumineux.

Interroger l'état d'une tâche en masse

GET /social/bulk-posts/{bulkJobId}

Renvoie l'état de la tâche avec les résultats par ligne, notamment l'identifiant de la publication créée pour chaque ligne et les lignes ayant échoué après leur mise en file d'attente. Les tâches ne sont pas conservées indéfiniment ; une requête portant sur un identifiant dont la durée de conservation a expiré renvoie SY95047.

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

Vérifier les limites et l'utilisation

GET /social/limits

Consultez ces informations avant de créer des connexions plutôt qu'après avoir reçu SY95042. Comparez usage.connections à maxConnections : il s'agit du nombre facturable, qui comprend les connexions actuelles et celles libérées plus tôt au cours de cette période. usage.connectionsActive correspond aux connexions actives à cet instant, et usage.connectionsReleased à la capacité qui redevient disponible au renouvellement.

brands renvoie null, ce qui signifie qu'il n'y a pas de limite. Les marques ne sont pas décomptées dans le cadre d'un forfait API.

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

Erreurs que vous rencontrerez

La liste complète figure dans la référence des codes d'erreur.

Étapes suivantes

Consultez Forfaits et options pour comprendre comment s'articulent le plafond de connexions, les packs de 5 connexions et la règle d'archivage à 90 jours, ainsi que Réagir aux événements avec les webhooks pour recevoir les événements social_post.* et social_connection.* au lieu d'effectuer des interrogations périodiques.

Le Python SDK prend en charge ces endpoints via client.social.brands, client.social.connections, client.social.posts et client.social.bulk ; consultez la ressource Social. Le Node SDK ne prend pas encore en charge Social ; appelez donc les endpoints REST directement depuis Node.