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 → 403SERIES_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șiexternal_idtrimis de altă aplicație → 409EXTERNAL_ID_USED; folosește un prefix propriu aplicației (pluginul WooCommerce îl pune singur:wc-<site>-<comanda>).