Per il consulente informatico

Questa appendice è rivolta al responsabile IT o al system integrator che deve collegare EXOfattura ad altri sistemi aziendali (ERP, e-commerce, BI).

Note

Il resto del manuale è pensato per l'uso quotidiano di imprenditori e commercialisti. Le informazioni di questa pagina non servono per l'uso ordinario della piattaforma.

Documentazione API

Le integrazioni tra sistemi usano le API REST di EXOfattura.

• Documentazione interattiva: da Sistema → Impostazioni, riquadro API Key — Integrazioni esterne, pulsante «Documentazione API» (all'indirizzo https://app.exofattura.it/swagger/).
• Autenticazione: chiave API nell'intestazione X-API-Key, oppure token Bearer. Se l'utente ha la verifica in due passaggi attiva, il login API (POST /api/v1/auth/login) risponde con mfa_required e il token si ottiene inviando il codice a POST /api/v1/auth/login/mfa.
• Chiavi API: si generano in Sistema → Impostazioni, riquadro API Key — Integrazioni esterne, con «Genera API key». La chiave viene mostrata una sola volta: copiala subito. Puoi revocarla in qualsiasi momento con «Revoca». Una chiave API dà accesso completo all'account, quindi può generarla solo il proprietario o il legale rappresentante.
• Token personali: in Sistema → API Token generi token con permessi limitati (scope) e vedi quando sono stati usati l'ultima volta. Un token personale può fare solo ciò che consentono i suoi scope: non può creare chiavi API né gestire le sessioni.
• Ambiente di prova: dallo stesso riquadro, con «Ambiente di TEST», generi le chiavi di prova e apri la sandbox (vedi Ambiente di prova (sandbox)).

Ambiente di prova (sandbox)

Per collaudare un'integrazione senza toccare i dati veri c'è un ambiente di prova separato, sempre aggiornato alla stessa versione della produzione.

	Produzione	Prova
Gestionale	https://app.exofattura.it	https://app-test.exofattura.it
API	https://api.exofattura.it	https://api-test.exofattura.it
Chiave API	fat_…	fat_test_…

Come si entra

1. In produzione vai in Sistema → Impostazioni, riquadro API Key — Integrazioni esterne, e clicca «Ambiente di TEST».
2. Per il gestionale clicca «Apri sandbox»: si apre app-test.exofattura.it con un'azienda di prova [TEST], già collegato con il tuo utente.
3. Per le API genera una Chiave API TEST (fat_test_…) e usala verso https://api-test.exofattura.it.

Cosa cambia rispetto alla produzione

• Le fatture vanno all'ambiente di test dello SDI: nessun documento arriva all'Agenzia delle Entrate né ai clienti.
• Email, PEC, SMS, WhatsApp e notifiche sull'app non partono mai: il gestionale le considera inviate, ma non escono.
• Le spedizioni sono simulate: nessun corriere riceve ordini; etichette e tracciamento sono di prova.
• Pagamenti e firma elettronica usano gli ambienti di prova dei fornitori.
• I webhook partono verso gli indirizzi registrati nella sandbox e contengono "sandbox": true.
• I dati sono temporanei: dopo 1 ora senza attività vengono cancellati. Puoi azzerarli subito con «Azzera dati» nella barra gialla in alto.
• Le credenziali non si mescolano: una chiave fat_test_… non funziona in produzione e una chiave di produzione non funziona nella sandbox.

Nota

Per tornare alla produzione clicca «Torna a LIVE» nella barra gialla.

Ambiti tipici di integrazione

Ambito	Esempio
Anagrafiche	Sincronizzazione di clienti e prodotti; ricerca dei dati di un'azienda a partire dalla P.IVA (GET /api/v1/companies/lookup?q=…)
Vendite	Creazione di fatture da ordini e-commerce
Pagamenti online	Link di pagamento da preventivo o fattura, RoxPay se collegato altrimenti Mollie (POST /api/v1/quotes/{id}/payment-link, POST /api/v1/invoices/{id}/payment-link); al pagamento il tuo sistema riceve il webhook payment.paid
Pagamenti RoxPay	Link, elenco, verifica e storno RoxPay (…/roxpay-payment, …/roxpay-payments, …/roxpay-sync, …/roxpay-refund)
Rinnovo automatico	Righe con renewal su preventivi e fatture; stato e link di gestione per il cliente (GET …/{id}/auto-renew), disdetta (POST …/{id}/auto-renew/cancel), elenco (GET /api/v1/auto-renewals)
Pagamenti Mollie	Link di pagamento Mollie (POST /api/v1/quotes/{id}/mollie-payment, POST /api/v1/invoices/{id}/mollie-payment); con RoxPay collegato creano il link RoxPay
Link pubblico PDF	Link condivisibile al PDF di una fattura, consultabile senza login (POST /api/v1/invoices/{id}/share-link)
Fatture passive	Registrazione anche in valuta estera con cambio reale (POST /api/v1/purchases/invoices con original_currency, original_total_amount, exchange_rate, lines_currency); eliminazione di un documento inserito a mano e senza effetti (DELETE /api/v1/purchases/invoices/{id}, il motivo del blocco è in delete_block_reason del dettaglio)
Note di credito	PDF della nota di credito, con lo stile documenti scelto (GET /api/v1/credit-notes/{id}/pdf)
Logistica	Aggiornamento del tracking dalle piattaforme dei corrieri; generazione etichetta (GET /api/v1/shipments/{id}/label) e download dell'ultima etichetta generata (GET /api/v1/shipments/{id}/label/download)
Note e Promemoria	Spunta delle attività di una checklist (POST /api/v1/knowledge/notes/{id}/checklist/{item} con {"completed": true})
Magazzino	Aggiornamento giacenze da un WMS
Costi e produzione	Costi, distinte base, ordini di produzione, ricevimenti merce, mapping codici fornitore
Notifiche	Webhook sugli eventi: il tuo sistema registra URL ed eventi (POST /api/v1/webhooks)

Le chiamate che operano su un'azienda richiedono l'intestazione X-Company-Id e i permessi adeguati. I dettagli di ogni chiamata sono nella documentazione interattiva.

Webhook

In Sistema → Webhook gli amministratori configurano gli endpoint che ricevono le notifiche sugli eventi selezionati:

1. Nel riquadro Nuovo endpoint inserisci l'URL endpoint e scegli gli Eventi.
2. Clicca «Crea webhook».
3. Copia subito il secret mostrato: non sarà più visibile e ti serve per verificare l'autenticità delle notifiche.

Nella tabella Endpoint configurati vedi stato ed eventi di ciascun webhook e puoi eliminarlo.

Registrare un webhook da un altro sistema

Un sistema collegato (area clienti, CRM, e-commerce) può registrarsi da solo, senza passare dalle impostazioni:

1. Chiede l'elenco degli eventi disponibili: GET /api/v1/webhooks/events.
2. Registra il suo indirizzo e gli eventi che gli servono: POST /api/v1/webhooks con url ed events. La risposta contiene il secret, mostrato una sola volta.
3. Verifica che tutto funzioni con una consegna di prova: POST /api/v1/webhooks/{id}/test.

A ogni evento EXOfattura invia una notifica firmata (intestazione X-Exobyte-Signature). Se il sistema non risponde, EXOfattura riprova più volte nelle ore successive; l'esito di ogni invio è in GET /api/v1/webhooks/deliveries.

Eventi utili per i pagamenti online:

Evento	Quando arriva
payment.paid	Il cliente ha pagato con il link di pagamento: la fattura è già emessa e incassata
auto_renew.activated	Dopo il primo pagamento si è attivato il rinnovo automatico su carta
auto_renew.charged	È stato addebitato un rinnovo: la nuova fattura è già emessa e incassata
auto_renew.cancelled	Il rinnovo automatico è stato disdetto dal cliente o dall'azienda
auto_renew.failed	Il rinnovo automatico non si è attivato: le scadenze restano manuali

Importare dati da altri programmi

Per importare anagrafiche e documenti da Danea Easyfatt o Fatture in Cloud usa Sistema → Import dati.

Supporto tecnico

Per richieste di integrazione contatta il supporto EXOBYTE indicando:

• ambiente (produzione o test);
• moduli coinvolti;
• volumi stimati e frequenza di sincronizzazione.

---

Torna al manuale d'utilizzo per le procedure operative.