Introduction
L’objectif de ce document est de décrire le fonctionnement des appels APIs pour les échanges de données avec la solution CRM.
L’URL permettant d’accéder aux APIs pour les projets hébergés en Europe est « https://api.weavy.divalto.com » et sera rappelée dans la suite du document par l’alias « {{apiBaseUrl}} ».
Pour les projets hébergés en Amérique du Nord, veuillez utiliser l'URL « https://swing-ca.swingmobility.com » à la place.
Les clés uniques (codes) sont nommées de la manière suivante : [nomEntité]_ID, on y transmet et récupère les codes du SI.
Authentification
Cette étape permet de s’authentifier sur le serveur.
URL : {{apiBaseUrl}}/v1/Authenticate
Méthode : POST
Document à envoyer :
{
"scope": "API",
"projectCode": "PROJECTCODE",
"userName": "USERNAME",
"password": "PASSWORD"
}
scope : Constante. Ne pas modifier.
projectCode : code du projet auquel se connecter.
userName : nom d’utilisateur du projet à employer pour se connecter.
password : mot de passe de l’utilisateur à connecter.
Document à réceptionner :
{
"authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 43200,
"generatedTimeUTC": "2017-12-05T22:56:34.9748003Z",
"passwordExpiryUTC": null
}
authToken : token d’authentification réceptionné une fois la connexion établie.
expiresIn : temps de validité du token en secondes.
generatedTimeUTC : date et heure d’attribution du token.
passwordExpiryUTC : date et heure d'expiration du mot de passe si celle-ci est définie.
Ce token est signé et est à utiliser pour toutes les opérations suivantes (bearer token).
Format des données
Concernant les types de données, voici les formats à respecter :
Booléen : true/false
Entier : la valeur entière
Date et heure : YYYY-MM-DDTHH:MM:SS (exemple : 2016-12-05T08:33:33)
Décimal : la valeur décimale avec le point comme séparateur (exemple : 69.33)
Chaîne de caractères : entre double-quote en respectant les échappements JSON
Données binaire : chaîne au format Base64 entre double-quote
Découverte des entités disponibles
Si vous souhaitez connaitre les entités accessibles avec cette API, vous pouvez utiliser la méthode suivante :
URL : {{apiBaseUrl}}/v1/Dictionary/[codeProjet]
Méthode : GET
Document à réceptionner :
[
{
"entityName": "customer",
"translations": [
{
"languageCode": "DE",
"text": "Kunde"
},
{"languageCode": "EN", "text": "Customer" },
{"languageCode": "FR", "text": "Client" }
],
"fields": []
},
{
"entityName": "product",
"translations": [
{"languageCode": "DE","text": "Artikel"},
{"languageCode": "EN","text": "Product"},
{"languageCode": "FR","text": "Article"}
],
"fields": []
}
]
Le document contient la liste des entités accessibles depuis l'API avec au moins une autorisation activée (lecture, ajout, modification, suppression).
Le détail des champs n'est volontairement pas fourni lors de cet appel. Vous devez ensuite demander le détail d'une entité.
Pour connaitre le détail d'une entité, vous pouvez utiliser la méthode suivante :
URL : {{apiBaseUrl}}/v1/Dictionary/[codeProjet]/[entité]
entité : nom de la table (sans « sw_data_ »).
Méthode : GET
Document à réceptionner :
{
"entityName": "customer",
"translations": [
{"languageCode": "DE","text": "Kunde"},
{"languageCode": "EN","text": "Customer"},
{"languageCode": "FR","text": "Client"}
],
"fields": [
{
"fieldName": "CodeCustomer",
"translations": [
{"languageCode": "DE","text": "Kunde"},
{"languageCode": "EN","text": "Account code"}
{"languageCode": "FR","text": "Code Tiers"}
],
"fieldType": "text",
"fieldLength": 255
},
{
"fieldName": "baseuser_ID",
"translations": [
{"languageCode": "DE","text": "Basis / Benutzer"},
{"languageCode": "EN","text": "Base / User"}
{"languageCode": "FR","text": "Base / Utilisateur"}
],
"fieldType": "text(foreignkey)",
"fieldLength": null
},
{
"fieldName": "name",
"translations": [
{"languageCode": "DE","text": "Name"},
{"languageCode": "EN","text": "Name"},
{"languageCode": "FR","text": "Nom"}
],
"fieldType": "text",
"fieldLength": 255
}
]
}
Récupération simple des données
Cette opération permet de récupérer un paquet de données d’une entité (limité à 1000 enregistrements).
URL : {{apiBaseUrl}}/v1/Data/[codeProjet]/[entité][?options]
entité : nom de la table (sans « sw_data_ »).
Méthode : GET
Options : La première est précédée de « ? ». Les différentes options employées sont séparées par « & ».
limit=valeur : limite le nombre d’enregistrements renvoyés dans le document.
offset=valeur : offset du premier enregistrement à retourner dans le document.
srvAttrib=valeur : permet de filtrer les résultats sur la valeur du champ srvAttrib (suppression logique). Par défaut, seuls les enregistrements pour lesquels srvAttrib est égal à zéro.
serverExport=valeur : permet de filtrer les résultats sur la valeur du champ srvExport (à exporter).
Document à réceptionner :
[
{
"srvExport": 0,
"srvDateUTC": "2016-02-16T10:38:28",
"srvAttrib": 0,
"customer_ID": "COLOMB",
"baseuser_ID": "APB",
"name": "COLOMBE DIAMANTS",
…
},
{ Enregistrement2 },
{ Enregistrement3 },
…]
Le document contient la liste des enregistrements compris entre crochets « [ ] ». Chaque enregistrement est contenu entre accolades « { } » et est décrit par la liste exhaustive de ses champs (champ:valeur).
Récupération des données avec filtrage avancée
Cette opération permet de récupérer un paquet de données d’une entité (limité à 1000 enregistrements).
URL : {{apiBaseUrl}}/v1/Data/[codeProjet]/Select
Méthode : POST
En-têtes : Content-Type=application/json
Contrairement à la méthode précédente, il est possible de personnaliser la manière dont les données sont retournées :
Sélection des champs de l'entité à retourner avec éventuellement spécification d'alias sur les noms des champs.
Définition d'une série de filtres à appliquer à la requête. Par défaut l'opérateur "AND" est automatiquement utilisé entre les filtres.
Définition d'une série de groupes de filtrage à appliquer à la requête. Ceci permet de personnaliser l'opérateur à utiliser entre les filtres et de construire un filtrage plus avancé.
Tri des résultats de la requête sur un ou plusieurs champs.
Document à envoyer :
{
"companyCode": "RHOL",
"entityName": "product",
"srvExport": 0,
"srvAttrib": 0,
"limit": 20,
"offset": 0,
"returnFields": [
{
"fieldName": "description",
"aliasName": "designation"
},
{
"fieldName": "productfamily_ID"
},
{
"fieldName": "product_ID",
"aliasName": "productCode"
},
{
"fieldName": "saleMultiple"
}
],
"filterFields": [
{
"companyCode": "COMPANY",
"filterKey": "branchOfficeKey",
"fieldName": "branchoffice_ID",
"operator": "Equal",
"filterValues": [
"Office"
]
},
{
"filterKey": "descriptionKey",
"fieldName": "description",
"operator": "StartWith",
"filterValues": [
"BOUTON FK"
]
},
{
"filterKey": "saleMultipleKey",
"fieldName": "saleMultiple",
"ifNullValue": 1,
"operator": "GreaterThanOrEqual",
"filterValues": [
5
]
}
],
"filterGroups": [
{
"groupLogicalOperator": "AND",
"filterKeys": [
"descriptionKey",
"saleMultipleKey"
],
"groupKeys": [
"subGroup"
]
},
{
"groupKey": "subGroup",
"groupLogicalOperator": "OR",
"filterKeys": [
"descriptionKey",
"saleMultipleKey"
]
}
],
"sortFields": [
{
"fieldName": "description",
"sortOrder": "Descending"
},
{
"fieldName": "defaultPrice",
"sortOrder": "Ascending"
}
]
}
Paramétrage du corps de la requête (format JSON) :
companyCode (optionnel) : code de la société pour le filtrage des données. Par défaut, le code société associé à l'utilisateur connecté est utilisé.
entityName (obligatoire) : nom de la table (sans « sw_data_ »).
limit (optionnel) : limite le nombre d’enregistrements renvoyés dans le document. Par défaut, limité à 1000 enregistrements.
offset (optionnel) : offset du premier enregistrement à retourner dans le document. Par défaut, les lignes retournées commencent à l'index 0.
srvAttrib (optionnel) : permet de filtrer les résultats sur la valeur du champ srvAttrib (suppression logique). Par défaut, seuls les enregistrements pour lesquels srvAttrib est égal à zéro sont retournés.
srvExport (optionnel) : permet de filtrer les résultats sur la valeur du champ srvExport (à exporter).
returnFields (obligatoire) : liste des champs à retourner.
fieldName (obligatoire) : nom du champ à sélectionner.
aliasName (optionnel) : nom du champ à retourner dans le document.
filterFields (optionnel) : liste des champs sur lesquels il faut effectuer un filtrage de données.
companyCode (optionnel) : permet d’indiquer un code société dans le cas où le filtre est basé sur une table étrangère.
filterKey (optionnel) : permet d'identifier un filtre pour être utilisé ensuite dans un groupe de plusieurs filtres.
fieldName (obligatoire) : nom du champ à filtrer.
ifNullValue (optionnel) : valeur par défaut dans le filtre si la valeur n'est pas définie en base.
operator (obligatoire) : défini l'opérateur à appliquer dans le filtrage du champ. Les opérateurs possibles dépendent du type de champ, se référer à la matrice ci-dessous.
filterValues (obligatoire/optionnel en fonction de l'opérateur) : défini la ou les valeurs à utiliser dans le filtrage du champ. Pour certains opérateurs, ce champ doit rester vide.
filterGroups (optionnel) : liste des groupes de filtres sur lesquels il faut effectuer un filtrage de données.
groupKey (optionnel) : permet d'identifier un groupe pour être utilisé ensuite en tant que sous-groupe dans un groupe. Un groupe peut être déclaré dans plusieurs sous-groupes. Il n'est pas possible de faire des boucles infinies. Si les groupes sont utilisés, au minimum un groupe ne doit appartenir à aucun sous-groupe (groupe racine).
groupLogicalOperator (optionnel) : permet de définir l'opérateur logique à utiliser entre les filtres du groupe : valeurs possibles "AND" / "OR". Par défaut, l'opérateur "AND" est utilisé.
filterKeys (obligatoire) : liste des identifiants de filtre à inclure dans le groupe. Cette liste est automatiquement dédoublonnée (une seule occurance de filtre par groupe).
groupKeys (optionnel) : liste des identifiants de groupe à inclure dans le groupe (sous-groupes). Cette liste est automatiquement dédoublonnée (une seule occurance de sous-groupe par groupe).
sortFields (optionnel) : liste des champs sur lesquelles faire le tri des résultats retournés. Le tri est fait dans l'ordre de déclaration des champs.
fieldName (obligatoire) : nom du champ à trier.
sortOrder (optionnel) : sens du tri à appliquer : valeurs possibles "Ascending" / "Descending". Par défaut, le sens "Ascending" est utilisé.
Matrice des opérateurs autorisés en fonction du type de champ (est précisé les données à fournir en tant que valeur pour le filtre) :
Integer / Double / DateTime :
Undefined : aucune valeur de filtre
Defined : aucune valeur de filtre
Equal : une seule valeur de filtre
Different : une seule valeur de filtre
LessThanOrEqual : une seule valeur de filtre
LessThan : une seule valeur de filtre
GreaterThanOrEqual : une seule valeur de filtre
GreaterThan : une seule valeur de filtre
InList : une ou plusieurs valeurs de filtre
String :
Undefined : aucune valeur de filtre
Defined : aucune valeur de filtre
Equal : une seule valeur de filtre
Different : une seule valeur de filtre
StartWith : une seule valeur de filtre
InList : une ou plusieurs valeurs de filtre
Boolean :
Undefined : aucune valeur de filtre
Defined : aucune valeur de filtre
IsTrue : aucune valeur de filtre
IsFalse : aucune valeur de filtre
Blob :
Undefined : aucune valeur de filtre
Defined : aucune valeur de filtre
ForeignKey :
Undefined : aucune valeur de filtre
Defined : aucune valeur de filtre
Equal : une seule valeur de filtre
Different : une seule valeur de filtre
InList : une ou plusieurs valeurs de filtre
Toute autre combinaison est strictement prohibée.
Le format du document à réceptionner est identique à la méthode dite simple.
Gestion d’enregistrement
Ces méthodes permettent de gérer les enregistrements de manière unitaires en mode CRUD.
URL : {{apiBaseUrl}}/v1/Data/[codeProjet]/[entité]/[idEnregistrement]
Les actions sont gérées de manière atomique ; si l’une des actions échoue ou si l’une des clés étrangères utilisées n’est pas valide, l’ensemble de la transaction est annulé.
Création d’un enregistrement
Méthode : POST
Document à envoyer :
{
"customer_ID": "RH-TEST-03",
"baseuser_ID": "KB",
"name": "Nikita",
"address1": "36 rue Henri Louisette",…
}
Le code enregistrement n’est pas à renseigner pour ce cas.
Il faut positionner le paramètre « Content-Type » à la valeur « application/json ».
Le document contient l’enregistrement à insérer contenu entre accolades « { } ». Il est décrit par la liste exhaustive de ses champs à intégrer (champ:valeur) ; un champ non renseigné est initialisé avec la valeur « null ».
Lecture d’un enregistrement
Méthode : GET
Document à réceptionner :
{
"customer_ID": "RH-TEST-03",
"baseuser_ID": "KB",
"name": "Nikita",
"address1": "36 rue Henri Louisette",…
}
Le document contient l’enregistrement dont l’ID est passé dans l’URL. Il est décrit par la liste exhaustive de ses champs (champ:valeur).
Mise à jour d’un enregistrement
Méthode : PUT
Document à envoyer :
{
"name": "NewValue",
"baseuser_ID": "APB"
}
Il faut positionner le paramètre « Content-Type » à la valeur « application/json ».
Le document contient les champs à mettre à jour pour l’enregistrement (champ:valeur) dont l’ID est passé dans l’URL ; les champs absents ne sont pas modifiés et l’ID de l’enregistrement n’est pas à préciser dans le document.
Suppression d’un enregistrement
Méthode : DELETE
Cette méthode supprime l’enregistrement dont l’ID est passé dans l’URL.
Il est possible d'effectuer soit une suppression physique (la ligne est réellement supprimée de la base de données), soit une suppression logique (la valeur du champ "srvAttrib" est mise à 1).
Pour ce faire, vous devez préciser le type d'action souhaité avec le paramètre "deleteMode" qui peut prendre les valeurs :
Physical
Logical
Exemple : ?deleteMode=Physical
Import Dataset
Cette opération permet de transmettre un document contenant un Dataset complet et permet d’intégrer les données sous la forme de paquets.
URL : {{apiBaseUrl}}/v1/Data/[codeProjet]/DataSet?[deleteMode]&[companyCode]&[srvExport]
Méthode : POST
DeleteMode : le mode de suppression est obligatoire et permet de déterminer le comportement de l’API concernant les enregistrements liés à l’enregistrement principal, et dont l’entité est citée dans le document, qui seraient absents du document. Trois modes sont distingués :
deleteMode=0 : aucune suppression n’est effectuée
deleteMode=1 : les enregistrements absents sont supprimés de manière logique (prévu mais non fonctionnel à ce jour)
deleteMode=2 : les enregistrements absent sont supprimés de manière physique.
srvExport (obligatoire) : permet de spécifier la valeur à mettre à jour pour le statut “export” (champ “srvExport”).
companyCode (optionnel) : code de la société pour le filtrage des données. Par défaut, le code société associé à l'utilisateur connecté est utilisé.
Document à envoyer :
{
"intervention": {
"intervention_ID": "INTER-SWM-01",
"customeraddress_ID": "SWING",
"startDate": "2017-11-27 08:30:00",
"endDate": "2017-11-27 17:00:00",
"interventiontype_ID": "MAINT",
"interventionpart": [{
"interventionpart_ID": "INTER-SWM-01-1",
"intervention_ID": "INTER-SWL-01",
"interventionequipment_ID": "BEU0364/3-1",
"product_ID": {
"product_ID": "CHRONO345/1",
"description": "Chrono 0345 1",
"productfamily_ID": {
"productfamily_ID": "CHRONO",
"label": "Chrono",
"productfamily_ID_parentfamily": {
…
}
}
},
"lineNumber": "1",
"estimatedQuantity": "2",
"productdepot_ID_source": "DPO-PRINC",
"removeFromStock": "1"
}, {
"interventionpart_ID": "INTER-SWM-01-2",
"intervention_ID": "INTER-SWM-01",
"interventionequipment_ID": "BEU0364/3-1",
"product_ID": " CHRONO343"
"lineNumber": "2",
"estimatedQuantity": "1",
"productdepot_ID_source": "DPO-PRINC",
"removeFromStock": "1"
}]
}
}
Il faut positionner le paramètre « Content-Type » à la valeur « application/json ».
L’ensemble des traitements s’articule autour de l’enregistrement principal (le premier du document) et de son entité. Il ne peut y avoir qu’un seul enregistrement pour cette entité dans le document, mais il n’y a pas de limite d’enregistrements liés, ou de niveaux de parenté.
Le document est traité de manière atomique ; si l’une des actions échoue ou si l’une des clés étrangères utilisées n’est pas valide, l’ensemble de la transaction est annulé.
Les traitements sont effectués en mode différentiel ; les données présentes mais non modifiées par rapport au contenu actuel de la base ne seront pas mises à jour. Par conséquent, les enregistrements pour lesquels aucune modification n’est apportée ne seront pas détectés comme à synchroniser sur les devices.
Les suppressions en cascade ne sont pas gérées ; seuls les enregistrements liés à un enregistrement parent défini dans le document et dont l’entité est citée dans le document sont concernés.
Validation des données exportées pour une entité
Une fois un jeu de données récupéré, il est utile de mettre à jour le statut "export" de ces mêmes données sur le serveur afin de ne pas avoir à les retraiter jusqu'à leur prochaine modification.
Pour ce faire, il faudra renseigner le code des enregistrements des lignes à valider ainsi que leur date de dernière modification sur le serveur. Ceci permet de s'assurer que ces données n'ont pas été modifiées entre leur récupération et la demande de validation de l'export.
Si ce cas devait se produire, il convient de redemander la lecture de ces enregistrmements afin de ne pas perdre d'information en cours de route.
URL : {{apiBaseUrl}}/v1/Data/[codeProjet]/ValidateExport
La validation des exports est gérée de manière atomique ; si l’une des mises à jour échoue, l’ensemble de la transaction est annulé.
Méthode : POST
Document à envoyer :
{
"companyCode": "RHM5",
"entityName": "product",
"srvExport": 0,
"rows": [
{
"rowCode": "9222",
"srvDateUTC": "2019-08-21T15:32:06"
},
{
"rowCode": "0223",
"srvDateUTC": "2019-08-21T15:32:06"
},...
]
}
Paramétrage du corps de la requête (format JSON) :
companyCode (optionnel) : code de la société pour le filtrage des données. Par défaut, le code société associé à l'utilisateur connecté est utilisé.
entityName (obligatoire) : nom de la table (sans « sw_data_ »).
srvExport (obligatoire) : permet de spécifier la valeur à mettre à jour pour le statut "export" (champ "srvExport").
rows (obligatore) : liste des enregistrements à mettre à jour avec la valeur du champ "srvExport".
rowCode : code unique de l'enregistrement pour une société (dans le cas d'un projet "multi-société" il faut renseigner la propriété "companyCode" ci-dessus).
srvDateUTC : date de dernière modification de l'enregistrement sur le serveur à retourner à partir des données lues en amont.
Validation des données exportées pour plusieurs entités
Il est également possible de mettre à jour le statut "export" de plusieurs entités simultanément.
Les conditions sont les mêmes que pour la validation d'une seule entité.
URL : {{apiBaseUrl}}/v1/Data/[codeProjet]/ValidateExportMulti
La validation des exports est gérée de manière atomique ; si l’une des mises à jour échoue, l’ensemble de la transaction est annulé.
Méthode : POST
Document à envoyer :
{
"companyCode": "RHM5",
"entities": [
{
"entityName": "orderheader",
"srvExport": 0,
"rows": [
{
"rowCode": "CMD0045",
"srvDateUTC": "2020-04-07T08:51:39"
}
]
},
{
"entityName": "orderdetail",
"srvExport": 0,
"rows": [
{
"rowCode": "CMD0045-L0001",
"srvDateUTC": "2020-04-07T08:51:40"
},
{
"rowCode": "CMD0045-L0002",
"srvDateUTC": "2020-04-07T08:51:40"
},
{
"rowCode": "CMD0045-L0003",
"srvDateUTC": "2020-04-07T08:51:40"
}
]
}
]
}
Paramétrage du corps de la requête (format JSON) :
companyCode (optionnel) : code de la société pour le filtrage des données. Par défaut, le code société associé à l'utilisateur connecté est utilisé.
entityName (obligatoire) : nom de la table (sans « sw_data_ »).
srvExport (obligatoire) : permet de spécifier la valeur à mettre à jour pour le statut "export" (champ "srvExport").
rows (obligatoire) : liste des enregistrements à mettre à jour avec la valeur du champ "srvExport".
rowCode : code unique de l'enregistrement pour une société (dans le cas d'un projet "multi-société" il faut renseigner la propriété "companyCode" ci-dessus).
srvDateUTC : date de dernière modification de l'enregistrement sur le serveur à retourner à partir des données lues en amont.
Import de données en masse
Cette opération permet d’importer un lot de données de manière atomique.
URL : {{apiBaseUrl}}/v1/Data/[codeProjet]/ImportDataSet
Dans le cadre de l’ajout/mise à jour, l’existence du code de l’enregistrement détermine s’il faut créer un enregistrement ou modifier l’enregistrement existant.
Chaque enregistrement doit contenir les mêmes champs.
Méthode : POST
Document à envoyer :
{
"data": {
"customer": [
{
"customer_ID": "MF01",
"name": "MF-01"
},
{
"customer_ID": "MF02",
"name": "MF-02"
},
{
"customer_ID": "MF03",
"name": "MF-03"
}
]
}
}
Réponse :
{
"addedRow": 0,
"updatedRow": 10000,
"statistics": {
"queryCount": 10010,
"queryDurationTotal": "00:00:16.2361677",
"executionDuration": "00:00:32.5875658"
}
}
Import d’un data set relationnel
Cette opération permet de créer, mettre à jour ou supprimer un ensemble d’enregistrements de manière atomique.
URL : {{apiBaseUrl}}/v1/Data/[codeProjet]/RelationalDataSet?noServerExportUpdate=true|false
Dans le cadre de l’ajout/mise à jour, l’existence du code de l’enregistrement détermine s’il faut créer un enregistrement ou modifier l’enregistrement existant.
Les suppressions sont traitées en premier, puis les ajout/mise à jour et enfin les relations entre les entités.
La gestion des relations permets de mettre à jour la clé étrangère d’une entité (target) pour la faire pointer vers une autre entité (target).
Dans le cadre de la suppression, l’absence d’un enregistrement est toléré et ne lèvera pas d’exception.
Les modifications sont gérées de manière atomique ; si l’une des mises à jour échoue, l’ensemble de la transaction est annulé.
Le paramètre ‘noServerExportUpdate' permet de désactiver la mise à jour automatique du champ ‘srvExport’ lors de la modification d’un enregistrement existant.
Méthode : POST
Document à envoyer :
{
"data": {
"noResultData": false,
"customer": [
{
"customer_ID": "MF01",
"name": "MF-01"
},
{
"customer_ID": "MF02",
"name": "MF-02"
},
{
"customer_ID": "MF03",
"name": "MF-03"
}
]
},
"deletes": {
"customer": [
"MF02",
"MF03"
],
"customercontact": [
"CONTACT01",
"CONTACT02",
]
},
"Relations": [
{
"SourceEntityName": "customer",
"SourceRowCode": "MF01",
"TargetEntityName": "customerContact",
"TargetFieldName": "customer_ID",
"TargetRowCode": "CONTACT01"
},
{
"SourceEntityName": "customer",
"SourceRowCode": "MF01",
"TargetEntityName": "customerContact",
"TargetFieldName": "customer_ID",
"TargetRowCode": "CONTACT02"
}
]
}
Paramétrage du corps de la requête (format JSON) :
noResultData : la valeur ‘true’ permet de ne pas recevoir de données en retour.
data : tableau des données par entités. Il est obligatoire de fournir le code de l’enregistrement.
deletes : tableau des codes à supprimer par entités.
relations : tableau des informations concernant l’enregistrement source et l’enregistrement cible.
SourceEntityName : nom de l’entité source
SourceRowCode : code de l’entité source
TargetEntityName : nom de l’entité cible
TargetRowCode : code l’entité cible.
TargetFieldName : nom de la colonne de l’entité cible. Cette colonne recevra le code de l’enregistrement source.
Suppression d’un dataset
Cette opération permet de supprimer un ensemble d’enregistrements de manière atomique.
URL : {{apiBaseUrl}}/v1/Data/[codeProjet]/DeleteDataSet?[deleteMode]&[companyCode]
Méthode : DELETE
DeleteMode : le mode de suppression est obligatoire et permet de déterminer le comportement de l’API concernant les suppressions :
deleteMode=1 : les enregistrements sont supprimés de manière logique.
deleteMode=2 : les enregistrements absent sont supprimés de manière physique.
companyCode (optionnel) : code de la société pour le filtrage des données. Par défaut, le code société associé à l'utilisateur connecté est utilisé.
L’absence d’un enregistrement est toléré et ne lèvera pas d’exception.
Les suppressions sont gérées de manière atomique ; si l’une des suppression échoue, l’ensemble de la transaction est annulé.
Document à envoyer :
{
"customer": [
"MF02",
"MF03"
],
"customercontact": [
"CONTACT01",
"CONTACT02",
]
}
Paramétrage du corps de la requête (format JSON) :
Dictionnaires, dont la clé est l’entité, et les valeurs sont les codes à supprimer.
Réponse :
{
"deletedRow": 10000,
"statistics": {
"queryCount": 10010,
"queryDurationTotal": "00:00:16.2361677",
"executionDuration": "00:00:32.5875658"
}
}
Création des comptes utilisateurs
Il est possible de créer un ensemble de comptes via une API dédiée.
Les comptes inexistants seront créés. Si un compte existe déjà, il sera possible de mettre à jour uniquement son statut.
L'affectation du statut d'un compte est dépendante du nombre de licences restantes pour le projet.
Ainsi, s'il ne reste aucune licence, les comptes dont le statut demandé est "actif" seront automatiquement passés en statut "désactivé".
Il est possible de libérer des licences en passant le statut de certains comptes du statut "actif" en un autre statut possible.
URL : {{apiBaseUrl}}/v1/Devices/[codeProjet]/CreateDevicesWithList
La création des comptes est gérée de manière atomique ; si l’une des actions échoue, l’ensemble de la transaction est annulé.
Méthode : POST
Document à envoyer :
[
{
"deviceName": "tgreiner@divalto.com",
"baseUserCode": "TG",
"languageCode": "EN",
"password": "Dh4tSDGx",
"accountStatus": "Disabled",
"accessType": "MultiDevice"
},
{
"deviceName": "fbertrand@divalto.com",
"baseUserCode": "FB",
"languageCode": "FR",
"password": "hJd57gZ3",
"accountStatus": "Active",
"accessType": "MobileOnly"
},...
]
Paramétrage du corps de la requête (format JSON) :
deviceName (obligatoire) : nom du compte. Il s'agit de l'identifiant unique dans le projet.
baseUserCode (obligatoire) : code du représentant possédant les données de l'utilisateur. Ce code doit exister dans l'entité "baseuser".
languageCode (obligatoire) : code de la langue à utiliser pour le compte. Ce code doit exister dans l'entité "language".
password (obligatoire) : mot de passe à attribuer au compte. Ce mot de passe devra être modifié à la première connexion.
accountStatus (obligatoire) : statut du compte (voir la liste ci-dessous).
accessType (obligatoire) : type d'accès pour le compte (voir la liste ci-dessous).
Liste des status disponibles :
Active : le compte est actif et consomme une licence.
Disabled : le compte est désactivé et l'utilisateur ne peut plus se connecter.
Maintenance : le compte est en maintenance et l'utilisateur ne peut plus se connecter.
Readonly : le compte est en lecture et les données remontées du mobile ne seront pas enregistrées sur le serveur de base de données.
Destroy : la base de données du mobile sera détruite à la prochaine synchronisation des données.
Destroyed : la base de données du mobile a été détruite.
Liste des types d'accès disponibles :
BackOfficeOnly : le compte ne peut se connecter qu'à l'interface de gestion Web.
MobileOnly : le compte ne peut se connecter que sur un mobile.
MultiDevice : le compte peut se connecter à l'interface de gestion Web, ainsi qu'à deux mobiles au maximum.
NB : Lors d'une mise à jour, seul le statut du compte peut être modifié. Les valeurs des autres propriétés ne sont pas prises en compte.
Création de tâches pour l'exécution de traitements
Via l'API il est possible de demander au serveur l'exécution d'une ou plusieurs tâches de traitement "Event".
Si une tâche est déjà en attente pour un traitement, une nouvelle tâche ne sera pas créée.
Si le code de la tâche est spécifié plusieurs fois lors de l'appel, une seule tâche pour ce code sera ajoutée.
URL : {{apiBaseUrl}}/v1/SysEvents/[codeProjet]/Create
La création des tâches est gérée de manière atomique ; si l’un des ajouts échoue, l’ensemble de la transaction est annulé.
Méthode : POST
Document à envoyer :
{
"actionCodes": [
"INFINITY_EXPORT_CONTRACT",
"INFINITY_EXPORT_DEAL_TIME",
"INFINITY_EXPORT_WORKORDER"
]
}
Paramétrage du corps de la requête (format JSON) :
actionCodes (obligatoire) : liste des codes actions à utiliser pour générer les tâches.
L'API retourne la liste des tâches qui auront été effectivement créées.
Création d'une boite d'envoi de génération d'un report
URL : {{apiBaseUrl}}/v1/data/[codeProjet]/outbox/report/?eventActionCode=
Méthode : POST
En-têtes : Content-Type=application/json
eventActionCode (optionnel) : code d'une action d'événement (eventAction). Si ce paramètre est fourni à l'API, un événement correspondant à ce type sera automatiquement crée pour déclencher le traitement de la nouvelle boite d'envoi par le service Alert.
Document à envoyer :
{
"baseOutbox_ID": "Report001",
"confreport_ID": "ORDER",
"rowID": "ORDER_0001",
"sourceEntity": "orderheader",
"baseuser_ID": "TECH3",
"print": 0,
"isBodyHtml": 0,
"replyto": [
"email1@divalto.com",
"email2@divalto.com"
],
"emailto": [
"email1@client.com",
"email2@client.com"
],
"attachments": [
{
"entity": "productpicture",
"dataColumn": "binaryData",
"rowID": "Product1",
"name": "article1",
"mimeType": "image/jpeg"
},
{
"entity": "productpicture",
"dataColumn": "binaryData",
"rowID": "Product2",
"name": "article2",
"mimeType": "image/jpeg"
}
]
}
Paramétrage du corps de la requête (format JSON) :
baseOutbox_ID (obligatoire) : code de la boite d'envoi. Par défaut, le code société associé à l'utilisateur connecté est utilisé.
confreport_ID (obligatoire) : code du report tel que défini dans l'entité 'confreport'.
rowID (obligatoire) : code de l'enregistrement utilisé pour la génération du report.
sourceEntity (obligatoire) : nom de l'entité utilisée pour la génération du report.
baseUser_ID (obligatoire) : code de l'utilisateur associé à la boite d'envoi, tel que défini dans l'entité 'baseuser'.
fromArchive (optionnel) : '2' = le document provient toujours de l'archive, 1 = le document provient de l'archive si disponible, 2 = le document est toujours recrée.
print (optionnel) : nombre d'exemplaire à imprimer (0 pour ne pas demander de demande d'impression).
messageSubject (optionnel) : sujet du mail.
messageBody (optionnel) : corps du mail.
filename (optionnel) : nom du fichier a générer.
pathExport(optionnel) : chemin relatif où générer le fichier.
isBodyHtml (optionnel) : '1' dans le cas d'un envoi par mail, pour définir un corps de message HTML.
replyto (optionnel) : liste des adresses emails utilisés pour le "répondre à".
emailto (optionnel) : liste des adresses emails destinataires.
attachments (optionnel) : liste des documents à joindre à l'email :
entity (obligatoire) : nom de l'entité où est stocké le document.
dataColumn (obligatoire) : nom du champ contenant la donnée binaire (BLOB).
rowID (obligatoire) : code de l'enregistrement correspondant au document.
name (obligatoire) : nom de la pièce jointe.
mimeType (obligatoire) : type de pièce jointe (ex image/jpeg, image/png)
Fusionner deux enregistrements
URL : {{apiBaseUrl}}/v1/data/[codeProjet]/[entité]/mergeData
Cette API permet de copier les données d'un enregistrement source vers un enregistrement cible.
Les enregistrements liés à la source seront déplacés vers l'enregistrement cible.
L'enregistrement source sera supprimé.
Concernant la copie des données de source vers cible : les champs non NULL seront recopiés si le champ est NULL dans la cible.
L'enregistrement cible doit exister.
Méthode : POST
Document à envoyer :
{
"sourceCode": "Customer1",
"sourceCompanyCode": "SOC1",
"targetCode": "Customer2",
"targetCompanyCode": "SOC1",
}
Paramétrage du corps de la requête (format JSON) :
sourceCode (obligatoire) : code de l'enregistrement source.
sourceCompanyCode (obligatoire) : code société de l'enregistrement source.
targetCode (obligatoire) : code de l'enregistrement cible.
targetCompanyCode (obligatoire) : code société de l'enregistrement cible.
L'API retourne un code HTTP 200 si aucune erreur ne se produit.
Quota
Une limitation d'usage est active sur les appels API à partir d'une même IP :
10 appels max / seconde
tolérance à 20 appels / seconde, mais dans ce cas il faudra attendre 1 seconde avant de refaire de nouveaux appels