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

Kanonikus URL: https://sosoapi.ai/hu/docs/publishing-api-reference

Építs szerveroldali közzétételi integrációt célhelyenként egy Scheduled Post köré. Ez a referencia a 2026. október 20-án ellenőrzött közzétételi API-szerződést fedi le. A példák helyőrzőket tartalmaznak, és ezen az oldalon nem futnak.

## 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 ezt használják: Authorization: Bearer <your-key> és Content-Type: application/json. 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.

Scheduled Posts végpontok; minden kérés POST

| Útvonal | Kérés | Válasz és hatókör |

| --- | --- | --- |

| /studio-api/scheduled-posts/list | workspace_id; opcionális project_id, status, időpár, limit, cursor. | posts, next_cursor, returned_count. Munkaterületi hatókörű olvasás. |

| /studio-api/scheduled-posts/get | id. | post, delivery, actions, attempts, outcomes. Itt olvasd az aktuális verziót. |

| /studio-api/scheduled-posts/eligibility | workspace_id, targets; opcionális include_quota. | destinations és opcionális quota. Csak olvasási előellenőrzés, nem foglalás. |

| /studio-api/scheduled-posts/create | workspace_id, pontos fiók, provider_payload, content, scheduled_at, idempotency_key. | post és deduped. Új időzítésnél 201; egyező ismétlésnél 200. |

| /studio-api/scheduled-posts/bulk-create | workspace_id és 1–50 targets, mindegyik saját idempotency_key értékkel. | batch_id, successes, failures. Legalább egy sikernél 201; ha egyik sem sikerül, 422. Mindkét tömböt vizsgáld meg. |

| /studio-api/scheduled-posts/update | id, expected_version, patch; opcionális egyező provider_payload. | post. Az elavult verziót elutasítja; a célhely nem módosítható. |

| /studio-api/scheduled-posts/publish-now | id és expected_version. | post. Azonnali végrehajtást kér; nem bizonyítja a közzétételt. |

| /studio-api/scheduled-posts/retry | id, expected_version; opcionális jövőbeli scheduled_at. | post. Csak sikertelen állapotnál, bizonyítékhoz kötött helyreállítás; soha nem vak újraküldés. |

| /studio-api/scheduled-posts/cancel | id és expected_version. | post. Visszavonja a még közzé nem tett munkát; a távoli visszavonás függőben maradhat. |

| /studio-api/scheduled-posts/delete | id és expected_version. | post. A gépi hívók nem törölhetnek már közzétett szolgáltatói tartalmat. |

| /studio-api/scheduled-posts/withdraw-delete | id és expected_version. | post. Visszavon egy leállt, csak ellenőrzésre szolgáló Instagram Login törlési kérést; megtartja a szolgáltatói tartalmat. |

## 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.

A létrehozási kérés mezői és alapértékei

| Mező | Szerződés |

| --- | --- |

| workspace_id / social_account_id | Kötelező UUID-k az engedélyezett munkaterülethez és pontos célhelyhez. |

| provider_payload | Kötelező platformmegkülönböztető és platformspecifikus publish_options. |

| scheduled_at / display_timezone | Kötelező, időeltolást tartalmazó ISO-8601 időpont; érvényes IANA megjelenítési időzóna, alapértéke UTC. |

| idempotency_key | Kötelező, környező szóközök nélküli, 8–160 karakteres karakterlánc, amely ennél a szándéknál állandó. |

| caption / hashtags | A caption lehet null, legfeljebb 5,000 karakter; alapértéke null. A hashtags alapértéke []; legfeljebb 100 darab, 100 karakteres karakterlánc. A szolgáltatói korlátok szigorúbbak lehetnek. |

| media | Alapérték []; legfeljebb 20 regisztrált médiahivatkozás. Mindegyik kind értéke image/video, és kanonikus url értéke van; add meg a kész asset_id értékét. A platformszabályok szigorúbbak lehetnek. |

| link_url | Opcionális URL vagy null. A célhelynek és bejegyzéstípusnak támogatnia kell. |

| local_scheduled_at / schedule_dst_disambiguation | Opcionális pár: helyi idő időeltolás nélkül és exact/earlier/later. Mindkettőt add meg, vagy egyiket sem; a kívánt időponttal és időzónával egyezniük kell. |

| expires_at / automatic_retry_enabled | Opcionális lejárat a scheduled_at után; a null azt jelenti, nincs lejárat. Az automatikus újrapróbálás alapértéke true, és továbbra is a szolgáltatói biztonsági feltételektől függ. |

| project_id / source_ref | Opcionális, null értéket is elfogadó projekt-UUID és hívói származási objektum. Egyik sem változtat jogosultságot. |

```
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.

HTTP-válaszok és hasznos következő lépések

| Állapot | Jelentés és válasz |

| --- | --- |

| 400 | A sémaellenőrzés a kezelőburok helyett success:false értéket és ZodError hibát adhat az error mezőben. Javítsd a mezőhibákat; ha a törzsben nincs request_id, használd az x-request-id értékét. A kezelő szintjén érvénytelen vagy nem támogatott kérések is használhatnak 400-at. |

| 401 / 403 | Hiányzó/lejárt hitelesítő adat vagy megtagadott képesség-, szerepkör-, munkaterület- vagy fiókhozzáférés. A pontos engedélyt vagy tagságot javítsd. |

| 404 | Az erőforrás nem érhető el az engedélyezett hatókörben. Ellenőrizd az azonosságot. |

| 409 | Állapot-/verzió-, idempotencia-, duplikálttartalom- vagy jogosultságütközés. Olvasd újra; ne küldd be vakon ismét. |

| 422 bulk-create esetén | Egyetlen célhely sem sikerült. Vizsgáld meg a failures listát; részleges siker esetén 201 a válasz. |

| 429 | Kérésszám-korlátozás. Kövesd a Retry-After értékét, és tartsd meg ugyanannak a szándéknak az azonosságát. |

| 503 / egyéb 5xx | Átmeneti szolgáltatási vagy belső hiba. Őrizd meg a request_id értéket; bizonytalan módosítás újrapróbálása előtt vizsgáld meg a meglévő állapotot. |

- [Platformképesség-mátrix](https://sosoapi.ai/hu/docs/publishing-capabilities)

- [Saját AI-ügynök beállítása](https://sosoapi.ai/hu/docs/quickstart)