Flowyer

Conectarea asistenților IA externi

Cum conectați ChatGPT, Claude, Gemini, Grok, DeepSeek sau Cursor la Flowyer și ce poate, respectiv ce nu poate face o cheie API.

Referința API pentru dezvoltatori

Despre ce este vorba?

Cu o cheie API personală, un asistent IA extern poate citi și crea înregistrări (dosare, clienți, sarcini, ore lucrate, costuri și documente) în Flowyer în numele dumneavoastră și, acolo unde permiteți, le poate modifica. Fiecare cerere rulează exact cu permisiunile dumneavoastră, restrânse suplimentar de ceea ce permiteți pe cheie; dosarele, clienții și sarcinile create de un bot poartă în liste un marcaj mic cu cheia care le-a creat, iar pentru orele lucrate, costuri și documente cheia care le-a creat este înregistrată, dar o vede numai un administrator al biroului, la "Înregistrări create prin API".

Ce NU poate face o cheie

Nu poate șterge niciodată nimic (o cerere DELETE răspunde întotdeauna 405).
Poate modifica o înregistrare doar prin operațiile și câmpurile PATCH oferite, indicând expected_updated_at al înregistrării (409 la conflict); nimic altceva nu este suprascris.
Poate descărca conținutul unui document doar cu permisiunea separată de descărcare (documents:download), prin linkul semnat, cu valabilitate scurtă, de la documents.download; nu are alt acces la fișiere.
Nu vede niciodată mai mult decât dumneavoastră: restricțiile pe dosare și permisiunile modulelor se aplică neschimbate.

Crearea unei chei API

Un administrator al biroului activează accesul API pentru birou la Setări > Chei API (dezactivat implicit).
Pe aceeași pagină creați o cheie: dați-i un nume (de ex. "ChatGPT") ca să știți mai târziu ce bot identifică fiecare cheie.
Bifați ce poate face botul (citire, creare sau modificare) și setați o expirare. Permisiunile unei chei nu pot fi modificate ulterior: dacă este nevoie de mai mult, creați o cheie nouă.
Cheia este afișată o singură dată: copiați-o în setările asistentului. O puteți revoca oricând, cu efect imediat.

Dați fiecărui bot propria cheie. Pot fi revocate separat, iar listele de dosare, clienți și sarcini arată care dintre ele a creat o înregistrare.

Permisiuni disponibile

matters:read Citire dosare
matters:create Creare dosare
matters:update Modificare dosare
clients:read Citire clienți
clients:create Creare clienți
clients:update Modificare clienți
tasks:read Citire sarcini
tasks:create Creare sarcini
tasks:update Modificare sarcini
workhours:read Citire ore
workhours:create Înregistrare ore
workhours:update Modificare ore
costs:read Citire costuri
costs:create Înregistrare costuri
costs:update Modificare costuri
invoices:read Citire facturi
documents:read Listare documente (doar metadate, fără descărcare)
documents:download Descărcare documente (conținut complet)
documents:create Încărcare documente
documents:update Redenumire documente
colleagues:read Listarea colegilor (doar nume)
knowledge:read Citirea bazei de cunoștințe
knowledge:create Crearea intrărilor în baza de cunoștințe
knowledge:update Modificarea intrărilor în baza de cunoștințe
emails:read Citire e-mailuri dosare
litigation:read Listare istoric litigiu
litigation:create Creare înregistrare istoric litigiu
litigation:update Modificare înregistrare istoric litigiu
mail_register:read Citire corespondență
mail_register:create Creare înregistrări corespondență
mail_register:update Modificare înregistrări corespondență
comments:read Citirea comentariilor dosarului
comments:create Adăugarea de comentarii la dosar
comments:update Editarea propriilor comentarii
trials:read Citire termene de judecată
trials:create Creare termene de judecată
trials:update Modificare termene de judecată
courts:read Listarea instanțelor
hr:read Citirea concediilor (doar date)
calendar:read Citirea evenimentelor din calendar
calendar:create Crearea evenimentelor în calendar
calendar:update Modificarea evenimentelor din calendar
bookings:read Vizualizarea programărilor
bookings:create Crearea de programări (trimite un e-mail clientului)
bookings:update Reprogramarea și editarea programărilor
bookings:send Confirmarea sau anularea programărilor (trimite un e-mail clientului)
tickets:read Citirea tichetelor de asistență
tickets:reply Răspuns la tichete (trimite un e-mail clientului)
tickets:update Modificarea stării tichetului
portal:read Portal client: citirea conversațiilor și a mesajelor
portal:reply Portal client: răspuns către client (trimite un mesaj și un e-mail de notificare)

Conectare

Folosiți întotdeauna exact gazda https care începe cu www. (o redirecționare ar elimina antetul de autorizare). Pentru conexiunile cu cheie API, trimiteți cheia ca "Authorization: Bearer <cheie>"; clienții MCP se autentifică în schimb prin OAuth, conectându-se din browser, așa că nu trebuie introdusă nicio cheie.

URL de bază: https://www.flowyer.ro/api/agent
OpenAPI: https://www.flowyer.ro/api/agent/openapi.json
MCP: https://mcp.flowyer.com/mcp

ChatGPT (Actions)

Într-un GPT personalizat, importați descrierea OpenAPI de mai jos la Actions, alegeți autentificarea cu cheie API de tip "Bearer" și lipiți cheia Flowyer.

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

Grok

Dați-i lui Grok adresa descrierii OpenAPI și cheia; din descriere află ce operații există și ce parametri primesc.

Claude Code

Claude Code se conectează la serverul MCP; la prima utilizare vă conectează din browser (OAuth), fără a fi nevoie de o cheie:

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

Claude Desktop / Cursor / Gemini CLI / DeepSeek

Claude Desktop, Cursor, CLI-ul Gemini și clienții MCP bazați pe DeepSeek folosesc aceeași adresă MCP în fișierul lor de configurare; la prima conectare, clientul vă conectează din browser (OAuth), fără a fi nevoie să introduceți o cheie:

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

REST (curl)

Exemple de apeluri REST directe:

curl -H "Authorization: Bearer flw_..." https://www.flowyer.ro/api/agent/me
curl -H "Authorization: Bearer flw_..." "https://www.flowyer.ro/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.ro/api/agent/clients

Reguli

Reîncercări sigure (Idempotency-Key)

Fiecare creare acceptă un antet Idempotency-Key (sau un câmp idempotency_key): o cerere repetată cu aceeași valoare returnează aceeași înregistrare în loc să creeze alta, iar chei diferite creează întotdeauna înregistrări separate. Fără cheie, o creare identică în decurs de 120 secunde returnează prima înregistrare.

Erori

Fiecare eroare are aceeași formă: un cod (error), un mesaj în engleză (message) și mesajul în limba biroului (message_localized). Mesajul spune ce este de făcut. La 401, 403, 404 și 422 nu are sens să repetați cererea neschimbată, cu două excepții: la 404 upload_not_finished finalizați mai întâi încărcarea la upload_url, apoi apelați din nou complete; la un token de acces OAuth expirat (401 expired_key) reînnoiți mai întâi tokenul.

{
  "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	Semnificație
400	invalid_json, use_www_host, bad_request	Cerere invalidă: corp JSON invalid, gazdă greșită (folosiți gazda www.) sau o cerere ilizibilă.
401	missing_key, invalid_key, revoked_key, expired_key, user_inactive, office_not_found	Cheia lipsește, este invalidă, revocată sau expirată, titularul ei nu mai este activ, ori biroul cheii nu a fost găsit.
403	scope_missing, module_forbidden, forbidden, office_api_disabled, licence_expired, office_archived	Lipsește o permisiune pe cheie sau pe utilizator, ori biroul nu a activat API-ul.
404	not_found, matter_not_visible, unknown_endpoint, upload_not_finished, replay_not_visible	Înregistrarea nu există sau utilizatorul nu o poate vedea; endpoint necunoscut; fișierul încărcat nu a ajuns încă în stocare (upload_not_finished: încărcați-l la upload_url, apoi apelați din nou complete); ori o creare repetată a cărei înregistrare a fost creată anterior, dar între timp a fost ștearsă sau ascunsă (replay_not_visible: nu s-a creat nimic nou, nu o creați din nou).
405	delete_not_allowed, update_not_allowed, method_not_allowed	Ștergerea nu este posibilă prin API; modificarea doar acolo unde descrierea oferă o operație PATCH.
409	client_exists, client_exists_generic, idempotency_key_reused, duplicate_in_progress, record_conflict, record_locked, duplicate_name	Există deja un client cu acel nume; în folder există deja un document cu acel nume (duplicate_name); înregistrarea s-a modificat de când ați citit-o (record_conflict: citiți-o din nou și retrimiteți modificarea cu noul updated_at); înregistrarea a fost facturată sau blocată (record_locked: faceți modificarea în Flowyer); Idempotency-Key a fost folosit pe altă resursă; ori o cerere identică este în curs de procesare.
413	request_too_large, file_too_large	Corpul cererii este prea mare (request_too_large) sau fișierul de încărcat depășește limita (file_too_large; details.max indică limita în octeți).
422	validation_failed, unknown_client, unknown_colleague, blocked_file_type, upload_token_invalid, folder_not_in_matter, document_name_too_long	Un câmp invalid sau lipsă (details.fields arată care); un token de încărcare invalid, deja folosit sau expirat (upload_token_invalid: reluați încărcarea); ori un folder care nu aparține dosarului (folder_not_in_matter).
429	rate_limited, auth_rate_limited	Prea multe cereri (300 pe minut per cheie); antetul Retry-After spune când să reîncercați.
500	server_error	Eroare neașteptată. Cererea a fost înregistrată sub request_id; reîncercați mai târziu și, dacă se repetă, comunicați acest ID asistenței Flowyer.
503	office_maintenance, office_setup_incomplete, temporarily_unavailable	Biroul este temporar indisponibil (întreținere sau configurare în curs); antetul Retry-After spune când să reîncercați.

Confidențialitate

Furnizorul asistentului (de ex. OpenAI, Anthropic, xAI) vede toate datele pe care le returnează cheia. Dați o cheie doar unui bot a cărui prelucrare a datelor a fost acceptată de birou și doar cu permisiunile cu adevărat necesare.