Toate secțiunile ghidului

API și webhooks

Chei API, endpoint-uri de citire, notificări webhook semnate și conectarea unui asistent AI prin MCP. API-ul și webhooks sunt în planul Business, iar MCP este inclus în Business sau se adaugă ca modul.

Chei API

  • Din Setări › API și webhooks creezi chei care încep cu sk_live_. Cheia se afișează o singură dată, apoi rămâne doar o amprentă.
  • Endpoint-urile REST sunt doar pentru citire. Cheile au o limită de 120 de cereri pe minut.
  • La creare poți bifa Date sensibile, pentru cheile date unui asistent AI care trebuie să vadă emailurile, telefoanele și IBAN-urile clienților. Fără bifă, aceste câmpuri nu se returnează.
  • Poți revoca o cheie oricând.

Endpoint-uri

  • GET /api/v1/invoices și GET /api/v1/invoices/{id}
  • GET /api/v1/invoices/{id}/pdf
  • GET /api/v1/clients

Autentificarea se face cu antetul Authorization: Bearer <cheia>.

Asistent AI (MCP)

  • MCP este inclus fără cost în planul Business. Pe Start și Pro se adaugă ca modul, cu 12,99 lei pe lună (TVA inclus) și 30 de zile de probă, din meniul Aplicații. Modulul deschide doar serverul MCP și crearea cheilor: API-ul REST și webhooks rămân în Business.
  • Dacă modulul se oprește sau firma trece pe planul Gratuit, cheile nu se șterg, dar serverul MCP răspunde cu o eroare de plan până la reactivare. La trecerea pe Business, modulul plătit iese din abonament, deoarece devine inclus.
  • Socotio are un server MCP la adresa /api/mcp, pe care îl pot folosi Claude, ChatGPT sau Cursor. Adresa exactă și exemplele de configurare apar în Setări › API și webhooks, la „Conectează un asistent AI”.
  • Autentificarea se face cu aceeași cheie API, în antetul Authorization: Bearer <cheia>. Fiecare asistent primește cheia lui.
  • Asistentul citește datele firmei. Nu emite facturi și nu trimite nimic în SPV, iar emiterea rămâne în aplicație.
  • Cu dreptul Ciorne, bifat la crearea cheii, asistentul poate crea clienți, produse și ciorne de factură sau proformă, le poate modifica și șterge doar pe cele create de el și poate verifica o ciornă înainte de emitere. O ciornă creată prin API are o notă pe pagina ei, iar un om o verifică și o emite din aplicație.
  • Scrierile cer o cheie de idempotență, ca o cerere repetată să nu creeze duplicate. Limitele sunt 30 de scrieri pe minut, 300 pe zi și cel mult 200 de ciorne create prin API în același timp. Fiecare scriere apare în jurnal.
  • Pentru un document emis, asistentul poate cere un link către PDF, valabil 15 minute și pentru 5 descărcări. Linkul cere dreptul Date sensibile.
  • Prognoza de numerar (get_cash_flow) folosește doar sumele sigure: facturile neîncasate după scadență, facturile primite neplătite și obligațiile fixate de contabil. Estimările din aplicație nu sunt incluse.
  • Primul pas pentru un asistent este unealta get_organization, care arată firma, planul, modulele active și drepturile cheii.
  • Asistentul poate citi: facturile, încasările, ofertele, facturile recurente, seriile, clienții și produsele, vânzările și restanțele, starea e-Factura, facturile primite din SPV, starea conexiunii ANAF și, dacă modulele sunt active, declarațiile e-Transport, tranzacțiile bancare, riscul partenerilor și starea contabilă. Ghidul de utilizare poate fi citit ca resursă.
  • La creare alegi valabilitatea cheii: 30 de zile, 90 de zile (implicit), un an sau fără expirare. După expirare, cheia primește 401 și se creează alta.
  • Fiecare unealtă se oprește după 25 de secunde. Dacă primești mesajul că a durat prea mult, restrânge perioada sau filtrele.
  • Fiecare apel al unei unelte se înregistrează în pagina de setări, cu unealta, ora și rezultatul, fără conținutul documentelor.

Webhooks

  • Adaugi o adresă HTTPS publică. Adresele private sunt refuzate.
  • Evenimente: factură emisă, factură încasată integral, factură respinsă de ANAF și ciornă creată prin API.
  • Mesajele sunt semnate HMAC, în antetul Socotio-Signature, cu secretul endpoint-ului.
  • Livrarea se face la câteva minute după eveniment, cu 8 reîncercări. Butonul Trimite un test verifică adresa, iar lista livrărilor arată rezultatul fiecăreia.