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

Synchronisteur

igfactapi.exe /RunSync

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

Open

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 : 

Open

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.