Chei API și permisiuni

Cheile

Cheile se fac în aplicație, la API și webhookuri, cu contul tău Chappa. Fiecare are un nume (al programului care o folosește) și o listă de firme.

• Cheia arată așa: chf_ urmat de 43 de caractere. O vezi o singură dată, când o faci; noi păstrăm doar o amprentă SHA-256, din care cheia nu se poate reface. Dacă o pierzi, faci alta.
• În listă vezi începutul și sfârșitul ei, când a fost folosită ultima dată și de la ce adresă IP.
• O revoci oricând; din acel moment orice cerere cu ea primește 401 invalid_api_key.
• La fiecare cheie nouă primești un email, ca să afli dacă a făcut-o altcineva.
• Un cont are cel mult 25 de chei active. Fă câte una pentru fiecare program: o revoci pe una fără să le oprești pe celelalte.

Cheia este a contului, nu a unei firme: aceeași cheie poate lucra cu mai multe firme, fiecare cu alte permisiuni. Cererile spun firma în adresă: /companies/{company_id}/….

Permisiunile pe firmă

Pentru fiecare firmă a cheii alegi ce poate face: pentru fiecare resursă nimic, citire sau scriere, plus emiterea, trimiterea în RO e-Factura și ștergerea documentelor.

Ce înseamnă fiecare:

Scrierea include citirea aceleiași resurse, iar orice permisiune pe documente include documents:read. Fără permisiune, cererea primește 403 missing_permission, cu permisiunea lipsă în permission. O cheie de raportare, de exemplu, are doar permisiuni de citire; una pentru magazinul online are documents:write, documents:issue, documents:submit și payments:write pe o singură firmă.

Rolul tău în firmă

O cheie nu poate face mai mult decât poți tu în firmă, acum. Dacă ai rolul de vizualizare, cheia doar citește, orice permisiuni i-ai fi dat. Dacă rolul se schimbă, cheia urmează imediat; GET /companies arată, la fiecare firmă, permisiunile care lucrează acum.

Dacă ieși dintr-o firmă, cheile tale pierd accesul la ea. Dacă ești adăugat din nou mai târziu, accesul nu revine singur: îl dai din nou cheii, din aplicație.

Firme verificate și neverificate

O firmă adăugată în aplicație este neverificată: este a ta (și a celor pe care îi inviți) până când cineva dovedește drepturile SPV pe codul ei fiscal, conectând-o la ANAF cu certificatul digital. Atunci devine verificată: una singură pentru acel cod fiscal, în toată platforma, cu tot istoricul ei.

Emailurile și ANAF cer firma verificată ca nimeni să nu poată trimite facturi în numele unei firme care nu e a lui. Câmpul verified al firmei îți spune unde ești.

Când firma devine verificată

• O verifici tu (Setări, Conexiune ANAF, în aplicație): firma își păstrează id-ul, cheile merg mai departe fără nicio schimbare și primești evenimentul company.verified. De acum trimite și în RO e-Factura.
• Codul fiscal era deja verificat pe Chappa, de altcineva: după propria ta dovadă SPV intri în firma verificată și îți poți muta acolo copia, din aplicație. La mutare, cheile și webhookurile tale trec pe firma verificată, cu aceleași permisiuni, limitate de rolul tău acolo; cererile pe vechiul id primesc 410 company_merged, cu noul id în merged_into, și primești evenimentul company.merged. Documentele își păstrează id-urile.
• O verifică altcineva din copia ta: cei care erau în copie fără dovadă SPV ies din ea, iar cheile lor pierd accesul. Intră înapoi printr-o invitație de la un administrator verificat sau prin propria dovadă, apoi dau din nou acces cheilor.

Păstrarea cheilor

• Doar pe server, într-o variabilă de mediu sau într-un manager de secrete. Niciodată în codul din browser, într-o aplicație de telefon sau într-un depozit de cod.
• Dă fiecărei chei doar firmele și permisiunile de care are nevoie programul ei.
• Ca s-o schimbi fără întrerupere: faci una nouă, o pui în program, apoi o revoci pe cea veche.
• Dacă a scăpat undeva, revoc-o imediat. Prefixul chf_ o face ușor de găsit de scannerele de secrete.

Referința

{
  "id": 7,
  "object": "company",
  "kind": "pj",
  "cif": "47755081",
  "fiscal_code": "RO47755081",
  "name": "Alfa Soft SRL",
  "reg_com": "J40/1234/2023",
  "address": "Bd. Unirii 1",
  "city": "Sector 4",
  "county": "București",
  "country": "RO",
  "vat_payer": true,
  "vat_on_collection": false,
  "verified": true,
  "efactura": { "applies": true, "connected": true, "submit_mode": "manual", "submit_delay_hours": 24 },
  "default_currency": "RON",
  "default_due_days": 14,
  "track_payments": true,
  "role": "verified",
  "permissions": ["documents:read", "documents:write", "documents:issue", "documents:submit", "payments:read", "payments:write"]
}

Obiectul ApiKey

Cheia cu care faci cererea.

Obiectul Company

O firmă (sau un PFA, o persoană fizică) la care ajunge cheia.

Obiectul CompanyDetail

Firma, cu ce îți trebuie ca să emiți: Company plus: