Collegare un gestionale a ScontrinoZen

Il gestionale prepara lo scontrino; l'esercente lo controlla e lo emette nell'app ScontrinoZen, con il suo accesso all'Agenzia delle Entrate. Non serve nessuna chiave e nessun server: basta costruire un link di cassa.

Gestionale su PC: mostra il link come QR; l'esercente lo inquadra con la fotocamera del telefono.
Gestionale su tablet o smartphone (lo stesso dispositivo con l'app): il link, toccato, apre l'app con lo scontrino già pronto.

Il link

https://scontrinozen.zenzeroot.it/e#<dati>

<dati> è un oggetto JSON in UTF-8 codificato in base64url senza = finali. I dati stanno dopo il #: non arrivano a nessun server, nemmeno al nostro.

{
  "v": 1,
  "r": [["Taglio e piega", 3500, "22", 1], ["Shampoo", 850, "22", 2]],
  "p": "E",
  "ref": "CRM-4812",
  "src": "Il tuo gestionale"
}

campo	obbligatorio	significato
`v`	sì	versione del formato: `1`
`r`	sì	righe, da 1 a 30: `[descrizione, prezzo, iva, quantità]`
descrizione	sì	testo, al massimo 80 caratteri
prezzo	sì	prezzo lordo unitario in centesimi, intero da 1 a 9999999 (35,00 € → `3500`)
iva	sì	aliquota `"22"`, `"10"`, `"5"`, `"4"`, oppure la natura `"N2"` (non soggetta, es. regime forfettario) o `"N4"` (esente)
quantità	no	intero da 1 a 99 (predefinito 1)
`p`	no	pagamento: `"E"` elettronico (carta, POS) o `"C"` contanti; se manca sceglie l'esercente
`ref`	no	il tuo riferimento (es. id dell'appuntamento), al massimo 40 caratteri. L'app avvisa se oggi ha già emesso uno scontrino con lo stesso riferimento
`src`	no	nome del gestionale mostrato all'esercente, al massimo 30 caratteri
`exp`	no	scadenza in secondi Unix: oltre, l'app chiede di ricontrollare gli importi
`cb`	no	indirizzo https di ritorno (vedi sotto); vale solo per i gestionali registrati

Tieni il link entro circa 400 caratteri perché il QR resti leggibile da qualunque telefono: con descrizioni brevi ci stanno 6-8 righe. Un link non valido non tocca la cassa: l'app mostra l'errore e basta.

Esempi

JavaScript

function linkScontrino(dati) {
  const json = new TextEncoder().encode(JSON.stringify(dati));
  let bin = ''; json.forEach((b) => { bin += String.fromCharCode(b); });
  const b64 = btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
  return 'https://scontrinozen.zenzeroot.it/e#' + b64;
}

PHP

function link_scontrino(array $dati): string {
    $json = json_encode($dati, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    return 'https://scontrinozen.zenzeroot.it/e#' . rtrim(strtr(base64_encode($json), '+/', '-_'), '=');
}

Python

import base64, json
def link_scontrino(dati: dict) -> str:
    j = json.dumps(dati, ensure_ascii=False, separators=(",", ":")).encode()
    return "https://scontrinozen.zenzeroot.it/e#" + base64.urlsafe_b64encode(j).decode().rstrip("=")

Cosa vede l'esercente

Il link apre ScontrinoZen con «Scontrino da src», le righe e il totale.
Se in cassa c'è già uno scontrino, sceglie se aggiungere o sostituire.
Conferma con Emetti. Se l'accesso all'Agenzia è scaduto (dura circa 2 ore), l'app lo porta a rientrare con SPID o CIE e lo scontrino resta pronto: nulla viene emesso senza di lui.

Ritorno dell'esito

Per i gestionali registrati con noi (scrivi a info@zenzeroot.it), dopo l'emissione l'app mostra «Torna a src», che apre cb con questi parametri:

https://tuo-gestionale.it/esito?ref=CRM-4812&esito=emesso&numero=DCW2026/1234-5678&totale=5200

numero è il numero del documento commerciale, totale in centesimi. Funziona quando il gestionale è aperto sullo stesso dispositivo dell'app; dal QR mostrato su un PC il ritorno non è ancora disponibile. Il controllo dei doppioni sul riferimento vale per il singolo telefono.

Prova

Descrizione Prezzo (€) IVA Riferimento