Flowyer

Külső AI-asszisztensek csatlakoztatása

Hogyan köthet ChatGPT-t, Claude-ot, Geminit, Grokot, DeepSeeket vagy Cursort a Flowyerhez, és mire képes, illetve mire nem képes egy API-kulcs.

Fejlesztői API-referencia

Mi ez?

Egy személyes API-kulccsal egy külső AI-asszisztens az Ön nevében olvashat és hozhat létre rekordokat (ügyeket, ügyfeleket, teendőket, munkaórákat, költségeket és dokumentumokat) a Flowyerben, és ahol Ön engedélyezi, módosíthatja is azokat. Minden kérés pontosan az Ön jogosultságaival fut, a kulcsnál megadott szűkítéssel; a bot által létrehozott ügyeken, ügyfeleken és teendőkön a listákban kis jelölés mutatja, melyik kulcs hozta létre őket, a munkaóráknál, költségeknél és dokumentumoknál pedig a létrehozó kulcs rögzítve van, de csak az iroda adminisztrátora látja, az "API-n létrehozott rekordok" résznél.

Mire NEM képes a kulcs

Törölni semmit nem tud (a DELETE kérés mindig 405-tel tér vissza).
Rekordot csak a felkínált PATCH műveletekkel és mezőkkel módosíthat, a rekord expected_updated_at értékének megadásával (ütközéskor 409); mást nem írhat át.
Dokumentum tartalmát csak a külön letöltési jogosultsággal (documents:download), a documents.download rövid életű, aláírt hivatkozásával töltheti le; a fájlokhoz más úton nem fér hozzá.
Sosem lát többet, mint Ön: az ügyekhez kapcsolódó hozzáférési korlátozások (kínai fal) és a modul-jogosultságok ugyanúgy érvényesek.

API-kulcs létrehozása

Az iroda adminisztrátora a Beállítások > API-kulcsok oldalon engedélyezi az API-használatot az irodában (alapból ki van kapcsolva).
Ön ugyanitt létrehoz egy kulcsot: adjon neki nevet (pl. "ChatGPT"), hogy később tudja, melyik botot melyik kulcs azonosítja.
Jelölje be, mit tehessen a bot (olvasás, létrehozás vagy módosítás), és állítson lejáratot. A kulcs jogosultságai később nem módosíthatók: ha többre van szükség, hozzon létre új kulcsot.
A kulcs csak egyszer jelenik meg: másolja ki és adja meg az asszisztens beállításaiban. Visszavonni bármikor tudja, az azonnal hatályos.

Minden botnak külön kulcsot adjon. Így külön visszavonhatók, és az ügyek, az ügyfelek és a teendők listájában látszik, melyik hozta létre az adott rekordot.

Választható jogosultságok

matters:read Ügyek olvasása
matters:create Ügy létrehozása
matters:update Ügy módosítása
clients:read Ügyfelek olvasása
clients:create Ügyfél létrehozása
clients:update Ügyfél módosítása
tasks:read Teendők olvasása
tasks:create Teendő létrehozása
tasks:update Teendő módosítása
workhours:read Munkaórák olvasása
workhours:create Munkaóra rögzítése
workhours:update Munkaóra módosítása
costs:read Költségek olvasása
costs:create Költség rögzítése
costs:update Költség módosítása
invoices:read Számlák olvasása
documents:read Dokumentumok listázása (csak adatok, letöltés nélkül)
documents:download Dokumentumok letöltése (teljes tartalom)
documents:create Dokumentum feltöltése
documents:update Dokumentum átnevezése
colleagues:read Kollégák listázása (csak nevek)
knowledge:read Tudásbázis olvasása
knowledge:create Tudásbázis-bejegyzés létrehozása
knowledge:update Tudásbázis-bejegyzés módosítása
emails:read Ügyek e-mailjeinek olvasása
litigation:read Pertörténet listázása
litigation:create Pertörténeti bejegyzés létrehozása
litigation:update Pertörténeti bejegyzés módosítása
mail_register:read Postakönyv olvasása
mail_register:create Postakönyvi tétel létrehozása
mail_register:update Postakönyvi tétel módosítása
comments:read Ügy hozzászólások olvasása
comments:create Hozzászólás írása ügyhöz
comments:update Saját hozzászólás módosítása
trials:read Tárgyalások olvasása
trials:create Tárgyalás létrehozása
trials:update Tárgyalás módosítása
courts:read Bíróságok listázása
hr:read Szabadságon lévők listázása (csak dátumok)
calendar:read Naptáresemények olvasása
calendar:create Naptáresemények létrehozása
calendar:update Naptáresemények módosítása
bookings:read Időpontfoglalások megtekintése
bookings:create Időpontfoglalás létrehozása (e-mailt küld az ügyfélnek)
bookings:update Foglalások átütemezése és szerkesztése
bookings:send Foglalások visszaigazolása vagy lemondása (e-mailt küld az ügyfélnek)
tickets:read Ügyfélszolgálati jegyek olvasása
tickets:reply Válasz jegyre (e-mailt küld az ügyfélnek)
tickets:update Jegy státuszának módosítása
portal:read Ügyfélportál: beszélgetések és üzenetek olvasása
portal:reply Ügyfélportál: válasz az ügyfélnek (üzenetet és értesítő e-mailt küld)

Csatlakozás

Mindig pontosan a www. kezdetű, https hostot használja (az átirányítás eldobná a hitelesítő fejlécet). Az API-kulcsos csatlakozásoknál a kulcsot az "Authorization: Bearer <kulcs>" fejlécben küldje; az MCP-kliensek ehelyett OAuth-tal, a böngészőben történő bejelentkezéssel hitelesítenek, kulcsot nem kell beírni.

Alap-URL: https://www.flowyer.hu/api/agent
OpenAPI: https://www.flowyer.hu/api/agent/openapi.json
MCP: https://mcp.flowyer.com/mcp

ChatGPT (Actions)

Egy egyedi GPT-ben az Actions résznél importálja az alábbi OpenAPI-leírást, hitelesítésnek válassza az API-kulcsot "Bearer" típussal, és illessze be a Flowyer-kulcsot.

https://www.flowyer.hu/api/agent/openapi.json

Grok

Adja meg a Groknak az OpenAPI-leírás címét és a kulcsot; a leírásból megtudja, mely műveletek érhetők el és milyen paraméterekkel.

Claude Code

A Claude Code az MCP-szerverhez csatlakozik; első használatkor a böngészőben jelentkezik be (OAuth), kulcsot nem kell megadni:

claude mcp add --transport http flowyer https://mcp.flowyer.com/mcp

Claude Desktop / Cursor / Gemini CLI / DeepSeek

A Claude Desktop, a Cursor, a Gemini CLI és a DeepSeeket futtató MCP-kliensek ugyanezt az MCP-címet várják a konfigurációs fájlban; első csatlakozáskor a kliens a böngészőben jelentkezteti be Önt (OAuth), kulcsot nem kell beírni:

{
  "mcpServers": {
    "flowyer": {
      "url": "https://mcp.flowyer.com/mcp"
    }
  }
}

REST (curl)

Közvetlen REST-hívásra példák:

curl -H "Authorization: Bearer flw_..." https://www.flowyer.hu/api/agent/me
curl -H "Authorization: Bearer flw_..." "https://www.flowyer.hu/api/agent/matters?q=2026/0025"
curl -X POST -H "Authorization: Bearer flw_..." -H "Content-Type: application/json" \
     -H "Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f" \
     -d '{"name":"Kovács Kft.","email":"info@kovacs.hu"}' https://www.flowyer.hu/api/agent/clients

Szabályok

Ismételt létrehozás (Idempotency-Key)

Minden létrehozás elfogad egy Idempotency-Key fejlécet (vagy idempotency_key mezőt): ugyanazzal az értékkel megismételt kérés ugyanazt a rekordot adja vissza, nem hoz létre újat, eltérő kulcsok pedig mindig külön rekordot hoznak létre. Kulcs nélkül is védett: egy azonos tartalmú létrehozás 120 másodpercen belül az első rekordot adja vissza.

Hibák

Minden hiba azonos szerkezetű: gépi kód (error), angol üzenet (message) és az iroda nyelvén írt üzenet (message_localized). Az üzenet megmondja, mi a teendő. 401, 403, 404 és 422 esetén a változatlan kérést nincs értelme újrapróbálni, két kivétellel: 404 upload_not_finished esetén előbb fejezze be a feltöltést az upload_url címre, majd hívja meg újra a complete műveletet; egy OAuth-hozzáférési token lejártakor (401 expired_key) pedig előbb frissítse a tokent.

{
  "error": "scope_missing",
  "message": "This API key does not have the \"clients:create\" permission. ...",
  "message_localized": "Ehhez az API-kulcshoz nem tartozik \"clients:create\" jogosultság. ...",
  "locale": "hu",
  "details": { "required_scope": "clients:create" }
}

HTTP	error	Jelentés
400	invalid_json, use_www_host, bad_request	Hibás kérés: érvénytelen JSON-törzs, rossz host (a www. kezdetűt használja), vagy nem értelmezhető kérés.
401	missing_key, invalid_key, revoked_key, expired_key, user_inactive, office_not_found	A kulcs hiányzik, érvénytelen, visszavont vagy lejárt, a tulajdonosa már nem aktív, vagy a kulcshoz tartozó iroda nem található.
403	scope_missing, module_forbidden, forbidden, office_api_disabled, licence_expired, office_archived	Hiányzó jogosultság a kulcson vagy a felhasználón, vagy az iroda nem engedélyezte az API-t.
404	not_found, matter_not_visible, unknown_endpoint, upload_not_finished, replay_not_visible	A rekord nem létezik, vagy a felhasználó nem láthatja; ismeretlen végpont; a feltöltött fájl még nem érkezett meg a tárhelyre (upload_not_finished: töltse fel az upload_url címre, majd hívja meg újra a complete műveletet); vagy egy megismételt létrehozás, amelynek rekordja korábban már létrejött, de azóta törölték, vagy nem látható (replay_not_visible: új rekord nem jött létre, ne hozza létre újra).
405	delete_not_allowed, update_not_allowed, method_not_allowed	Törlés az API-n keresztül nem lehetséges; módosítani csak ott lehet, ahol a leírás PATCH műveletet kínál.
409	client_exists, client_exists_generic, idempotency_key_reused, duplicate_in_progress, record_conflict, record_locked, duplicate_name	Már létező ügyfélnév; ugyanilyen nevű dokumentum ugyanabban a mappában (duplicate_name); a rekord megváltozott, mióta beolvasta (record_conflict: olvassa be újra, és küldje el a módosítást az új updated_at értékkel); a rekordot kiszámlázták vagy zárolták (record_locked: a változtatást a Flowyerben végezze el); más típusú rekordnál már használt Idempotency-Key; vagy épp feldolgozás alatt lévő azonos kérés.
413	request_too_large, file_too_large	A kérés törzse túl nagy (request_too_large), vagy a feltöltendő fájl nagyobb a megengedettnél (file_too_large; a details.max mutatja a korlátot bájtban).
422	validation_failed, unknown_client, unknown_colleague, blocked_file_type, upload_token_invalid, folder_not_in_matter, document_name_too_long	Hibás vagy hiányzó mező (a details.fields mutatja, melyik); érvénytelen, már felhasznált vagy lejárt feltöltési token (upload_token_invalid: kezdje újra a feltöltést); vagy a mappa nem ehhez az ügyhöz tartozik (folder_not_in_matter).
429	rate_limited, auth_rate_limited	Túl sok kérés (kulcsonként 300 / perc); a Retry-After fejléc mondja meg, mikor próbálja újra.
500	server_error	Váratlan hiba. A kérést a request_id azonosítóval naplóztuk; próbálja újra később, és ha ismétlődik, ezzel az azonosítóval jelezze a Flowyer ügyfélszolgálatának.
503	office_maintenance, office_setup_incomplete, temporarily_unavailable	Az iroda átmenetileg nem érhető el (karbantartás vagy folyamatban lévő beállítás); a Retry-After fejléc mondja meg, mikor próbálja újra.

Adatvédelem

Az asszisztens szolgáltatója (pl. OpenAI, Anthropic, xAI) látja az összes adatot, amit a kulcs visszaad. Csak olyan botnak adjon kulcsot, amelynek adatkezelését az iroda elfogadta, és csak a tényleg szükséges jogosultságokkal.