RO e-Factura în aplicația ta, într-o oră

Cum vorbești cu iframe-ul

Pagina ta și iframe-ul își trimit mesaje JSON prin postMessage, ca cererile și răspunsurile unui API HTTP. Tu trimiți cereri (produsele tale, o factură precompletată, emiterea, PDF-ul) și iframe-ul răspunde la fiecare; când se întâmplă ceva (factură emisă, validată de ANAF, încasată), îți trimite un eveniment. Le trimiți și le citești cum vrei, din orice framework.

Adresa iframe-ului are ?api. Un schimb întreg, de la deschidere până la factura validată (→ trimiți tu, ← primești):

← { "chappa": "facturare/1", "kind": "event", "type": "ready", "payload": { "protocol": "facturare/1" } }

→ { "chappa": "facturare/1", "kind": "request", "id": "1", "type": "init",
    "payload": { "assertion": "eyJhbGciOiJFUzI1NiIs…" } }
← { "chappa": "facturare/1", "kind": "response", "id": "1",
    "payload": { "ok": true, "result": { "mode": "integrator", "user": { … }, "entities": [ … ], … } } }

→ { "chappa": "facturare/1", "kind": "request", "id": "2", "type": "newInvoice",
    "payload": { "client": { "name": "Beta SRL", "cui": "RO18547290", "city": "Sector 3", "county": "București" },
                 "lines": [{ "name": "Abonament lunar", "quantity": 1, "unitPrice": 250, "vatRate": 21 }] } }
← { "chappa": "facturare/1", "kind": "response", "id": "2",
    "payload": { "ok": true, "result": { "documentId": 812 } } }

← { "chappa": "facturare/1", "kind": "event", "type": "document.accepted",
    "payload": { "id": 812, "number": "FCT0042", "stage": "accepted", … } }

Trimiți cu iframe.contentWindow.postMessage(mesaj, 'https://facturare.chappa.ro') și primești în addEventListener('message', …). Regulile sunt la mesaje; cererile, evenimentele și erorile au câte un tabel.

Fără assertion în init, utilizatorii intră cu contul Chappa, ca la iframe-ul simplu; atunci pagina ta poate doar asculta evenimentele și schimba ecranul. view din init alege ecranul de pornire, iar theme aspectul.

Endpointul de aserțiuni

Pagina ta cere aserțiunea de la propriul server, în sesiunea utilizatorului tău. Reguli:

• Doar pentru utilizatorul autentificat în aplicația ta, cu sub luat din sesiune, niciodată din parametri trimiși de browser.
• POST + verificarea originii (sau tokenul CSRF pe care îl folosești deja). Fără CORS: alte site-uri nu au ce citi.
• Răspuns text/plain cu aserțiunea, Cache-Control: no-store.
• Expirare scurtă (2 până la 5 minute) și un jti nou de fiecare dată. Când sesiunea din iframe expiră, iframe-ul trimite assertion_required, iar pagina ta răspunde cu authenticate și o aserțiune nouă.

// Express, exemplu
app.post('/chappa/assertion', requireLogin, (req, res) => {
  if (req.get('Origin') !== 'https://app.exemplu.ro') return res.sendStatus(403);
  res.set('Cache-Control', 'no-store').type('text/plain')
     .send(chappaAssertion(req.user, 'https://app.exemplu.ro'));
});

Mesajele

Plicul, în ambele sensuri:

{ "chappa": "facturare/1", "kind": "request" | "response" | "event", "id": "…", "type": "…", "payload": { … } }

• Iframe-ul are adresa https://facturare.chappa.ro/embed/?api: ?api îi spune că pagina ta vorbește cu el. Când e gata, trimite ready (cu targetOrigin *, doar cu versiunea protocolului).
• Ascultă mesajele înainte să pui adresa iframe-ului, ca să nu pierzi ready.
• Prima cerere trebuie să fie init; ce trimiți cât timp rulează init se tratează după el, în ordine. Originea paginii care o trimite devine fixă: iframe-ul ignoră orice mesaj din altă origine sau de la altă fereastră decât window.parent și răspunde doar acelei origini.
• Tu verifici la rândul tău: event.source === iframe.contentWindow și event.origin === 'https://facturare.chappa.ro'; trimite cu targetOrigin https://facturare.chappa.ro.
• id îl alegi tu, unic pentru fiecare cerere. Răspunsul: { "ok": true, "result": … } sau { "ok": false, "error": { "code", "message", "details"? } }, cu același id.

Cereri

Unitățile de măsură sunt coduri UN/ECE (H87 bucată, HUR oră, DAY, MON, KGM, LTR, MTR, C62…). Cotele de TVA: vatRate în procente (21, 11); categoriile: S standard, Z cotă zero, E scutit, AE taxare inversă, K intracomunitar, G export.

O linie cu preț în altă monedă primește currency (de exemplu un serviciu în EUR pe o factură în lei): o transformăm la cursul BNR valabil la data facturii, iar pe factură apare prețul în moneda ei. La o factură recurentă, conversia se face din nou la fiecare dată.

Încasarea la emitere: paid: true marchează factura ca încasată integral, prin paymentMethod (bon_fiscal, numerar, card, ordin_plata, cec, altul). La emitere se înregistrează plata; numerar emite și chitanța, iar bon_fiscal trimite factura în RO e-Factura ca factură pe bon fiscal (tip 751). Fără paid, paymentMethod este modul de plată așteptat.

Evenimente

Erori