Einen Beitrag veröffentlichen

Ein Beitrag gehört zu einem Betrieb und geht an ein oder mehrere Netzwerke, seine Ziele. Jedes Ziel hat seinen eigenen Text, seine Medien, sein Format und seinen Zustand.

Beitragsart: sofort, geplant oder Entwurf

Zwei Felder des Bodys entscheiden, wann und ob der Beitrag rausgeht:

Der Body eines Beitrags

Medien eines Ziels

Jeder Eintrag von targets[].media bezeichnet ein Medium der Mediathek über seine id oder eine öffentliche https-url mit ihrem type (image oder video). Instagram und TikTok verlangen ein Foto oder ein Video. Um der Mediathek ein Medium hinzuzufügen, siehe Ein Medium importieren.

Einen Beitrag duplizieren

Es gibt keinen eigenen Endpoint zum Duplizieren eines Beitrags: Lies ihn mit `GET /v1/posts/{id}` und sende seinen Inhalt dann in einer neuen Anfrage POST /v1/posts zurück.

Entferne vor dem Zurücksenden die Felder, die Sofia selbst füllt. Mindestens:

• id und createdAt des Beitrags;
• status des gelesenen Beitrags (er fasst den Versandzustand zusammen): Setze den gewünschten oder lasse ihn weg;
• in jedem Ziel: state, publishedAt, permalink und error.

Behalte establishmentId und pro Ziel platform und accountId. Das Lesen liefert weder den Text der Ziele noch ihre Medien: Gib sie erneut an. Setze schließlich ein neues scheduledAt (oder lasse es weg, um sofort zu veröffentlichen, oder sende "status": "draft").

Dein erster Beitrag

1. Die verbundenen Netzwerke prüfen

Ein Beitrag geht über die mit dem Betrieb verbundenen Konten raus. Liste sie auf; fehlt eines, erstelle einen Verbindungslink. Siehe Verbundene Konten.

2. Ein Medium hinzufügen

Instagram und TikTok verlangen ein Foto oder ein Video. Importiere eines von einer öffentlichen https-URL; Sofia lädt es in die Mediathek und liefert seine id zurück. Siehe Ein Medium importieren.

3. Mit einer Simulation prüfen

Füge ?dry_run=true hinzu: Sofia beurteilt jedes Netzwerk nach seinen echten Regeln und dem verbundenen Konto und schreibt nichts.

curl -X POST 'https://api.sofia-post.com/api/v1/posts?dry_run=true' \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "establishmentId": "'$ESTABLISHMENT_ID'",
    "targets": [
      { "platform": "instagram", "text": "Tarte tatin du jour", "media": [{ "id": "'$MEDIA_ID'" }] },
      { "platform": "facebook", "text": "Tarte tatin du jour", "media": [{ "id": "'$MEDIA_ID'" }] }
    ]
  }'

{
  "status": "ready",
  "dryRun": true,
  "targets": [
    { "platform": "instagram", "accountId": "fecd0904-…", "handle": "sof_ia_officiel", "state": "ready" },
    { "platform": "facebook", "accountId": "a423b3a4-…", "handle": "Sofia post", "state": "ready" }
  ]
}

4. Veröffentlichen

Sende denselben Body ohne dry_run, mit einem Idempotency-Key, damit ein erneuter Versuch nie doppelt veröffentlicht. Ohne scheduledAt geht der Beitrag sofort raus; mit einem zukünftigen scheduledAt wird er geplant.

curl -X POST https://api.sofia-post.com/api/v1/posts \
  -H "Authorization: Bearer $SOFIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @post.json

5. Ihn verfolgen

Der Beitrag antwortet publishing, dann wechselt jedes Netzwerk zu published mit seinem Permalink oder zu failed mit seinem Grund. Lies ihn mit `GET /v1/posts/{id}` oder registriere einen Webhook, um benachrichtigt zu werden.

Simulation (Dry Run)

POST /v1/posts?dry_run=true führt die Prüfungen eines echten Beitrags aus: die Regeln jedes Netzwerks, das verbundene Konto, die Medien, das Datum und deinen Tarif. Es speichert nichts und sendet nichts.

Bereit

Würde jedes Netzwerk den Beitrag akzeptieren, ist die Antwort 200 mit status: "ready" und für jedes Ziel dem Konto, das veröffentlichen würde.

Abgelehnt

Andernfalls ist die Antwort 422 post_refused, mit einem Detail pro Grund. Jedes Detail nennt sein Netzwerk, seinen code und sagt, was zu korrigieren ist.

{
  "error": {
    "code": "post_refused",
    "message": "The post would not be published: x: the text is too long (300 characters, at most 280)",
    "details": [
      {
        "platform": "x",
        "code": "caption_too_long",
        "max": 280,
        "actual": 300,
        "message": "x: the text is too long (300 characters, at most 280)"
      }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#post_refused"
  }
}

Jeder Grund ist bei den Fehlern aufgelistet.

Zum Testmodus der Anwendungen siehe Testmodus und Simulation. Ein Idempotency-Key schützt auch POST /v1/posts: siehe Idempotenz.