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.

#Direttamente da allverto (canale principale)

Se la tua JTL-Wawi gira su un server in affitto e il server REST è raggiungibile da internet, allverto si collega da solo. Non ti serve alcun programma sul tuo server.

Funziona se:

• il server REST è raggiungibile tramite un indirizzo IP pubblico o un nome pubblico – non tramite localhost, un indirizzo della rete aziendale o un nome computer.
• la porta è 80, 443 oppure 1024 o superiore.

Come procedere:

1. Apri Impostazioni → Migrazione dati → Migrazione da JTL-Wawi, passo Collega origine, e scegli API JTL-Wawi.
2. In Dati di connessione inserisci l'Indirizzo dell'API Wawi, ad es. https://217.160.19.64:5885/api/eazybusiness, e fai clic su Salva.
3. Fai clic su Verifica connessione. allverto interroga …/v2/info. Senza chiave API il risultato è «server REST raggiungibile ✓ – l’accesso segue con la registrazione». È normale che l'indirizzo stesso (…/api/eazybusiness) mostri «404» nel browser.
4. Se il tuo server REST risponde solo tramite HTTPS, allverto propone l'indirizzo con https://. Fai clic su Cambia l’indirizzo in https://.
5. Se il tuo server REST usa un certificato creato da te, allverto mostra l'impronta (SHA-256), l'emittente e la validità. Confronta l'impronta con il certificato sul tuo server e fai clic su Fidati di questo certificato.
6. Registra allverto in JTL-Wawi – in quest'ordine:
   1. In JTL-Wawi apri „Anwendungsregistrierungen“ → „Anwendung registrieren“ e prosegui fino a «Registrierung beginnen». La Wawi attende quindi una richiesta.
   2. In allverto fai clic su Invia registrazione da allverto. allverto invia di nuovo la richiesta ogni 5 secondi per un massimo di 10 minuti. Lo stato compare subito sotto, ad es. «In attesa della Wawi» o «Accettata». Con Annulla interrompi l'operazione.
   3. Nella Wawi controlla «Anwendungsinformationen», scegli un utente Wawi in «Benutzer», conferma i diritti (solo lettura, facoltativamente stampa delle fatture) in «Zugriffsverwaltung» e fai clic su «Einrichtung abschließen». allverto mostra allora «Chiave API salvata.» e la salva cifrata.
7. Fai clic su Recupera dati direttamente ora. allverto recupera i dati in background. Le quantità compaiono poi in Dati trovati.

Se inserisci localhost o un indirizzo della tua rete aziendale, il campo mostra: «Questo indirizzo è raggiungibile solo sul tuo server. Inserisci l’IP pubblico del tuo server oppure usa jtl-bridge qui sotto.» Se il tuo server REST non è raggiungibile da internet, usa il canale con jtl-bridge (passi 2 e 3 più sotto).

#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 sul computer su cui gira la tua JTL-Wawi (di solito un server Windows).
• Su questo computer è raggiungibile a un indirizzo come http://localhost:5883/api/eazybusiness. localhost significa «questo computer», 5883 è un esempio di porta – si intende la porta che hai impostato in Wawi per il server REST (spesso 5883, ma anche ad es. 5885). eazybusiness è il nome del database della tua Wawi.
• Ogni programma deve registrarsi una volta come applicazione. Avvii la registrazione nella Wawi, il programma invia la sua richiesta, tu completi la configurazione – dopodiché il programma riceve la sua chiave API.
• allverto si registra come applicazione «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 – ad es. apri nel browser sul server Wawi l'indirizzo http://localhost:<port>/api/eazybusiness. Se arriva una risposta qualsiasi (anche un messaggio di errore nel browser), è in esecuzione.

#2. Con jtl-bridge: scegliere l'origine in allverto

Questo canale ti serve solo se il tuo server REST non è raggiungibile da internet.

1. Apri Impostazioni → Migrazione dati → Migrazione da JTL-Wawi, passo Collega origine.
2. Scegli API JTL-Wawi. Non devi inserire nulla – indirizzo e chiave API li trasferisce jtl-bridge da solo.
3. Facoltativo: imposta una Data di passaggio.

In Dati di connessione trovi anche Chiave API (solo se ne hai già una), ID mandante (facoltativo) (solo se la tua Wawi lo richiede), Recupera i PDF delle fatture tramite API e l'interruttore Integrare i dati mancanti dal database (facoltativo) (vedi sotto).

#3. Con jtl-bridge: avviare il programma e registrare l'applicazione nella Wawi

Apri in basso il riquadro Server non raggiungibile da internet? Trasferisci i dati con jtl-bridge. Ti guida attraverso i passi (in dettaglio: Il programma di supporto jtl-bridge):

1. Scaricare jtl-bridge.
2. Copiare il file sul server su cui gira la tua JTL-Wawi, ad es. tramite Desktop remoto sul desktop.
3. Sul server avviare il file con un doppio clic.
4. Fai clic qui su «Genera codice di configurazione», copia il codice, incollalo nella finestra con il clic destro e premi Invio.
5. Rispondere alle domande nella finestra – di solito basta Invio. Il programma cerca il server REST su questo computer (porte da 5883 a 5890) e propone l'indirizzo trovato, ad es. «Trovato: http://localhost:5885/api/eazybusiness – premi Invio per usarlo».
6. In JTL-Wawi registrare l'applicazione (vedi sotto).
7. Attendere che compaia «Fatto»: allverto spunterà poi il passaggio.

Sul passo 6 – l'ordine è importante, perché la Wawi accetta una richiesta solo mentre la sua procedura guidata è in attesa:

1. In JTL-Wawi apri Anwendungsregistrierungen (registrazioni delle applicazioni) → Anwendung registrieren (registra applicazione). La procedura guidata ha i passi Einführung, Registrierung beginnen, Anwendungsinformationen, Benutzer, Zugriffsverwaltung e Einrichtung abschließen.
2. Prosegui fino a Registrierung beginnen (avvia registrazione). Lì compaiono «Eine Sitzung zur Entgegennahme von Registrierungsanfragen wurde gestartet …» e «Es wird auf die Übermittlung einer Registrierungsanfrage durch die zu registrierende Anwendung gewartet …».
3. Ora premi Invio nella finestra di jtl-bridge. Il programma invia la richiesta allverto – Umzug von JTL-Wawi. Se la Wawi non la accetta ancora, il programma riprova ogni 5 secondi per 10 minuti.
4. In Wawi controlla Anwendungsinformationen, scegli un utente Wawi in Benutzer e conferma in Zugriffsverwaltung i diritti richiesti (sola lettura, facoltativamente stampa delle fatture).
5. Fai clic su Einrichtung abschließen (completa la configurazione). jtl-bridge consegna poi la chiave API cifrata ad allverto – non la vedi e non devi copiare nulla. allverto la salva crittografata e la usa solo per questa migrazione.

Se non completi la configurazione entro 10 minuti, jtl-bridge si interrompe – in tal caso avvialo semplicemente di nuovo.

#Da dove viene la chiave API?

JTL-Wawi non mostra alcuna chiave API da copiare e non ne crea una con un clic. La rilascia solo a un'applicazione che sta facendo richiesta in quel momento – mentre la sua procedura guidata è in attesa su Registrierung beginnen. Questa richiesta la invia allverto da solo (Invia registrazione da allverto). Se il tuo server REST non è raggiungibile da internet, la invia jtl-bridge.

Poi allverto recupera i dati oppure jtl-bridge li carica. 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 nella procedura guidata, sotto Dati, attivi l'interruttore Integrare i dati mancanti dal database (facoltativo) e inserisci l'accesso al SQL Server, jtl-bridge 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. In Utente (sa) va l'utente di SQL Server (di solito sa), non il tuo utente in JTL-Wawi; va bene anche un utente dedicato con sola autorizzazione di lettura. Senza database questi dati mancano – tutto il resto viene comunque trasferito.

#Sicurezza e rete

• Direttamente da allverto il server REST deve essere raggiungibile da internet. Apri la porta nel firewall solo per i server di allverto: 2.31.70.120, 2.31.74.112, 2.31.72.228 – mai per tutti.
• Usa https://. Con http:// chiave API e dati viaggiano in chiaro su internet. Un certificato creato da te lo confermi una volta con Fidati di questo certificato. Dopo, allverto si collega solo con esattamente questo certificato.
• Con jtl-bridge non deve essere raggiungibile nulla da internet. jtl-bridge gira sul server Wawi e carica solo tramite HTTPS. I dati sono inoltre cifrati con una chiave derivata dal token di importazione.
• La chiave API e il codice di configurazione sono come password: non inviarli per e-mail, non copiarli nei ticket. allverto salva la chiave API cifrata e non la mostra mai. Il codice di configurazione vale 30 giorni alla volta (prolungabile), al massimo fino alla conclusione della migrazione.
• Con Verifica connessione allverto controlla da solo un indirizzo solo se è raggiungibile da internet. Con localhost o un indirizzo della rete aziendale il test lo fa jtl-bridge e comunica il risultato.
• Dopo la migrazione puoi rimuovere l'applicazione «allverto – Umzug von JTL-Wawi» nella Wawi in „Anwendungsregistrierungen“.

#Risoluzione dei problemi

Altri casi: Risoluzione dei problemi nella migrazione da JTL.