Social

Alle Social-Endpunkte: Marken, gehostete Verbindungslinks, Einzel- und Massenveröffentlichung, Planung, Statistiken und das übergreifende Verbindungslimit.

Die Social API veröffentlicht auf Facebook, Instagram, X, LinkedIn und Pinterest. Zwei Objekte bilden das gesamte Modell ab. Eine Marke ist die Identität, unter der Sie veröffentlichen: ein Name, eine Zeitzone und die damit verknüpften Social-Media-Konten. Eine Verbindung ist ein autorisiertes Social-Media-Konto einer Marke auf einer Plattform. Marken sind in einem API-Tarif unbegrenzt verfügbar und kostenlos. Der Tarif erfasst die Anzahl der Verbindungen, daher müssen Sie bei der Konzeption das Verbindungslimit berücksichtigen.

Ein Konto kann nicht von Ihrem Server aus verbunden werden. Der Endnutzer muss die Verbindung auf der Plattform autorisieren, daher fordern Sie einen gehosteten Link an und leiten ihn dorthin weiter. Die Veröffentlichung erfolgt asynchron: Jeder Aufruf zum Erstellen kehrt zurück, sobald der Beitrag angenommen wurde, und Sie fragen das Ergebnis für jeden Kanal regelmäßig ab.

Endpunkte im Überblick

Werte, die Sie überall verwenden

Plattformwerte sind Enum-Namen in Großbuchstaben. Das Senden von "instagram" wird abgelehnt. TWITTER steht für X; der Enum-Name wurde bei der Umbenennung des Produkts nicht geändert.

Eine Marke erstellen

POST /social/brands

profileName und timezone sind erforderlich. Die Zeitzone ist ein Objekt, und tzCode ist das entscheidende Feld: Es enthält den IANA-Bezeichner, anhand dessen sämtliche Werte für scheduleDate und scheduleTime in den Beiträgen dieser Marke interpretiert werden. Die anderen drei Schlüssel dienen als Anzeigebezeichnungen.

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

Bewahren Sie die zurückgegebene Marken-ID auf. Sie wird bei jedem anderen Marken-Endpunkt als Pfadparameter brandId und beim Veröffentlichen im Body-Feld socialProfileId verwendet.

Marken auflisten und abrufen

GET /social/brands gibt eine Ergebnisseite mit Marken zurück. GET /social/brands/{brandId} gibt eine Marke mit allen Details zurück.

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

Eine ID, für die SY95043 zurückgegeben wird, gehört entweder nicht zu diesem Konto oder verweist auf eine bereits archivierte Marke.

Eine Marke aktualisieren

POST /social/brands/update

Die Marken-ID wird als input.profileId im Body übergeben, nicht im Pfad. Senden Sie nur die Felder, die Sie ändern möchten; alle ausgelassenen Felder behalten ihren aktuellen Wert.

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

Eine Marke archivieren

POST /social/brands/archive

Eine Marke muss seit 90 Tagen bestehen, bevor sie archiviert werden kann. Vor Ablauf dieser Frist wird der Aufruf mit SY95051 abgelehnt und nichts geändert. Sobald die Marke alt genug ist, wird die Archivierung sofort wirksam und archiviert gleichzeitig alle zugehörigen Verbindungen.

Über diese Verbindungen wird sofort nichts mehr veröffentlicht, ihre Plätze werden jedoch bis zum Ende des Abrechnungszeitraums weiterhin angerechnet, genau wie beim manuellen Trennen einer Verbindung. Durch die Archivierung lässt sich heute keine Kapazität freigeben.

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

Einen Verbindungslink abrufen

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

Dies ist die einzige Möglichkeit, eine Verbindung hinzuzufügen. Die Antwort enthält eine gehostete url, die expiresIn Sekunden lang gültig ist. Leiten Sie den Endnutzer dorthin weiter; er erteilt auf der Plattform seine Autorisierung und wird anschließend zu Ihrer redirectUrl zurückgeleitet, wobei das Ergebnis im Query-String übergeben wird. Übergeben Sie errorUrl, um Abbrüche von erfolgreichen Vorgängen zu unterscheiden, und state, um Ihren eigenen Korrelationswert durch den gesamten Ablauf mitzuführen.

Beachten Sie, dass dieser Body flach aufgebaut ist und keinen input-Wrapper enthält.

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

Prüfen Sie status vor der Weiterleitung. Eine failed-Antwort gibt keine url zurück und enthält den Grund in title, meist das Verbindungslimit (SY95042) oder eine Plattform, die dem Konto nicht zur Verfügung steht (SY95044).

Die Verbindungen einer Marke auflisten

GET /social/brands/{brandId}/connections

Gibt die mit der Marke verbundenen Konten zurück, jeweils mit der id, die Sie benötigen, um über eine bestimmte Verbindung zu veröffentlichen oder diese zu trennen.

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

Eine Verbindung trennen

POST /social/connections/disconnect

Verwendet die id der Verbindung aus der obigen Liste. Über das Konto wird sofort nichts mehr veröffentlicht, der belegte Platz wird jedoch erst am Ende des Abrechnungszeitraums wieder freigegeben. Wenn Sie dasselbe Konto innerhalb dieses Zeitraums erneut mit derselben Marke verbinden, wird dieser Platz wiederverwendet und es entstehen keine Kosten; die Verbindung mit einer anderen Marke belegt einen zweiten Platz.

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

Einen Beitrag veröffentlichen

POST /social/posts

Ein Aufruf veröffentlicht denselben Inhalt auf jeder Plattform in platforms. Für jede dieser Plattformen muss bereits eine Verbindung mit der Marke bestehen, andernfalls gibt der Aufruf SY95045 zurück. Instagram und Pinterest erfordern mindestens einen Eintrag in mediaUrls.

Planen Sie einen Beitrag auf eine von zwei Arten, niemals auf beide zugleich. scheduledAt ist ein ISO-8601-Zeitstempel mit einem Offset. scheduleDate und scheduleTime werden zusammen gesendet und in der Zeitzone der Marke interpretiert. Wenn Sie beide Varianten oder einen Zeitpunkt in der Vergangenheit senden, wird SY95046 zurückgegeben.

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

Setzen Sie clientReference auf Ihre eigene Kennung. Sie wird gespeichert und zurückgegeben, sodass Sie einen Beitrag mit Ihren Datensätzen abgleichen können, ohne die UUID aufzubewahren.

Einen einzelnen Beitrag abrufen

GET /social/posts/{postId}

So erfahren Sie, ob die Veröffentlichung erfolgreich war. Der eigene status des Beitrags ist eine Zusammenfassung; das tatsächliche Ergebnis steht für jeden Kanal in connectedChannels, wobei jeder Eintrag seinen eigenen status enthält, eine liveLink, sobald die Plattform den Beitrag annimmt, sowie reason oder error, wenn sie ihn nicht annimmt.

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

Fragen Sie diesen Endpunkt nach einer PUBLISH wiederholt ab. Bei einem Kanal kann die Veröffentlichung fehlschlagen, während sie bei den anderen erfolgreich ist. Prüfen Sie daher jeden Eintrag statt nur den übergeordneten status.

Beiträge einer Marke auflisten

GET /social/brands/{brandId}/posts

Eine Seite mit Beiträgen der Marke und Filtern zur Eingrenzung nach Status. Verwenden Sie sie für einen gesammelten Abgleich, statt IDs einzeln abzufragen.

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

Einen geplanten Beitrag stornieren

POST /social/posts/cancel

Storniert einen Beitrag, der noch nicht veröffentlicht wurde. Ein Beitrag, der bereits auf einer Plattform veröffentlicht ist, kann über diesen Endpunkt nicht zurückgezogen werden.

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

Statistiken und Kommentare abrufen

GET /social/posts/{postId}/insights

Interaktionszahlen und Kommentare für einen Beitrag auf einem Kanal. Der Kanal ist erforderlich, da ein auf drei Plattformen veröffentlichter Beitrag drei separate Zahlensätze hat.

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"

Beiträge gesammelt erstellen

POST /social/bulk-posts

Akzeptiert 1 bis 500 Zeilen in input.posts. Jede Zeile ist dasselbe Objekt, das POST /social/posts als input akzeptiert, und die Zeilen können innerhalb derselben Anfrage für unterschiedliche Marken bestimmt sein.

Der gesamte Stapel wird validiert, bevor etwas erstellt wird. Wenn eine Zeile die Validierung nicht besteht, erhalten Sie SY95050 mit Fehlern pro Zeile, und nichts wird in die Warteschlange gestellt. Korrigieren Sie daher die Fehler und senden Sie den Stapel erneut. Bei mehr als 500 Zeilen wird SY95048 zurückgegeben, ebenfalls ohne etwas zu erstellen. Ein gültiger Stapel liefert einen Auftrag zurück, dessen Status Sie abfragen können.

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

Eine Sammelanfrage zählt als eine Anfrage für Ihr Anfragelimit und ist daher der effiziente Weg für große Stapel.

Einen Sammelauftrag abfragen

GET /social/bulk-posts/{bulkJobId}

Gibt den Status des Auftrags mit Ergebnissen pro Zeile zurück, einschließlich der für jede Zeile erstellten Beitrags-ID sowie aller Zeilen, die nach dem Einreihen in die Warteschlange fehlgeschlagen sind. Aufträge werden nicht unbegrenzt aufbewahrt; bei einer ID, deren Aufbewahrungsfrist abgelaufen ist, wird SY95047 zurückgegeben.

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

Limits und Nutzung prüfen

GET /social/limits

Rufen Sie diese Informationen vor dem Erstellen von Verbindungen ab, statt erst nach einem SY95042. Vergleichen Sie usage.connections mit maxConnections: Das ist die abrechenbare Anzahl, bestehend aus den aktuell verbundenen und den zuvor in diesem Zeitraum freigegebenen Verbindungen. usage.connectionsActive gibt an, was aktuell aktiv ist, und usage.connectionsReleased, wie viel Kapazität bei der Verlängerung wieder verfügbar wird.

brands wird als null zurückgegeben, was unbegrenzt bedeutet. Bei einem API-Tarif wird die Anzahl der Marken nicht als Verbrauch erfasst.

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

Fehler, die auftreten können

Die vollständige Liste finden Sie in der Fehlercode-Referenz.

Nächste Schritte

Lesen Sie Tarife und Zusatzoptionen, um zu erfahren, wie das Verbindungslimit, die Pakete mit 5 Verbindungen und die 90-Tage-Archivierungsregel zusammenwirken, sowie Mit Webhooks auf Ereignisse reagieren, um Ereignisse vom Typ social_post.* und social_connection.* zu empfangen, statt regelmäßig Abfragen durchzuführen.

Das Python SDK stellt diese Endpunkte als client.social.brands, client.social.connections, client.social.posts und client.social.bulk bereit; siehe die Social-Ressource. Das Node SDK unterstützt Social noch nicht. Rufen Sie daher die REST-Endpunkte direkt aus Node auf.