SosoAPI:s publicerings-API: autentisering, anrop och resultat

1. Autentisera från din server

Skapa en API-nyckel i SosoAPI-appen → Inställningar → Agenter och API-åtkomst. Lagra den som SOSOAPI_API_KEY i servermiljön. Anrop använder Authorization: Bearer <your-key> och Content-Type: application/json. Bädda aldrig in nyckeln i en webbplats, mobilapp, URL eller ett offentligt kodarkiv.

Alla slutpunkter nedan använder POST med en JSON-kropp. Nycklar och delegerade agentbehörigheter begränsas av sina funktioner, tillåtna arbetsytor och ägarens aktuella medlemskap. Läsningar kräver agent:operate och minst viewer-åtkomst; publiceringsändringar kräver agent:publish och minst editor-åtkomst. En behörighet kan inte utvidga ägarens rättigheter.

Använd appens aktuella arbetsyta och anslutna konton eller anropa /identity-api/workspace/list och /identity-api/user/social-accounts/list för att hitta ID:n som du har behörighet att använda. Gissa inte en kunds arbetsyte- eller konto-ID.

// Node.js 20+; run only on your server.
const apiKey = process.env.SOSOAPI_API_KEY;
if (!apiKey) throw new Error("Set SOSOAPI_API_KEY on your server");
const apiBase = "https://gqeshlawtcexsapabaui.supabase.co/functions/v1";

async function sosoPost(path, body) {
  const response = await fetch(apiBase + path, {
    method: "POST",
    headers: {
      Authorization: "Bearer " + apiKey,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  });
  const result = await response.json();
  if (!response.ok) {
    const requestId = result.request_id ?? response.headers.get("x-request-id");
    // Handler errors use code/message; schema-validation 400s instead use
    // success:false and error:{name:"ZodError",message:...}.
    // Preserve status, available code and requestId in server diagnostics.
    // Never log the key or an Authorization header.
    throw new Error("SosoAPI " + response.status + " (" +
      (requestId ?? "no request id") + ")");
  }
  return result;
}

2. Karta över publiceringsslutpunkter

Sökvägarna är relativa till API-basen i serverhjälparen. Hämta Scheduled Post-detaljer för aktuell version, tillgängliga åtgärder och publiceringsresultat.

3. Lista och dela upp i sidor utan att tappa omfånget

limit är som standard 50 och godtar 1–200. Valfria status är något av scheduled, publishing, published, failed, expired, needs_reschedule, cancelled eller deleted. scheduled_from och scheduled_to måste anges tillsammans som ISO-8601-tidpunkter med tidszonsförskjutning; slutet måste vara efter början.

next_cursor är antingen null eller ett objekt med scheduled_at och id. Skicka tillbaka hela objektet som cursor tillsammans med samma arbetsyta och filter. Denna slutpunkt godtar inte filtren page, offset, platform eller social_account_id.

await sosoPost("/studio-api/scheduled-posts/list", {
  "workspace_id": "<workspace-uuid>",
  "limit": 50
});

const first = await sosoPost("/studio-api/scheduled-posts/list", {
  workspace_id: "<workspace-uuid>", limit: 50
});
if (first.next_cursor) {
  const next = await sosoPost("/studio-api/scheduled-posts/list", {
    workspace_id: "<workspace-uuid>", limit: 50, cursor: first.next_cursor
  });
  // Consume next.posts; continue only while next_cursor is not null.
}

4. Validera och skapa ett granskat inlägg

Ersätt alla platshållare med värden från ditt godkända omfång och en framtida tid. Exemplet schemalägger ett riktigt textinlägg på Threads när det körs. Få personens bekräftelse av konto, innehåll och tid före create-anropet.

Ange provider_payload.platform och plattformens publish_options. Servern kontrollerar att de stämmer med valt konto. Du kan inkludera project_id för att registrera inläggets ursprung; projektet ger inte publiceringsåtkomst och styr inte schemaläggningen.

await sosoPost("/studio-api/scheduled-posts/eligibility", {
  "workspace_id": "<workspace-uuid>",
  "include_quota": true,
  "targets": [
    {
      "social_account_id": "<threads-account-uuid>",
      "media": [],
      "provider_payload": {
        "platform": "threads",
        "publish_options": {
          "post_type": "TEXT"
        }
      },
      "draft": {
        "caption": "A reviewed update from our team.",
        "hashtags": [],
        "scheduled_at": "<future-ISO-8601-instant-with-offset>",
        "display_timezone": "Asia/Hong_Kong"
      }
    }
  ]
});

await sosoPost("/studio-api/scheduled-posts/create", {
  "workspace_id": "<workspace-uuid>",
  "social_account_id": "<threads-account-uuid>",
  "caption": "A reviewed update from our team.",
  "hashtags": [],
  "media": [],
  "provider_payload": {
    "platform": "threads",
    "publish_options": {
      "post_type": "TEXT"
    }
  },
  "scheduled_at": "<future-ISO-8601-instant-with-offset>",
  "display_timezone": "Asia/Hong_Kong",
  "idempotency_key": "<stable-key-for-this-one-intent>"
});

5. Läs resultatet och avbryt säkert

Create returnerar { post, deduped }. List returnerar { posts, next_cursor, returned_count }. Get returnerar { post, delivery, actions, attempts, outcomes }. Ett inlägg innehåller id, status, version, destination, schedule och tillgänglig leverantörsidentitet/permalänk; delivery och actions förklarar aktuellt förlopp och tillåtna nästa steg.

Ett inlägg med status scheduled eller publishing väntar fortfarande. Ett slutligt publiceringsresultat med status published bekräftar publicering och innehåller tillgängliga leverantörsbelägg för inlägget; en permalänk kan saknas. Om klienten kopplas från eller ett svar dröjer, läs det befintliga inlägget innan du redovisar resultat.

Hämta inläggsinformationen före avbrytande och ange dess aktuella numeriska version. Resultatet kan vara cancellation_pending medan SosoAPI avbryter en schemaläggning hos leverantören. Att avbryta en schemaläggning tar inte bort ett redan publicerat inlägg.

await sosoPost("/studio-api/scheduled-posts/get", {
  "id": "<scheduled-post-uuid>"
});

const detail = await sosoPost("/studio-api/scheduled-posts/get", {
  id: "<scheduled-post-uuid>"
});
// Run only after the person confirms cancelling this unpublished post.
await sosoPost("/studio-api/scheduled-posts/cancel", {
  id: detail.post.id, expected_version: detail.post.version
});

6. Idempotens, konflikter och osäkra skrivningar

Använd samma idempotency_key när du upprepar samma create-anrop. En matchande upprepning returnerar det befintliga inlägget med deduped=true. Att ändra innehållet och återanvända nyckeln orsakar en konflikt. Detta förhindrar dubbla skapanden i SosoAPI; det garanterar inte leverans exakt en gång hos leverantören.

För uppdateringar och åtgärder anger du expected_version från senaste detaljsvaret. Vid konflikt hämtar du inlägget igen och granskar ändringen mot den nya versionen. Ett förlorat svar är skäl att kontrollera befintlig status, inte att skapa ett nytt inlägg med ny nyckel.

Skyddet mot duplicerat innehåll kan avvisa en separat begäran med samma normaliserade offentliga innehåll, konto och en närliggande publiceringstid. Granska hänvisningen till det befintliga inlägget om du har läsbehörighet och fråga användaren innan du ändrar begäran. Massbegäranden returnerar ett resultat per destination; vissa kan lyckas medan andra misslyckas.

7. Fel, anropsgränser och integrationsgränser

Hanterarfel använder ett hölje med error, message, valfri code, retryable, request_id, valfria details och retry_after_seconds. Schemavalidering med 400 returnerar en annan form: { success: false, error: { name: "ZodError", message: "…" } }. Valideringsmeddelandet innehåller för närvarande serialiserade fältproblem, inklusive deras sökvägar; förutsätt inte att hanterarhöljets fält finns.

Vid felsökning behåller du HTTP-status, felkod och korrelations-ID från result.request_id ?? response.headers.get("x-request-id"). Använd valideringens fältsökvägar för att rätta begäran. Vid autentiserings- eller behörighetsfel åtgärdar du uppgifterna eller behörigheten innan du försöker igen.

Aktuell studio-api-gräns är 240 anrop per minut och mänsklig användare och 480 per minut i användarens separata pott för maskinuppgifter. Detta är anropstak, inte publiceringstakt eller abonnemangskvoter. Andra slutpunkter och sociala leverantörer har separata gränser. Följ aktuell Retry-After-header vid 429 eller återförsökbar 503; kör inte en tät loop.

Läs status med avgränsade intervall medan användaren följer inlägget eller använd appens livestatusvy. Detta API lovar inte utgående webhooks, abonnent-SLA, identiska funktioner mellan plattformar eller en fast publiceringstid.

• Plattformsfunktionsmatris
• Konfigurera din egen AI-agent