🔌 API & Webhook

Far parlare NOX con quello che c'è fuori: chiavi API perché un sito o un altro programma chiedano dati a NOX, webhook perché NOX li avvisi appena succede qualcosa

v 3.2 Amministrazione → API & Webhook Pacchetto Fatturazione

1Due cose diverse

Servono alla stessa esigenza — collegare NOX a un sito, a un negozio online, a un altro gestionale — ma vanno in direzioni opposte:

Chiave API: è qualcuno che chiede a NOX. Il tuo sito chiede il catalogo, le giacenze, crea un ordine.
Webhook: è NOX che racconta. Appena una fattura viene emessa o una rata incassata, NOX chiama un indirizzo che hai indicato — invece di far stare l'altro a chiedere «è successo qualcosa?» ogni minuto.

2Creare una chiave

Nella linguetta Chiavi API premi Nuova chiave, dalle un nome che dica a cosa serve («Sito e-commerce») e scegli cosa può fare (almeno una delle due):

lettura — può chiedere dati;
scrittura — può creare soggetti e documenti in bozza.

⛔ La chiave si vede una volta sola. Copiala subito, nel riquadro giallo che compare quando nasce: di lei, nel database, resta solo un'impronta, come per le password. Se la perdi, ne crei un'altra e revochi la vecchia.

💡 Dai solo quello che serve. La chiave del sito che manda ordini non ha motivo di leggere il partitario.

Nell'elenco vedi per ogni chiave le sue ultime sei cifre (le ritrovi in fondo alla chiave che hai copiato), quando è stata usata l'ultima volta e quante chiamate ha fatto: prima di revocarne una, sai se qualcuno la usa ancora.

3Cosa si può chiedere

Le API stanno su https://gnox.it/api/pub/v1/. La chiave va nell'intestazione Authorization: Bearer <chiave>.

Indirizzo	Cosa fa	Serve
`GET /ping`	Verifica che la chiave funzioni e dice cosa può fare	lettura
`GET /soggetti`	Clienti e fornitori, con ricerca	lettura
`GET /catalogo`	Articoli e servizi, con prezzo e aliquota	lettura
`GET /giacenze`	Quantità a magazzino per articolo	lettura
`GET /documenti`	Documenti, filtrabili per data, stato e soggetto	lettura
`GET /documenti/:id`	Un documento solo, con le righe	lettura
`GET /scadenze`	Rate aperte (o tutte)	lettura
`GET /eventi`	L'elenco degli eventi a cui ci si può iscrivere	lettura
`POST /soggetti`	Crea un cliente (se partita IVA o codice fiscale esistono già, risponde con quello che c'è)	scrittura
`POST /documenti`	Crea un ordine (o, con `tipoCodice`, un preventivo o una fattura di vendita) con le sue righe	scrittura

Ogni riga del documento porta quantita e prezzoUnitario (il prezzo netto); con voceCatalogoId aliquota e natura sono quelle del catalogo, e se manca prezzoUnitario vale il prezzo del catalogo. Una riga senza prezzo e senza voce, o con il prezzo in un campo con un altro nome (prezzo), viene rifiutata con il motivo: non diventa una riga a zero euro.

Quello che una chiave legge di un documento è quello che serve a un sito: numero, date, intestatario, righe con prezzi e IVA, totali, rate. Non il costo d'acquisto, le provvigioni, gli agenti o le note interne.

💡Le scritture fatte con una chiave compaiono nel Registro modifiche come quelle fatte da dentro, con chi = api:<nome della chiave>. E valgono le stesse regole della licenza: con la licenza scaduta (sola lettura) o il pacchetto spento, POST /documenti risponde 403 come la pagina Documenti. Creare un soggetto resta sempre possibile.

⚠️Un documento creato da fuori nasce sempre in BOZZA. Numerare una fattura è un atto fiscale e lo fa una persona, guardandola: un sito che emette fatture da sé prima o poi ne emette una sbagliata, e quella non si cancella più. I totali li calcola NOX dalle righe, non il sito.

4Dichiarare un webhook

Nella linguetta Webhook premi Indirizzo: l'indirizzo https a cui mandare gli avvisi e gli eventi che ti interessano (se non ne scegli nessuno, arrivano tutti).

Gli eventi disponibili: documento creato (da NOX, da una conversione o dalle API), emesso, annullato; rata incassata; soggetto creato (da NOX o dalle API); nota spese approvata o rimborsata. Nel corpo, dati.origine dice da dove viene un documento o un soggetto creato (nox, conversione, evasione, duplica, api).

⛔ Anche il segreto dell'indirizzo si vede una volta sola, appena nasce: dopo non torna più, né nella pagina né nelle risposte del programma. Serve a chi riceve per verificare che la chiamata venga davvero da NOX. Se lo perdi, togli l'indirizzo e dichiaralo di nuovo.

⚠️ Solo indirizzi https pubblici, sulla porta 443 o 8443. Su http in chiaro non si mandano dati di fatture: serve https. NOX non chiama indirizzi locali o della rete interna (per esempio localhost, 127.0.0.1, 192.168.…, gli IPv4 scritti dentro un IPv6, oppure un nome che porta a uno di questi), né porte diverse dalla 443 (quella di https, che non si scrive) e dalla 8443: un indirizzo così viene rifiutato al salvataggio, con il motivo.

Il controllo si ripete a ogni consegna: se nel frattempo il nome dell'indirizzo è stato spostato su una rete interna, la chiamata non parte. Anche i rimandi verso un altro indirizzo non vengono seguiti. Non si può nemmeno scrivere utente e password dentro l'indirizzo: chi riceve verifica la firma (sotto).

5Verificare la firma

Ogni chiamata porta cinque intestazioni:

X-NOX-Evento — il nome dell'evento;
X-NOX-Data — il momento della chiamata;
X-NOX-Firma — l'HMAC-SHA256 di X-NOX-Data + "." + corpo, calcolato col segreto;
X-NOX-Consegna — il numero della consegna, uguale in tutti i tentativi della stessa;
X-NOX-Tentativo — il numero del tentativo (1, 2, …).

Chi riceve ricalcola la firma con il suo segreto e la confronta: se non torna, la chiamata non viene da NOX. La data sta dentro la firma perché una chiamata intercettata non si possa rigiocare.

6Se chi riceve non risponde

Chi riceve può essere spento proprio nel momento in cui NOX chiama, e un avviso perso non si recupera. Per questo le consegne si ritentano: sei tentativi con attesa crescente — 1, 5, 25 minuti, 2 ore, 10 ore — poi si smette e resta scritto perché.

⚠️Lo stesso avviso può arrivare due volte: se chi riceve lo registra ma risponde tardi (oltre 12 secondi) o con un errore, NOX lo ritenta. Chi riceve tiene da parte X-NOX-Consegna e scarta quelle già viste. Due giri di consegna non prendono mai la stessa riga insieme.

Per ogni indirizzo ci sono il pulsante prova, che manda un avviso finto e dice se ha risposto (con le stesse regole: niente indirizzi http, locali o interni), e lo storico delle consegne con tentativi e risposta. Un indirizzo che sbaglia venti volte di fila si spegne da solo; lo riaccendi quando è sistemato.

💡 Il pulsante Consegna ora svuota subito la coda, senza aspettare il giro automatico che passa ogni minuto: utile quando hai appena riacceso il sito.

?Domande frequenti

Emettere una fattura può fallire perché il sito è giù?

No. L'avviso si mette in coda nel momento in cui succede, e la consegna la fa un giro separato. La fattura si emette comunque.

Una chiave vale per tutte le aziende?

No. La chiave porta dentro il nome dell'azienda e apre solo i suoi dati.

Come faccio a sapere se la chiave funziona?

Chiama GET /api/pub/v1/ping: risponde con il nome dell'azienda e con quello che la chiave può fare.

Ho perso la chiave.

Non si può recuperare: ne crei una nuova, la metti nel programma che la usava, e revochi la vecchia.