Cette fonctionnalité est un module optionnel de IGFact. L’API vous permet de connecter per exemple un site Web à IGFact.
L’API permet de rendre les données de IGFact disponibles pour d’autres services également.
IGFactapi.exe est également un utilitaire qui fonctionne en ligne de commande pour exécuter des tâches indépendamment de IGFact.
Paramètres en ligne de commande
Correction de stock
igfactapi.exe /CorrStock /Mailto:support@igsoft.be /Numsoc=1
Permet de lancer une correction des écarts de stock en stociété 1 et d’envoyer le résultat des correcions à l’adresse indiquée.
igfactapi.exe /RunSync
Lance le synchronisateur pour les requêtes venant du webshop (boule bleue)
Paramétrage dans IGFact
Quand nous vous activons le module de l’API, vous recevrez un email qui vous permettra de définir votre mot de passe d’accès à l’API.
Ensuite vous aurez donc les deux paramètres vous permettant de configurer IGFact.
Un login (adresse email)
Un mot de passe
Pour activer le module, il faut aller dans le menu Utilitaires > Configuration > Paramètres de liaison avec IGFact API
Dans cet écran, indiquez juste votre login et votre mot de passe., puis validez sur le V vert.
Migration des données
Afin que vos données soient accessibles par un service externe, il faut les synchroniser dans le Cloud.
Pour cela, allez dans le menu Utilitaires > Fichiers > Exportation > Exportation IGFact Web
Cette étape permet de vérifier la cohérence de vos données et de les envoyer dans le Cloud.
L’opération n’est à effectuer qu’une seule fois, car par la suite les données sont mises à jour en temps réel par IGFact.
Cochez bien la case “Vérifier la cohérence” avant de démarrer la procédure.
Documentation de l’API
Les développeurs de sites web ou de services externes peuvent consulter le swagger de l’API à l’adresse suivante:
https://igfact-ws.igsoft.eu/swagger/index.html
Contactez nous si vous souhaitez plus d’information à ce sujet.
Objectifs
Synchronisation des articles
Synchronisation des disponibilités articles
Synchronisation des clients
Synchronisation des factures effectuées sur le webshop dans un journal spécifique de IGFact
Aspects techniques
Sécurité
Les APIs font l’objet d’une authentification au moyen d’un standard actuel en la matière (Token, Clé d’API, … ) et utilisent un système de documentation comme Swagger (OpenAPI) afin de faciliter les échanges entre les deux plate-formes.
Il vous sera fourni:
un login = votre adresse email
vous recevrez un mail à cette adresse pour définir votre mot de passe
un numéro de série (SerialNumber)
Deux manières de fonctionner
L’Api peut être utilisée de deux manières:
indépendante: une application tierce a juste besoin de consulter les données de IGFact, dans ce cas, login au moyen de Token/LoginUser
dépendante d’une application tierce (par exemple Prestashop): login au moyen de Token/LoginExtenalLink
La version dépendante permet à IGFact Api de fournir un webhook qui sera appelé par l’application dépendante quand un événement survient sur le webshop (une nouvelle commande est passée par exemple). Ainsi l’API IGFact va pouvoir aller récupérer la commande sur le webshop.
Objets
De manière générale, les objets disponibles dans l’API devront implémenter les méthodes suivantes :
Un webhook pour notifier d’un ajout / mise à jour / suppression qui contiendra l’objet modifié au format de l’API émettrice.
Une méthode pour récupérer tous les changements effectuées depuis un timestamp UTC
Une méthode pour récupérer l’ensemble de la liste (en cas de migration initiale ou de mise à jour complète)
Une méthode pour récupérer un objet spécifique sur base de sa clé unique.
Il sera de la responsabilité de chaque API de convertir les données fournies par les webhook afin de réaliser l’intégration des changements.
Suppressions
Afin d’éviter tout problème (serveur indisponible pendant un webhook par exemple, la suppression d’un objet ne devra jamais être une suppression physique mais bien un flag indiquant que l’objet est effacé. Ainsi, les méthodes qui récupèrent les changements depuis un timestamp UTC auront également accès aux éléments effacés.
Webhooks
Les webhooks devront être déclenchés pour les différentes opérations CRUD, pour rappel :
Create
Update
Delete
Administration des Webhooks
Une page de gestion des webhooks est disponible à l’adresse https://igfact.igsoft.eu afin de paramétrer ceux-ci.
Interactions prévues
Produits
La clé unique sera la référence d’article de IGFact.
Les données des produits sont gérées et créées principalement sur le site web.
La création / modification d’un article sur le webshop, engendre une notification à l’API de IGFact via un webhook contenant l’objet mis à jour, au format défini par le webshop.
La référence IGFact sera attribuée du côté du Webshop, mais celui-ci devra vérifier qu’elle n’est pas déjà utilisée dans IGFact afin d’éviter les doublons.
La modification d’un article dans IGFact, engendre une notification à l’API du Webshop via un webhook contenant l’objet au format défini par IGFact.
Disponibilité des produits
Les données de disponibilité des produits sont gérées des deux côtés.
Il faudra envisager les conflits de réservation d’articles entre IGFact et le Webshop afin d’éviter que deux utilisateurs réservent le même article. Nous suggérons que 3 données soit gérées : Le stock physique, une quantité réservée dans IGFact (commandes, … ), une quantité réservée dans le web (paniers).
La mise à jour de la quantité réservée coté webshop engendre une notification à l’API de IGFact via un webhook au format défini par le webshop
La mise à jour du stock ou de la quantité réservée dans IGFact engendre une notification à l’API du Webshop via un webhook contenant l’objet au format défini par IGFact.
Le stock physique sera géré intégralement au niveau de IGFact, et ce afin de maintenir le contrôle de celui-ci en un seul et même endroit. Il sera mis à jour à la création des factures et renvoyé à chaque changement de IGFact.
La quantité réservée dans le webshop devra impérativement être maintenue à jour et libérée en cas de panier abandonné pour ne pas entraver les ventes dans IGFact.
Clients
La clé unique sera la référence client de IGFact
Les clients seront générés à l’inscription sur le site web. Un webhook signale les ajouts/modifications à IGFact au format défini par le Webshop. IGFact renverra ensuite une mise à jour avec la référence générée dans IGFact.
Les ajouts/mises à jour effectuées du côté de IGFact engendreront une notification à l’API du Webshop via un webhook au format défini par IGFact.
Factures
Les factures seront générées sur le Webshop. Un webhook signale les ajouts/modification à IGFact au format défini par le Webshop. IGFact intégrera ces documents dans un journal spécifique au Webshop.
Il n’y a pas de mise à jour prévue au départ de IGFact vers le Webshop.
Description de l’API
Chaque objet disponible dispose des mêmes méthodes génériques. Seules les méthodes en lecture sont disponibles au départ d’une application tierce.
A savoir :
/api/ObjectName/GetAll
Donne la liste complète des objets disponibles./api/ObjectName/GetPage
Donne la liste complète des objets disponibles par page de taille spécifique (maximum 100) et avec éventuellements des filtres appliqués ou un tri.Il est également possible de spécifier si l’on veut ou non avoir les traductions liées aux objets
/api/ObjectName/GetById/{id}
Donne l’objet défini par l’id fourni en paramètre dans l’URL/api/ObjectName/GetLatest/{from}
Donne la liste des objets modifiés depuis le timestamp UTC fourni dans l’url
L’API requiert une Authentification via un token d’API qui peut être récupéré via un objet propre à l’authentification, à savoir l’objet Token de l’API.
Le format des objets est décrit dans le bas de la page swagger :
Les valeurs énumérables sont également disponibles :
Authentification
Pour s’authentifier sur l’API en tant qu’application tierce, il faudra faire un POST sur
Méthode indépendante
https://igfact-ws.igsoft.eu/api/Token/LoginUser
Dans le body de la requête, il faudra fournir cet objet :
{
"Email": "votre@email.com",
"Password": "****",
"SerialNumber": "99999999999"
}
La réponse vous donnera le Token dont vous avez besoin pour utiliser l’API
Méthode dépendante
https://igfact-ws.igsoft.eu/api/Token/LoginExtenalLink
Dans le body de la requête, il faudra fournir cet objet :
{
"Email": "votre@email.com",
"Password": "****",
"SerialNumber": "99999999999"
}
La réponse vous donnera le Token dont vous avez besoin pour utiliser l’API
Avec pour Header :
Content-Type: application/json
X-Tenant-Guid : 99999999999
Et en Authorisation:
La réponse contiendra un objet json avec le token et sa validité UTC (DateExpire) pour appeler les différentes méthodes de l’API :
{
"Email": "votre@email.com",
"Password": "****",
"Token": "ey1JhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy933cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9lbWFpbGFkZHJlc3MiOiJqdWFuQGlnc29mdCZSIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eSTgzODU1MzY4LCJpc3MiOiJsb2NhbGhvc3Q6ODA2MCIsImF1ZCI6ImxvY2FsaG9zdDo4MDYwIn0.G2osnX84qEagswBkzjo96ChPke2_shKhcgaV2XlP7cc",
"SerialNumber": "99999999999",
"UserInstallModules": null,
"AppId": 6,
"AppPlateformeId": 1,
"LegacyId": 9,
"UserId": 128,
"DateExpire": "2020-03-10T16:49:28.818716+01:00"
}
Webhooks
Pour adapter les URLs des webhooks, et en consulter les notifications, vous pouvez vous rendre sur https://igfact.igsoft.eu. Vous loguer avec votre compte et votre SerialNumber sans cocher la case “Admin”.
Dans la section WebHook , vous pouvez adapter les URLs correspondant aux évènements Create, Update et Delete.
Vous pouvez consulter toutes les notifications émises dans la section Tracking WebHook Out
Vous pouvez également vérifier l'état des stocks des produits dans la section product (les images sont auto-généré et n'ont donc pas de rapport avec le produit).
Vous avez ainsi tous les outils nécessaires pour la mise en place et les mises à jour éventuelles d'url pour les notifications.