Cu utilizatorii tăi

Cum funcționează

Utilizatorii tăi sunt deja autentificați în aplicația ta. Când serverul tău randează pagina cu facturarea, semnează o aserțiune: un text scurt care spune cine e utilizatorul, semnat cu cheia ta privată. O pune în adresa iframe-ului, după #:

<iframe src="https://facturare.chappa.ro/embed/#assertion=eyJhbGciOiJFUzI1NiIs…"
        width="100%" height="820" style="border:0" allow="clipboard-write"
        title="Facturare"></iframe>

Iframe-ul citește aserțiunea, o șterge din adresă, verifică semnătura la noi și deschide sesiunea utilizatorului tău. Nu există niciun apel de la serverul tău la noi și niciun rând de JavaScript în pagina ta.

Ce e după # nu pleacă din browser: nu ajunge în jurnalele vreunui server și nu se trimite altor site-uri. Aserțiunea e valabilă câteva minute și se poate folosi o singură dată (securitate).

Pașii

1. Cheile. O pereche EC P-256 pe serverul tău, generată o dată (comenzile).
2. Funcția care semnează. Copiezi una dintre funcțiile gata scrise, în Node.js, Python, PHP sau C#. Nu are dependențe.
3. Pagina cu facturarea. Randezi iframe-ul cu o aserțiune nouă, ca mai jos.
4. Deschizi pagina. Integrarea apare singură, în mod test, fără cont la noi. O înregistrezi când ești gata, fără să schimbi codul.

Pagina cu facturarea

<?php
require __DIR__ . '/chappa_assertion.php';   // funcția din /dezvoltatori/asertiunea
header('Cache-Control: no-store');
$a = chappa_assertion((string) $user->id, $user->name, 'https://app.exemplu.ro');
?>
<iframe src="https://facturare.chappa.ro/embed/#assertion=<?= $a ?>"
        width="100%" height="820" style="border:0" allow="clipboard-write" title="Facturare"></iframe>

import { chappaAssertion } from './chappa-assertion.mjs';   // funcția din /dezvoltatori/asertiunea

app.get('/facturare', requireLogin, (req, res) => {
  const a = chappaAssertion(req.user, 'https://app.exemplu.ro');
  res.set('Cache-Control', 'no-store').send(layout(`
    <iframe src="https://facturare.chappa.ro/embed/#assertion=${a}"
            width="100%" height="820" style="border:0" allow="clipboard-write" title="Facturare"></iframe>`));
});

from chappa_assertion import chappa_assertion   # funcția din /dezvoltatori/asertiunea

@app.get("/facturare")
@login_required
def facturare():
    a = chappa_assertion(current_user.id, current_user.name, "https://app.exemplu.ro")
    resp = make_response(render_template("facturare.html", assertion=a))
    resp.headers["Cache-Control"] = "no-store"
    return resp

# facturare.html
# <iframe src="https://facturare.chappa.ro/embed/#assertion={{ assertion }}"
#         width="100%" height="820" style="border:0" allow="clipboard-write" title="Facturare"></iframe>

Aserțiunea folosește doar litere, cifre, -, _ și puncte: o pui în adresă așa cum e, fără codificare.

Reguli

• O aserțiune nouă la fiecare randare. Una folosită nu mai deschide nimic.
• Cache-Control: no-store pe pagină. O pagină din cache ar aduce o aserțiune deja folosită: iframe-ul ar cere reîncărcarea.
• Doar pentru utilizatorul logat, cu sub luat din sesiunea ta, niciodată din ce trimite browserul.
• După #, nu după ?. Partea de după ? ajunge la server și în jurnale.
• Fără referrerpolicy="no-referrer" pe iframe: așa află iframe-ul pagina care îl afișează și o compară cu ori.
• Nu loga aserțiunile. Trăiesc puțin, dar până atunci deschid o sesiune.

Firmele utilizatorului

Fără nimic în plus, utilizatorul își adaugă singur firmele. Dacă le știi deja, le pui în aserțiune, cu identificatorii tăi, și le poți fixa ca utilizatorul să nu poată lucra pe altele:

"ent": [{ "ref": "org_42", "kind": "pj", "cif": "RO18547290", "name": "Alfa SRL",
          "city": "Cluj-Napoca", "county": "Cluj", "role": "admin" }],
"ent_lock": true

Detalii, inclusiv ce se întâmplă cu o firmă deja verificată de altcineva, în firme și drepturi.

Sesiunea

Sesiunea ține cât lucrează utilizatorul. După o oră fără activitate se încheie, iar iframe-ul îi cere să reîncarce pagina, care semnează o aserțiune nouă. Dacă vrei ca sesiunea să se reînnoiască fără reîncărcare, folosește API-ul: pagina ta trimite aserțiunea nouă într-un mesaj, semnată de aceeași funcție de pe server.

Parametri în adresă

Înainte de # poți pune aceiași parametri ca la iframe-ul simplu: view și theme.

https://facturare.chappa.ro/embed/?view=invoices&theme=light#assertion=…

Evenimentele vin la fel ca la iframe-ul simplu, dacă vrei să le asculți.

Cost

Gratuit cât integrarea e în mod test. După înregistrare plătești per utilizator activ pe lună; pentru utilizatorii tăi, platforma rămâne gratuită (niveluri).