Configurare l'API REST di JTL-Wawi

JTL-Wawi ha una propria interfaccia di programmazione: l'API JTL-Wawi, spesso chiamata anche «API REST» o «server REST della Wawi». Tramite essa un altro programma – in questo caso allverto – può leggere articoli, clienti e documenti dalla tua Wawi senza accedere direttamente al database. Questa pagina spiega cosa devi configurare nella Wawi.

#Cos'è l'API REST – in parole semplici?

Immagina il server REST come lo sportello di accettazione della tua Wawi. I programmi che vogliono dati chiedono allo sportello («dammi tutte le fatture»). Lo sportello verifica se il programma ha un documento d'identità valido – la chiave API – e consegna poi esattamente i dati autorizzati.

• Il server REST è un programma di JTL che gira nella tua rete aziendale, di solito sullo stesso computer della Wawi o del suo SQL Server.
• È raggiungibile a un indirizzo come http://wawi-server:5883/api/eazybusiness. wawi-server è il nome o l'IP del tuo computer, 5883 la porta (da te può essere un'altra), eazybusiness il nome del database della tua Wawi.
• Ogni programma deve registrarsi una volta come app. Confermi la registrazione nella Wawi, dopodiché il programma riceve la sua chiave API.
• allverto si registra come app «allverto – Umzug von JTL-Wawi» (migrazione da JTL-Wawi) e richiede solo l'accesso in lettura (più, facoltativamente, la stampa dei PDF delle fatture). allverto non modifica nulla nella tua Wawi.

#Da quale versione della Wawi?

allverto usa l'API nella versione pubblicata da JTL per Wawi 2.1 e 2.2 (percorsi con /v2/…). Il canale API è stato sviluppato e testato con queste versioni.

#Passo dopo passo

#1. Attivare il server REST nella Wawi

1. Accedi a JTL-Wawi come utente con diritti di amministrazione.
2. Configura il server REST come descritto da JTL per la tua versione e avvialo. Annota la porta su cui è in ascolto.
3. Verifica che il server sia in esecuzione: un computer della rete aziendale deve poter raggiungere l'indirizzo http://<wawi-server>:<port>/api/eazybusiness (apri la porta nel firewall del computer della Wawi per la rete interna).

#2. Registrare allverto come app

La registrazione la avvii con il programma di supporto jtl-bridge su un computer della rete aziendale:

jtl-bridge register --api-url http://wawi-server:5883/api/eazybusiness

1. jtl-bridge invia la richiesta di registrazione al tuo server REST e segnala: «Registrierung gesendet … Bitte jetzt in der JTL-Wawi unter Admin → App-Registrierung bestätigen» (registrazione inviata … ora conferma in JTL-Wawi in Admin → App-Registrierung).
2. Nella Wawi apri la App-Registrierung (registrazione app). Secondo la nostra documentazione in Wawi 2.2 la voce si chiama così: Admin → App-Registrierung. Lì trovi la richiesta di allverto – Umzug von JTL-Wawi con i diritti richiesti.
3. Controlla i diritti (solo lettura, facoltativamente stampa delle fatture) e conferma la richiesta.
4. jtl-bridge verifica ogni 5 secondi. Dopo la conferma mostra la chiave API – solo questa volta. Copiala subito.
5. Se non confermi entro 10 minuti, jtl-bridge si interrompe – in tal caso riavvia semplicemente la registrazione.

#3. Inserire i dati in allverto

1. Apri Impostazioni → Migrazione dati → Migrazione da JTL-Wawi, passo Collega origine.
2. Scegli API JTL-Wawi.
3. In Indirizzo dell'API Wawi inserisci l'indirizzo del passo 1, ad es. http://wawi-server:5883/api/eazybusiness.
4. Incolla la Chiave API. allverto la salva crittografata; alla successiva apertura compare «Salvata – lascia vuoto per mantenerla».
5. ID mandante (facoltativo): compilalo solo se la tua Wawi lo richiede. Con una Wawi installata in azienda il campo di solito resta vuoto.
6. Lascia attivo Recupera i PDF delle fatture tramite API se vuoi che le fatture arrivino anche come PDF (la Wawi li rigenera a questo scopo).
7. Facoltativo: inserisci il SQL Server – jtl-bridge integrerà allora ciò che l'API non fornisce (vedi sotto).
8. Fai clic su Salva origine.

#4. Caricare i dati

Poiché il server REST è raggiungibile solo nella rete aziendale (e così deve restare), è jtl-bridge a caricare i dati: Genera token di importazione, poi esegui il comando mostrato nella rete aziendale, ad es.

jtl-bridge upload --url https://erp.allverto.cloud --token avjtl_… --fill-from-db

Nella procedura guidata si prosegue con Dati trovati e Assegnazioni – vedi Migrazione da JTL-Wawi: come funziona.

#Cosa fornisce l'API – e cosa no?

#Come jtl-bridge colma le lacune

Se avvii jtl-bridge con --fill-from-db e in allverto hai inserito anche il SQL Server, legge direttamente dal database tutto ciò che l'API non fornisce o fornisce solo in parte: abbonamenti, fatture passive, righe delle note di credito, distinte base, nomi degli attributi, mandati SEPA. A questo scopo basta un utente del database con sola autorizzazione di lettura. Senza database questi dati mancano – tutto il resto viene comunque trasferito.

#Sicurezza e rete

• Il server REST resta nella rete aziendale. Non esporre la porta su internet. jtl-bridge gira all'interno, legge il server REST e carica i dati verso l'esterno – non servono connessioni in entrata.
• jtl-bridge carica solo tramite HTTPS. I dati sono inoltre crittografati con una chiave derivata dal token di importazione.
• La chiave API e il token di importazione sono come password: non inviarli per e-mail, non copiarli nei ticket. Il token di importazione vale fino alla conclusione della migrazione; dopo non è più valido.
• Recupera dati direttamente funziona solo se l'API Wawi è raggiungibile da internet. Lo consigliamo solo con un accesso protetto (ad es. HTTPS tramite un reverse proxy con restrizione degli accessi). Normalmente usa jtl-bridge.
• Dopo la migrazione puoi rimuovere di nuovo la registrazione dell'app di allverto nella Wawi.

#Risoluzione dei problemi

Altri casi: Risoluzione dei problemi nella migrazione da JTL.