Cheia se face pe firma care emite documentele (pentru pjAPI.ro: ANY PROJECT SOLUTIONS), din 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 Administrare APP → 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 proformelor | seria din care se emite proforma (cererea poate alege alta doar din „seriile permise”) | PJPF |
| Seria facturilor emise la plată | seria facturii fiscale emise automat | PJ |
| 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 (Integră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 |
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 Administrare APP → Integrări (chei API), cu codul 2FA.