| Sommaire |
|---|
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.
...
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 :
...
| Bloc de code | ||
|---|---|---|
| ||
{
"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).
...
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).
...
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.
...
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 :
...
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 :
...
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 :
...
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.
...
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.
...
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.
...
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é.
...
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.
...
| Bloc de code |
|---|
{
"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.
...
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.
...
| Bloc de code |
|---|
{
"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.
...
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.
...
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=
...
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
...
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 :
...