Dezvoltatori

Cheia aplicației — utilizatorul tehnic, drepturile și setările

Crearea cheii unei aplicații conectate, utilizatorul tehnic, drepturile (scopes), seriile, valabilitatea proformei, e-mailurile, plata cu cardul și evenimentele.

Specificația API (JSON)

Cheia se face pe firma care emite documentele (pentru pjAPI.ro: ANY PROJECT SOLUTIONS), din Setări → Integrări → API și chei, de Administratorul firmei.

1. Creează cheia

Chei API → Denumirea cheii (ex. pjAPI.ro) → bifa Aplicație cu utilizator tehnic (implicit bifată) → Creează cheia. Apar X-Ezif-Key (ezk_…) și Secretul (ezs_…): se pun direct în configurarea aplicației (fișierul de configurare sau secretele serverului ei), nu se trimit pe e-mail sau în chat. Secretul se poate afișa din nou doar cu codul 2FA.

Utilizatorul tehnic („pjAPI.ro (aplicație)”): membru al firmei cu rolul Facturare, fără parolă; nu se poate autentifica, nu apare la Platformă → Utilizatori și se dezactivează automat când cheia e revocată. O cheie veche (care emite în numele tău) trece pe utilizator tehnic cu Trece pe utilizator tehnic (Aplicații conectate).

2. Setările aplicației

Aplicații conectate → caseta cheii → Salvează setările aplicației. Fiecare salvare rămâne în Jurnalul de audit.

Setare Ce face pjAPI.ro
Drepturi ce endpoint-uri poate apela cheia; fără drept → 403 MISSING_SCOPE proforma:write, payment:write, documents:read, webhooks:manage
Seria facturilor (din v0.193.4) seria facturilor emise prin POST /invoices fără series și a facturii fiscale emise automat la plata proformei PJ
Seria proformelor seria proformelor (POST /proformas și POST /invoices cu kind: "proforma") fără series PJPF
Alte serii permise (din v0.193.4) seriile pe care cheia le mai poate cere explicit, cu series; orice altă serie → 403 SERIES_NOT_ALLOWED —
Valabilitatea proformei 1–90 de zile (cererea poate trimite valid_days în aceste limite) 15
Reminder după e-mail automat cu linkul de plată, la N zile după emitere, o singură dată; gol = oprit 7
Trimite proforma pe e-mail la emitere, la adresa clientului din cerere: PDF + linkul de plată da
Trimite factura achitată pe e-mail la emiterea automată a facturii da
Plata cu cardul din linkul proformei prin procesatorul firmei (Setări → Procesatori de plăți: Revolut / NETOPIA) da
Evenimente ce webhook-uri primește aplicația (vezi Webhook-urile) toate cele ale proformei + invoice.issued, invoice.spv_*, invoice.storno

Drepturile

Drept Endpoint-uri
proforma:write POST /proformas, /proformas/{id}/cancel, /proformas/{id}/send; POST /invoices cu kind: proforma
invoice:write POST /invoices, /invoices/{id}/storno, /invoices/{id}/convert, /invoices/{id}/shipping
payment:write POST /proformas/{id}/payments, POST /invoices/{id}/payments
documents:read GET /proformas/…, GET /invoices, GET /invoices/…, PDF, /series, /companies/{cui}
items:read GET /items, /items/{sku}, /stock
webhooks:manage POST /callback, /callback/test

Cheile create înainte de v0.42.0 (ex. pluginul WooCommerce) păstrează toate drepturile și primesc doar evenimentele de încasare, ca înainte — nimic nu se schimbă pentru ele până nu le salvezi setările.

3. Revocarea

Chei API → Revocă: cheia nu mai funcționează imediat, utilizatorul tehnic se dezactivează. Super Admin poate revoca orice cheie din Platformă → Sistem → Chei API, cu codul 2FA.

Seriile și documentele cheii (din v0.193.4)

  • Emiterea: cheia emite doar pe seriile ei (seria facturilor, seria proformelor, alte serii permise) — pe toate căile (/invoices, /proformas, conversia proformei). Cererea cu altă serie → 403 SERIES_NOT_ALLOWED, cu seriile cheii în mesaj. Fără series, documentul ia seria cheii pentru tipul lui. O cheie fără nicio serie aleasă emite pe seriile firmei, ca înainte.
  • Citirea: cheia vede doar documentele emise de ea — și pe cele care provin din ele (factura din proformă, storno-ul). GET /invoices, /invoices/{id}, PDF-ul, /invoices/by-external/…, /proformas/…, încasările și storno-ul pe documentul altei aplicații → 404. GET /series întoarce doar seriile cheii.
  • external_id: e unic pe firmă. Același external_id trimis de altă aplicație → 409 EXTERNAL_ID_USED; folosește un prefix propriu aplicației (pluginul WooCommerce îl pune singur: wc-<site>-<comanda>).

Documentația aplicației eZif 0.204.6.