Configurer l'API REST de JTL-Wawi

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 votre Wawi sans accéder directement à la base de données. Cette page explique ce que vous devez configurer pour cela dans la Wawi.

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

Imaginez le serveur REST comme le guichet d'accueil de votre 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 s'exécute dans votre réseau d'entreprise, généralement sur le même ordinateur que la Wawi ou son SQL Server.
• Il est accessible via une adresse comme http://wawi-server:5883/api/eazybusiness. wawi-server est le nom ou l'IP de votre ordinateur, 5883 le port (il peut être différent chez vous), eazybusiness le nom de votre base de données Wawi.
• Chaque programme doit s'enregistrer une fois comme application. Vous confirmez l'enregistrement dans la Wawi, puis 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 votre 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. Connectez-vous à JTL-Wawi avec un utilisateur disposant de droits d'administration.
2. Configurez le serveur REST comme JTL le décrit pour votre version, puis démarrez-le. Notez le port sur lequel il écoute.
3. Vérifiez que le serveur fonctionne : un ordinateur du réseau de l'entreprise doit pouvoir atteindre l'adresse http://<wawi-server>:<port>/api/eazybusiness (ouvrez ce port dans le pare-feu de l'ordinateur Wawi pour le réseau interne).

#2. Enregistrer allverto comme application

Vous lancez l'enregistrement avec l'utilitaire jtl-bridge sur un ordinateur du réseau de l'entreprise :

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

1. jtl-bridge envoie la demande d'enregistrement à votre serveur REST et indique : « Registrierung gesendet … Bitte jetzt in der JTL-Wawi unter Admin → App-Registrierung bestätigen » (enregistrement envoyé … veuillez maintenant confirmer dans JTL-Wawi sous Admin → App-Registrierung).
2. Dans la Wawi, ouvrez l'App-Registrierung (enregistrement d'application). D'après notre documentation, l'entrée s'appelle ainsi dans la Wawi 2.2 : Admin → App-Registrierung. La demande de allverto – Umzug von JTL-Wawi y figure avec les droits demandés.
3. Vérifiez les droits (lecture seule, impression des factures en option) et confirmez la demande.
4. jtl-bridge vérifie toutes les 5 secondes. Après la confirmation, il affiche la clé API – une seule et unique fois. Copiez-la immédiatement.
5. Si vous ne confirmez pas dans les 10 minutes, jtl-bridge s'interrompt – relancez alors simplement l'enregistrement.

#3. Saisir dans allverto

1. Ouvrez Paramètres → Reprise de données → Migration depuis JTL-Wawi, étape Connecter la source.
2. Choisissez API JTL-Wawi.
3. Sous Adresse de l'API Wawi, saisissez l'adresse de l'étape 1, p. ex. http://wawi-server:5883/api/eazybusiness.
4. Collez la Clé API. allverto l'enregistre de manière chiffrée ; à la prochaine ouverture, le champ indique « Enregistrée – laisser vide pour la conserver ».
5. ID du mandant (facultatif) : à remplir uniquement si votre Wawi en exige un. Pour une Wawi installée en interne, le champ reste généralement vide.
6. Laissez Récupérer les PDF des factures via l'API activé si vos factures doivent être reprises en PDF (la Wawi les régénère pour cela).
7. Facultatif : renseignez le SQL Server – jtl-bridge complète alors ce que l'API ne fournit pas (voir ci-dessous).
8. Cliquez sur Enregistrer la source.

#4. Téléverser les données

Comme le serveur REST n'est accessible que dans le réseau de l'entreprise (et doit le rester), c'est jtl-bridge qui téléverse les données : Générer un jeton d'import, puis exécutez la commande affichée dans le réseau de l'entreprise, p. ex.

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

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 vous lancez jtl-bridge avec --fill-from-db et avez en plus renseigné le SQL Server dans allverto, il 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. Un utilisateur de base de données en lecture seule suffit. Sans base de données, ces données manquent – tout le reste est néanmoins repris.

#Sécurité et réseau

• Le serveur REST reste dans le réseau de l'entreprise. N'exposez pas le port sur Internet. jtl-bridge s'exécute en interne, lit le serveur REST et téléverse les données vers l'extérieur – aucune connexion entrante n'est nécessaire.
• jtl-bridge téléverse uniquement via HTTPS. Les données sont en outre chiffrées avec une clé dérivée du jeton d'import.
• La clé API et le jeton d'import sont comme des mots de passe : ne les envoyez pas par e-mail, ne les copiez pas dans des tickets. Le jeton d'import est valable jusqu'à la fin de la migration ; il devient ensuite invalide.
• Récupérer les données directement ne fonctionne que si l'API Wawi est accessible depuis Internet. Nous ne le recommandons qu'avec un accès sécurisé (p. ex. HTTPS via un reverse proxy avec restriction d'accès). En règle générale, utilisez jtl-bridge.
• Après la migration, vous pouvez supprimer l'enregistrement d'application d'allverto dans la Wawi.

#Dépannage

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