Configurer l'API REST de JTL-Wawi

La JTL-Wawi dispose de sa propre interface de programmation : l'API JTL-Wawi, souvent aussi appelée « API REST » ou « serveur REST de la Wawi ». Elle permet à un autre programme – ici allverto – de lire les articles, clients et documents de ta Wawi sans accéder directement à la base de données. Cette page explique ce que tu dois configurer pour cela dans la Wawi.

#Directement depuis allverto (voie principale)

Si ta JTL-Wawi tourne sur un serveur loué et que le serveur REST est accessible depuis Internet, allverto s'y connecte lui-même. Tu n'as alors besoin d'aucun programme sur ton serveur.

Cela fonctionne si :

• le serveur REST est accessible via une adresse IP publique ou un nom public – pas via localhost, une adresse du réseau de l'entreprise ou un nom d'ordinateur.
• le port est 80, 443 ou supérieur ou égal à 1024.

Comment faire :

1. Ouvre Paramètres → Reprise de données → Migration depuis JTL-Wawi, étape Connecter la source, et choisis API JTL-Wawi.
2. Sous Informations de connexion, saisis l'Adresse de l'API Wawi, p. ex. https://217.160.19.64:5885/api/eazybusiness, et clique sur Enregistrer.
3. Clique sur Tester la connexion. allverto interroge …/v2/info. Sans clé API, le résultat est « serveur REST accessible ✓ – la connexion suit via l’enregistrement ». Il est normal que l'adresse elle-même (…/api/eazybusiness) affiche « 404 » dans le navigateur.
4. Si ton serveur REST ne répond qu'en HTTPS, allverto propose l'adresse avec https://. Clique sur Changer l’adresse en https://.
5. Si ton serveur REST utilise un certificat créé par toi, allverto affiche l'empreinte (SHA-256), l'émetteur et la validité. Compare l'empreinte avec le certificat de ton serveur et clique sur Faire confiance à ce certificat.
6. Enregistre allverto dans la JTL-Wawi – dans cet ordre :
   1. Dans la JTL-Wawi, ouvre „Anwendungsregistrierungen“ → „Anwendung registrieren“ et avance jusqu’à « Registrierung beginnen ». La Wawi attend alors une demande.
   2. Dans allverto, clique sur Envoyer l’enregistrement depuis allverto. allverto renvoie la demande toutes les 5 secondes pendant 10 minutes au maximum. L'état s'affiche juste en dessous, p. ex. « En attente de la Wawi » ou « Acceptée ». Annuler arrête l'opération.
   3. Dans la Wawi, vérifie « Anwendungsinformationen », choisis un utilisateur Wawi sous « Benutzer », confirme les droits (lecture seule, éventuellement impression des factures) sous « Zugriffsverwaltung » et clique sur « Einrichtung abschließen ». allverto affiche alors « Clé API enregistrée. » et l'enregistre chiffrée.
7. Clique sur Récupérer les données directement maintenant. allverto récupère les données en arrière-plan. Les quantités apparaissent ensuite sous Données trouvées.

Si tu saisis localhost ou une adresse de ton réseau d'entreprise, le champ affiche : « Cette adresse n’est accessible que sur ton serveur. Saisis l’IP publique de ton serveur – ou utilise jtl-bridge plus bas. » Si ton serveur REST n'est pas accessible depuis Internet, utilise la voie avec jtl-bridge (étapes 2 et 3 plus bas).

#Qu'est-ce que l'API REST – en termes simples ?

Imagine le serveur REST comme le guichet d'accueil de ta Wawi. Les programmes qui veulent des données s'adressent au guichet (« donne-moi toutes les factures »). Le guichet vérifie que le programme possède une pièce d'identité valide – la clé API – puis remet exactement les données autorisées.

• Le serveur REST est un programme de JTL qui tourne sur l'ordinateur où tourne ta JTL-Wawi (le plus souvent un serveur Windows).
• Sur cet ordinateur, il est accessible via une adresse comme http://localhost:5883/api/eazybusiness. localhost signifie « cet ordinateur », 5883 est un exemple de port – il s'agit du port que tu as réglé dans la Wawi pour le serveur REST (souvent 5883, mais aussi 5885 par exemple). eazybusiness est le nom de ta base de données Wawi.
• Chaque programme doit s'enregistrer une fois comme application. Tu démarres l'enregistrement dans la Wawi, le programme envoie sa demande, tu termines la configuration – ensuite, le programme reçoit sa clé API.
• allverto s'enregistre comme application « allverto – Umzug von JTL-Wawi » et ne demande qu'un accès en lecture (avec, en option, l'impression des PDF de factures). allverto ne modifie rien dans ta Wawi.

#À partir de quelle version de la Wawi ?

allverto utilise l'API dans la version publiée par JTL pour Wawi 2.1 et 2.2 (chemins en /v2/…). La voie API est développée et testée avec ces versions.

#Pas à pas

#1. Activer le serveur REST dans la Wawi

1. Connecte-toi à la JTL-Wawi avec un utilisateur disposant de droits d'administration.
2. Configure le serveur REST comme JTL le décrit pour ta version, puis démarre-le. Note le port sur lequel il écoute.
3. Vérifie que le serveur tourne – p. ex. en ouvrant l'adresse http://localhost:<port>/api/eazybusiness dans le navigateur du serveur Wawi. Si une réponse quelconque arrive (même un message d'erreur dans le navigateur), il tourne.

#2. Avec jtl-bridge : choisir la source dans allverto

Tu n'as besoin de cette voie que si ton serveur REST n'est pas accessible depuis Internet.

1. Ouvre Paramètres → Reprise de données → Migration depuis JTL-Wawi, étape Connecter la source.
2. Choisis API JTL-Wawi. Tu n'as rien à saisir – jtl-bridge transmet lui-même l'adresse et la clé API.
3. Facultatif : définis une date de bascule.

Sous Informations de connexion se trouvent aussi Clé API (seulement si tu en as déjà une), ID du mandant (facultatif) (seulement si ta Wawi en exige un), Récupérer les PDF des factures via l'API et l'interrupteur Compléter les données manquantes depuis la base de données (facultatif) (voir ci-dessous).

#3. Avec jtl-bridge : lancer le programme et enregistrer l'application dans la Wawi

Déplie en bas l'encadré Serveur non accessible depuis Internet ? Transférer les données avec jtl-bridge. Il te guide à travers les étapes (en détail : Le programme d'aide jtl-bridge) :

1. Télécharger jtl-bridge.
2. Copier le fichier sur le serveur où tourne ta JTL-Wawi – p. ex. par Bureau à distance sur le bureau.
3. Sur le serveur, lancer le fichier par double-clic.
4. Cliquer ici sur « Créer le code de configuration », copier le code, le coller dans la fenêtre par clic droit et appuyer sur Entrée.
5. Répondre aux questions dans la fenêtre – Entrée suffit généralement. Le programme cherche le serveur REST sur cet ordinateur (ports 5883 à 5890) et propose l'adresse trouvée, p. ex. « Trouvé : http://localhost:5885/api/eazybusiness – appuie sur Entrée pour l’utiliser ».
6. Dans la JTL-Wawi, enregistrer l'application (voir ci-dessous).
7. Attendre que « Terminé » s’affiche – allverto coche alors l’étape.

Pour l'étape 6 – l'ordre est important, car la Wawi n'accepte une demande que pendant que son assistant attend :

1. Dans la JTL-Wawi, ouvre Anwendungsregistrierungen (enregistrements d'applications) → Anwendung registrieren (enregistrer une application). L'assistant comporte les étapes Einführung, Registrierung beginnen, Anwendungsinformationen, Benutzer, Zugriffsverwaltung et Einrichtung abschließen.
2. Avance jusqu'à Registrierung beginnen. Il y est indiqué : « Eine Sitzung zur Entgegennahme von Registrierungsanfragen wurde gestartet … » et « Es wird auf die Übermittlung einer Registrierungsanfrage durch die zu registrierende Anwendung gewartet … » (en attente d'une demande d'enregistrement).
3. Appuie maintenant sur Entrée dans la fenêtre de jtl-bridge. Le programme envoie la demande allverto – Umzug von JTL-Wawi. Si la Wawi ne l'accepte pas encore, le programme réessaie toutes les 5 secondes pendant 10 minutes.
4. Dans la Wawi, vérifie Anwendungsinformationen, choisis un utilisateur Wawi sous Benutzer et confirme sous Zugriffsverwaltung les droits demandés (lecture seule, impression des factures en option).
5. Clique sur Einrichtung abschließen. jtl-bridge transmet ensuite la clé API chiffrée à allverto – tu ne la vois pas et tu n'as rien à recopier. allverto l'enregistre de manière chiffrée et ne l'utilise que pour cette migration.

Si tu ne termines pas la configuration dans les 10 minutes, jtl-bridge s'interrompt – relance-le alors simplement.

#D'où vient la clé API ?

La JTL-Wawi n'affiche aucune clé API et n'en crée pas non plus d'un clic. Elle ne la délivre qu'à une application qui en fait la demande à cet instant – pendant que son assistant attend à l'étape Registrierung beginnen. Cette demande, allverto l'envoie lui-même (Envoyer l’enregistrement depuis allverto). Si ton serveur REST n'est pas accessible depuis Internet, c'est jtl-bridge qui l'envoie.

Ensuite, allverto récupère les données ou jtl-bridge les téléverse. L'assistant continue avec Données trouvées et Correspondances – voir Migration depuis JTL-Wawi : comment ça se passe.

#Que fournit l'API – et que ne fournit-elle pas ?

#Comment jtl-bridge comble les lacunes

Si tu actives dans l'assistant, sous Informations, l'interrupteur Compléter les données manquantes depuis la base de données (facultatif) et que tu saisis l'accès au SQL Server, jtl-bridge lit directement dans la base de données tout ce que l'API ne fournit pas ou seulement en partie : abonnements, factures fournisseurs, lignes des avoirs, nomenclatures, noms d'attributs, mandats SEPA. Dans Utilisateur (sa), il faut l'utilisateur SQL Server (généralement sa), pas ton utilisateur JTL-Wawi ; un utilisateur dédié en lecture seule suffit aussi. Sans base de données, ces données manquent – tout le reste est néanmoins repris.

#Sécurité et réseau

• Directement depuis allverto, le serveur REST doit être accessible depuis Internet. N'ouvre le port dans le pare-feu que pour les serveurs allverto : 2.31.70.120, 2.31.74.112, 2.31.72.228 – jamais pour tout le monde.
• Utilise https://. Avec http://, la clé API et les données passent en clair sur Internet. Tu confirmes une seule fois un certificat créé par toi avec Faire confiance à ce certificat. Ensuite, allverto ne se connecte qu'avec exactement ce certificat.
• Avec jtl-bridge, rien ne doit être accessible depuis Internet. jtl-bridge tourne sur le serveur Wawi et téléverse uniquement via HTTPS. Les données sont en plus chiffrées avec une clé issue du jeton d'import.
• La clé API et le code de configuration sont comme des mots de passe : ne les envoie pas par e-mail, ne les copie pas dans des tickets. allverto enregistre la clé API chiffrée et ne l'affiche jamais. Le code de configuration est valable 30 jours à chaque fois (prolongeable), au plus jusqu'à la finalisation de la migration.
• Avec Tester la connexion, allverto ne vérifie lui-même une adresse que si elle est accessible depuis Internet. Pour localhost ou une adresse du réseau de l'entreprise, c'est jtl-bridge qui fait le test et transmet le résultat.
• Après la migration, tu peux supprimer l'application « allverto – Umzug von JTL-Wawi » dans la Wawi sous „Anwendungsregistrierungen“.

#Dépannage

Plus de cas : Dépannage de la migration JTL.