Clés API et webhooks
Créer des clés pour votre propre ERP, TMS ou WMS, configurer des webhooks, et les clés NAV pour les itinéraires et les adresses.
INTEGALL dispose de deux types de clés pour les systèmes externes :
- Clés API et webhooks pour l'API INTEGALL : lire les envois, demander des transports, lire les factures et recevoir des messages lors d'un événement. Vous les trouvez en bas de ParamètresIntégrations, sur la carte API et webhooks.
- Clés NAV pour le serveur NAV d'INTEGALL (itinéraires et adresses). Vous les trouvez sous ParamètresClés API.
La description technique destinée à votre partenaire informatique se trouve sous Développeurs (API).
Créer une clé API#
- Allez dans ParamètresIntégrations et faites défiler jusqu'à API et webhooks. Vous y trouvez aussi l'Adresse de l’API et un lien vers la Description technique (OpenAPI).
- Choisissez + Nouvelle clé API.
- Saisissez un Nom (à quoi sert cette clé ?), par exemple Connexion ERP.
- Choisissez les Autorisations : Lire les envois, Demander des transports, Lire les factures, Gérer les webhooks. N'accordez que ce dont le système a besoin.
- Cochez éventuellement Clé de test (les écritures sont seulement vérifiées, rien n’est enregistré) pour tester d'abord.
- Choisissez combien de temps la clé est Validité : jusqu’à révocation, 30, 90 ou 365 jours.
- Saisissez le code de votre application d'authentification et choisissez Créer la clé.
- La clé n'est affichée qu'une seule fois. Copiez-la avec Copier, conservez-la en lieu sûr (par exemple dans un gestionnaire de mots de passe) et choisissez Je l’ai conservé.
Vous pouvez avoir au maximum 20 clés actives.
Gérer les clés#
Le tableau indique pour chaque clé le Nom, les Autorisations (avec Essai pour une clé de test), le Statut (Actif, Retirée ou Expirée) et l'Utilisation : quand la clé a été utilisée pour la dernière fois et combien d'appels ont eu lieu au cours des dernières 24 heures.
Avec Retirer et Oui, révoquer, une clé cesse immédiatement de fonctionner. Pour remplacer une clé, procédez ainsi : créez une nouvelle clé, installez-la dans votre système, puis révoquez l'ancienne.
Webhooks#
Avec un webhook, INTEGALL envoie un message à votre adresse dès qu'un événement se produit. Chaque message est signé (X-INTEGALL-Signature).
- Choisissez + Nouveau webhook.
- Saisissez l'Adresse (https), par exemple
https://erp.uwbedrijf.be/integall. L'adresse doit être en https, avec un nom de domaine public (pas d'adresse IP ni de nom interne). - Choisissez les Événements : Statut d’un envoi modifié, Facture définitive et Facture payée.
- Saisissez le code de votre application d'authentification et choisissez Ajouter le webhook.
- Le secret de signature n'est affiché qu'une seule fois. Transmettez-le à votre partenaire informatique ; celui-ci s'en sert pour vérifier chaque message.
Pour chaque webhook, vous voyez la dernière livraison avec le statut HTTP, le nombre de messages en file d'attente et le nombre d'échecs au cours des 7 derniers jours, et sous Dernières livraisons les détails.
- Envoyer un message de test : un message de test part dans la minute.
- Renvoyer les échecs : renvoie les livraisons échouées des 7 derniers jours.
- Désactiver ou Activer, et Supprimer.
Une livraison échouée est retentée pendant environ 28 heures. Si votre adresse ne répond pas pendant plus de 24 heures, INTEGALL désactive automatiquement le webhook, en indiquant la raison. Vous pouvez avoir au maximum 10 webhooks.
Clés NAV#
ParamètresClés API affiche les Clés NAV : des clés pour les systèmes externes (ERP, TMS) qui demandent des itinéraires ou des adresses au serveur NAV d'INTEGALL. L'application du bureau et l'application chauffeur n'ont pas besoin de clé ; elles utilisent leur propre connexion.
Droits : Calculer des itinéraires, Rechercher des adresses, Tuiles de carte et Remplacer le profil du véhicule. Ici aussi, la clé n'est affichée qu'une seule fois et la création demande un code récent.