Posty fejlesztői erőforrások: API, MCP, OpenAPI, CLI

A Posty ütemezőjét négy programozható felületen éred el: nyilvános REST API, MCP-szerver, parancssori eszköz és webhookok. Mind ugyanazt a fiókot kezeli, ugyanazokkal a jogosultságokkal, amiket a webes felületen látsz. Ez az oldal a hivatkozási pont, a kliensenkénti beállításokat az AI-ügynökök oldal írja le.

Egy pillantásra

Nyilvános REST API

A REST API az https://api.posty.hu címen válaszol, a nyilvános útvonalak pedig a /public/v1 előtag alatt vannak. Ugyanazt a munkaterületet kezeli, mint a webes felület, csak közvetlenül a kódodból.

Hitelesítés

Minden kérés egy API-kulcsot visz az Authorization fejlécben. A kulcsot a Postyban, az Automatizálások → Fejlesztőknek oldalon hozod létre, ehhez nem kell hozzánk írnod. A kulcs a létrehozás pillanatában egyszer látszik, utána már nem kérdezhető vissza, ezért mentsd el rögtön. A kulcsok szűkíthetők: a jogosultságuk a tulajdonos aktuális szerepkörével együtt mozog, és a munkaterületről kikerülő felhasználó kulcsa megszűnik működni.

Ha egy kulcs több munkaterülethez tartozik, a showorg fejléc választja ki, melyikre vonatkozik a hívás.

Amit a v1 tud

• Bekötött közösségi fiókok listázása: GET https://api.posty.hu/public/v1/integrations
• Poszt létrehozása és ütemezése: POST https://api.posty.hu/public/v1/posts
• Naptár lekérdezése, módosítás, törlés: GET https://api.posty.hu/public/v1/posts, DELETE https://api.posty.hu/public/v1/posts/:id
• Médiafeltöltés fájlból vagy URL-ből: POST https://api.posty.hu/public/v1/upload, POST https://api.posty.hu/public/v1/upload-from-url
• Böngészős feltöltési link, ha a fájl a felhasználó eszközén van: POST https://api.posty.hu/public/v1/upload-link, GET https://api.posty.hu/public/v1/upload-link/:id
• Következő szabad időpont keresése: GET https://api.posty.hu/public/v1/find-slot/:id
• Statisztikák csatornára és posztra: GET https://api.posty.hu/public/v1/analytics/:integration

Állapot és felderítés hitelesítés nélkül

A GET https://api.posty.hu/public/v1/status az egyetlen útvonal, amely kulcs nélkül is válaszol. Megadja az API verzióját, a szerver pontos idejét UTC-ben, és abszolút címmel minden gépi olvasásra szánt dokumentumot: az OpenAPI-leírást, az OAuth-metaadatokat, az MCP-végpontot. Munkaterületi adatot nem ad vissza, és paramétert sem fogad. Egy ügynök ezzel tudja a leggyorsabban eldönteni, hogy elér-e minket, és hol keresse a többit.

Hibák

Minden hiba JSON-t ad vissza. A Posty által kiváltott hibákban a msg mező hordozza az emberi mondatot; a kérés formai ellenőrzésén elbukó hívások a keretrendszer alakját kapják (statusCode, message, error). A jogosultsági 403 megnevezi a hiányzó scope-ot és a kulcs tulajdonosának aktuális szerepkörét, mert a leggyakoribb ok nem a rosszul létrehozott kulcs, hanem a lefokozott felhasználó. Az OpenAPI dokumentum ApiError sémája mindezt géppel olvashatóan leírja, státuszkódonként azzal együtt, hogy érdemes-e újrapróbálni.

Hívási korlátok

Minden válasz viszi a RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (másodpercben) és RateLimit-Policy fejléceket, útvonalanként külön kerettel. A 429 mellé Retry-After is érkezik. Ne a 429-re várj: a maradék értékből előre tudsz lassítani.

Verziózás és kivezetés

A verzió az útvonalban van, minden nyilvános hívás a /public/v1 alatt él. Törő változás új verzióként jelenne meg (/public/v2), a v1 pedig tartja a szerződését. Bővítés (új opcionális mező, új útvonal, új felsorolt érték) a v1-en belül történik, ezért az ügyfélkódod hagyja figyelmen kívül azokat a mezőket, amelyeket nem ismer.

Ha egy útvonalat kivezetnénk, a válasza Deprecation: true fejlécet kap, mellette Sunset fejlécben azzal a dátummal, ami után már nem működik, és egy Link fejlécben a részletekkel. A Sunset dátum soha nem lehet közelebb 180 napnál az első Deprecation fejléctől számítva. Jelenleg semmi nincs kivezetés alatt.

MCP-szerver

Az MCP-szerver címe https://api.posty.hu/mcp, streamable HTTP átvitellel. Az ügynököd ezen keresztül ugyanazokat a csatornákat látja és ugyanabba a naptárba ütemez, mint te.

• Kulcs kliensekhez: psty_mcp_… kezdetű MCP-kulcs, a Automatizálások → Fejlesztőknek oldalról. A psty_… kezdetű REST-kulcsokat az MCP-szerver szándékosan visszautasítja, és meg is mondja, miért.
• Kulcs alkalmazásokhoz: pos_… kezdetű OAuth hozzáférési token. Ez lejár, frissíthető, és csak arra a címre érvényes, amelyre kiállították.
• Kész beállítási blokkot a Claude, a ChatGPT, a Muse, a Hermes és az OpenClaw kliensekhez az Automatizálások → Fejlesztőknek oldalon másolsz ki, a leírásuk pedig az AI-ügynökök oldalon van.

Parancssori eszköz

A posty-cli csomag az npm-en van kiadva. Telepítés: npm install -g posty-cli, a parancs neve pedig posty. Belépés böngészős jóváhagyással: posty auth:login.

A csomagban ott van a SKILL.md, amely minden parancsot és kapcsolót leír. Egy ügynök, amelynek van shellje, ebből tanulja meg a használatot, weboldal olvasása nélkül. A CLI a JSON-választ a szabványos kimenetre, az állapotot és a hibákat a hibakimenetre írja, sikertelen futásnál pedig nem nullával lép ki, így a hívó program tudja, mi történt.

Előfizetés ügynökökön keresztül

Egy ügynök (Claude, a CLI vagy egy REST-kliens) végig tudja vinni a felhasználót a „fizess elő a Pro éves csomagra” mondattól az élő előfizetésig. Egyetlen lépés marad emberi: a fizetés jóváhagyása a Stripe Checkout oldalán, ahol a Link a kereskedő. Az ügynök csomagot mutat, linket kér, és fizetés után ellenőrzi, hogy a csomag él.

• Fiók nélkül is indulhat: az OAuth-hozzájárulás oldaláról a belépés és a regisztráció (e-mail vagy Google) után a felhasználó ugyanahhoz a hozzájárulási kéréshez tér vissza. MCP-eszköz a regisztrációhoz nincs; REST-en és a CLI-ben az ügynök fiókot is létrehozhat, lásd lent.
• MCP: get_plans (a négy csomag ára és korlátai), subscribe (Stripe Checkout link a választott csomagra), get_subscription (állapot, fizetés után ezzel erősíti meg az ügynök), manage_subscription (Stripe számlázási portál: csomagváltás, lemondás, számlák, kártya). Ezek az egyetlen eszközök, amelyek csomagot nevezhetnek meg, és csak akkor hívhatók, ha a felhasználó kérdezett róluk.
• REST: GET /plans, GET /subscription, POST /subscriptions/checkout, GET /subscription/portal. CLI: posty billing:plans, posty billing:subscribe --tier pro --period yearly, posty billing:status, posty billing:manage.
• A fizetés a Stripe Checkoutban történik, a felhasználó saját Link-tárcájával vagy kártyájával. Az ügynök soha ne fizessen egyszer használatos vagy ügynök által kiállított kártyával: a Posty-előfizetés havonta vagy évente megújul, és az egyszer használatos kártya az első megújításnál elbukik, ami a csomag megszűnését jelenti.
• Egy munkaterület, amelynek csomagjában még nincs API-hozzáférés, az MCP-kapcsolaton csak ezt a négy eszközt kapja; fizetés után a többi a következő eszközlistával megjelenik. A subscribe és a manage_subscription csak bejelentkezéssel (OAuth) létesített kapcsolaton, a munkaterület fizetőjének érhető el; a REST-oldalon OAuth-token vagy teljes munkaterületi psty_sa_ kulcs kell hozzá. A ChatGPT-felületen a négy előfizetési eszköz egyike sem érhető el; ott a posty.hu oldalon lehet előfizetni.

Fiók létrehozása ügynökkel

Egy ügynök (a CLI, egy szkript vagy egy REST-eszközzel dolgozó asszisztens) böngésző nélkül is létrehozhat Posty-fiókot a felhasználónak. A fiók valódi és aktivált, a felhasználóé; az ügynök egy teljes munkaterületi kulcsot kap hozzá.

• Kód e-mailben: a POST /signup/start egyszer használatos kódot küld a felhasználó címére. A felhasználó felolvassa a kódot az ügynöknek, az ügynök pedig a POST /signup/complete hívással befejezi a regisztrációt. A kód 10 percig érvényes.
• A felhasználónak el kell fogadnia a feltételeket: az ügynök megmutatja neki az ÁSZF és az adatkezelési tájékoztató linkjét, és csak a beleegyezése után küldi el az acceptTerms: true mezőt. A hozzájárulást ugyanúgy rögzítjük, mint a webes regisztrációnál.
• Az így létrehozott fióknak nincs ingyenes próbaideje. A következő lépés a checkout: GET /plans, majd POST /subscriptions/checkout, és a felhasználó a Stripe oldalán fizet. Az API és az MCP csak olyan csomaggal nyílik meg, amelyben benne van: a GET /plans válaszában apiAndMcpAccess: true. Az Alap csomagban nincs benne, ezért ha a felhasználó azt választja, az ügynök előre szóljon neki, hogy a kulccsal fizetés után sem érheti el az API-t. A csatornákat a felhasználó köti be a webes felületen.
• Ha a címhez már van fiók, új nem jön létre: a felhasználó a posty auth:login paranccsal vagy OAuth-kapcsolattal lép be. A böngészőben regisztráló felhasználó próbaideje változatlan.
• CLI: posty auth:signup --email [email protected], utána posty billing:plans és posty billing:subscribe --tier pro --period yearly.

Webhookok

A webhookokat a Postyban állítod be, és minden kézbesítés alá van írva. Az aláírás az X-Posty-Signature fejlécben érkezik, t=<unix másodperc>,v1=<hex hmac-sha256> alakban. Ez szándékosan ugyanaz a forma, mint a Stripe aláírása, így a meglévő ellenőrző könyvtárak működnek vele.

• Az aláírás a nyers kéréstörzsre készül. Ha a kereted előbb JSON-ra alakítja és újra sorosítja, más karakterláncot kapsz, és az ellenőrzés elbukik.
• Az időbélyeg az aláírás része, ez a visszajátszás elleni védelem. A tűréshatár 300 másodperc.
• Az aláíró titkot a webhook létrehozásakor kapod meg, és a Postyban bármikor újragenerálhatod.

OAuth-alkalmazások

Ha nem a saját fiókodat kezeled, hanem másokét egy alkalmazásból, OAuth-ot használsz. Az engedélyezés authorization code folyamattal megy, és a következők kötelezőek.

• PKCE S256 kihívás minden kérésnél. Titok nélküli kliens is regisztrálható, de PKCE nélkül nem.
• A redirect_uri pontos egyezés a regisztrált listával.
• A tokenek lejárnak, a frissítő tokent pedig rotáljuk. Csak a hasított formájukat tároljuk.
• A token azokra a scope-okra jó, amikhez a felhasználó hozzájárult, és ezt minden híváskor metszük a felhasználó aktuális szerepkörével. Egy visszaminősítés a következő híváson érvényesül.
• Alkalmazást a munkaterület SUPERADMIN szerepű tagja engedélyezhet.

Hozzáférés és első lépések

A folyamat végig önkiszolgáló, nem kell hozzá értékesítővel beszélned és nem kell demót kérned.

• Regisztrálsz a /regisztracio oldalon. A regisztráció ingyenes.
• Bekötöd a közösségi fiókjaidat a szokásos OAuth-folyamattal.
• Kulcsot készítesz az Automatizálások → Fejlesztőknek oldalon: API-kulcsot a REST API-hoz és a CLI-hez, MCP-kulcsot a chatklienshez.
• Minden csomag 7 napos ingyenes próbával indul. A próba indításához bankkártyát kérünk, de a próba alatt nem vonunk le semmit, ma 0 Ft fizetendő, és a vége előtt bármikor lemondhatod. Az árakat az árak szakasz mutatja.

Gépi olvasásra

Ha ügynököt írsz, ne HTML-t elemezz. A honlap minden nyilvános oldalának van Markdown változata: tedd a .md végződést az útvonal végére, a főoldal pedig /index.md.

Ha elakadsz

Írj a [email protected] címre, vagy használd a Segítség oldal űrlapját. Munkanapokon általában egy napon belül válaszolunk.