SosoAPI közzétételi API: hitelesítés, kérések és eredmények

1. Hitelesíts a szerveredről

Hozz létre API-kulcsot itt: SosoAPI alkalmazás → Beállítások → Ügynökök és API-hozzáférés. Tárold SOSOAPI_API_KEY néven a szerverkörnyezetben. A kérések Authorization: Bearer <your-key> és Content-Type: application/json értéket használnak. Soha ne ágyazd a kulcsot webhelybe, mobilalkalmazás-csomagba, URL-be vagy nyilvános adattárba.

Minden alábbi végpont POST-ot használ JSON-törzzsel. A kulcsokat és delegált ügynökengedélyeket a képességek, engedélyezett munkaterületek és a tulajdonos aktuális tagsága korlátozza. Olvasáshoz agent:operate és legalább viewer hozzáférés, közzétételi módosításhoz agent:publish és legalább editor hozzáférés kell. Az engedély nem bővítheti a tulajdonos jogait.

Használd az alkalmazás aktuális munkaterületét és összekapcsolt fiókjait, vagy hívd meg a /identity-api/workspace/list és /identity-api/user/social-accounts/list végpontokat az engedélyezett azonosítókhoz. Ne találj ki ügyfél-munkaterület- vagy fiókazonosítót.

// 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. Közzétételi végponttérkép

Ezek az útvonalak a szerversegéd API-alapcíméhez relatívak. Kérd le a Scheduled Post részleteit az aktuális verzióhoz, elérhető műveletekhez és közzétételi eredményhez.

3. Listázz és lapozz a hatókör megtartásával

A limit alapértéke 50, megengedett tartománya 1–200. Az opcionális status értéke scheduled, publishing, published, failed, expired, needs_reschedule, cancelled vagy deleted. A scheduled_from és scheduled_to értékét együtt, időeltolást tartalmazó ISO-8601 időpontként kell megadni; a záró időpontnak későbbinek kell lennie a kezdőnél.

A next_cursor null vagy scheduled_at és id mezőt tartalmazó objektum. A teljes objektumot küldd vissza cursor értékként, ugyanazzal a munkaterülettel és szűrőkkel. Ez a végpont nem fogad page, offset, platform vagy social_account_id szűrőt.

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. Ellenőrizz és hozz létre egy jóváhagyott bejegyzést

Minden helyőrzőt cserélj az engedélyezett hatókörből származó értékre és jövőbeli időpontra. Végrehajtáskor ez a példa valódi Threads-szöveges bejegyzést időzít. A létrehozási hívás előtt kérd a személy megerősítését a fiókról, tartalomról és időpontról.

Állítsd be a provider_payload.platform és a platformhoz tartozó publish_options értékét. A szerver ellenőrzi, hogy egyeznek-e a kiválasztott fiókkal. A project_id megadásával rögzítheted a bejegyzés eredetét; a projekt nem ad közzétételi hozzáférést és nem vezérli az időzítést.

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. Olvasd el az eredményt, és vond vissza biztonságosan

A Create { post, deduped }, a List { posts, next_cursor, returned_count }, a Get { post, delivery, actions, attempts, outcomes } értéket ad vissza. A post tartalmazza az id, status, version, destination, schedule és elérhető szolgáltatói azonosság/permalink adatait; a delivery és actions a haladást és engedélyezett következő lépéseket ismerteti.

A scheduled vagy publishing status értékű bejegyzés még függőben van. A published status értékű végleges közzétételi eredmény igazolja a megjelenést, és tartalmazza az elérhető szolgáltatói bizonyítékot; permalink hiányozhat. Kliensszétkapcsolás vagy késő válasz esetén eredményjelentés előtt olvasd a meglévő bejegyzést.

Visszavonás előtt kérd le a bejegyzés részleteit, és add meg aktuális numerikus version értékét. Az eredmény cancellation_pending lehet, amíg a SosoAPI visszavonja a szolgáltatónál lévő időzítést. Időzítés visszavonása nem töröl már közzétett bejegyzést.

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. Idempotencia, ütközések és bizonytalan írások

Ugyanazon létrehozási kérés megismétlésekor ugyanazt az idempotency_key értéket használd. Egyező ismétléskor a meglévő bejegyzést adja vissza deduped=true értékkel. Ha a kulcs újrafelhasználásakor megváltoztatod a tartalmat, ütközés keletkezik. Ez a SosoAPI-ban megelőzi az ismételt létrehozást; a szolgáltatónál nem garantál pontosan egyszeri kézbesítést.

Frissítésekhez és műveletekhez a legfrissebb részletes válasz expected_version értékét add meg. Ütközésnél kérd le újra a bejegyzést, és vesd össze módosításodat az új verzióval. Elveszett válasz esetén a meglévő állapotot ellenőrizd; ne hozz létre másik bejegyzést új kulccsal.

A duplikált tartalom elleni védelem elutasíthat egy másik kérést, ha a normalizált nyilvános tartalom, a fiók és a közeli közzétételi idő megegyezik. Vizsgáld meg a meglévő bejegyzés hivatkozását, ha olvashatod, és a kérés módosítása előtt kérdezd meg a felhasználót. A tömeges kérések célhelyenként adnak eredményt; egyesek sikerülhetnek, míg mások meghiúsulnak.

7. Hibák, hívási és integrációs korlátok

A kezelőhibák error, message, opcionális code, retryable, request_id, opcionális details és retry_after_seconds mezőket tartalmazó burkot használnak. A sémaellenőrzési 400-as hibák alakja eltérő: { success: false, error: { name: "ZodError", message: "…" } }. Az ellenőrzési üzenet jelenleg a szerializált mezőhibákat és útvonalaikat tartalmazza; ne feltételezd, hogy a kezelőburok mezői jelen vannak.

Hibadiagnóziskor őrizd meg a HTTP-állapotot, hibakódot és korrelációs azonosítót innen: result.request_id ?? response.headers.get("x-request-id"). Az ellenőrzési mezőútvonalakkal javítsd a kérést. Hitelesítési vagy engedélyhibánál újrapróbálás előtt javítsd a hitelesítő adatot vagy engedélyt.

A studio-api jelenlegi korlátja emberi felhasználónként percenként 240 kérés, külön gépihitelesítőadat-keretében percenként 480. Ezek kérési plafonok, nem közzétételi teljesítmény vagy csomagkvóták. Más végpontok és közösségi szolgáltatók külön korlátokat használnak. 429 vagy újrapróbálható 503 esetén kövesd az élő Retry-After fejlécet; ne futtass folyamatos újrapróbálási ciklust.

Korlátozott időközönként olvasd az állapotot, amíg a felhasználó követi a bejegyzést, vagy használd az alkalmazás élő állapotnézetét. Ez az API nem ígér kimenő webhookokat, előfizetői SLA-t, platformonként azonos funkciókat vagy rögzített közzétételi időt.

• Platformképesség-mátrix
• Saját AI-ügynök beállítása