L'architecture REST est un service qui vous permet d'effectuer différentes opérations d'échange d'information.
Appeler un WebService DIVA
Exploiter l'API REST RecordSQL
Exploiter des Webhook
Authentification
Quel que soit le type d'opération que vous souhaitez effectuer (en dehors de l'accès à un webhook), l'authentification est une étape préalable avant tout dialogue avec le service.
L'adresse suivante doit être utilisée pour fournir les paramètres d'identification qui vous permettront d'obtenir un token en retour. Ce token dispose d'une durée de validité de 45 minutes
https://api.divaltocloud.com/[NUMEROSITE]/[ENVIRONNEMENT]/api/v1/Authent/Auth
Les paramètres d'identification doivent être transmis au format de données JSON au travers d'une méthode HTTP "POST" :
"user" * : Correspond à un compte (de préférence dédié) créé via l'outil DLMT.
"password" * : Mot de passe associé au compte indiqué
* : Champs obligatoires
Le résultat se présentera également au format de données JSON.
"error" : Contient le code d'erreur. La valeur « 0 » indique le succès de l'opération
"txterror" : Texte de l'erreur, si applicable
"access_token" : Contient la valeur du token obtenu
"infos" : Réservé pour un usage ultérieur
Exemple : Obtention d'un token
{
"user": "userapi@divalto.com",
"password": "xxxxxxxxxxxxxxx",
"infos": ""
}
Résultat :
{
"error": 0,
"access_token": "eyJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGRzaWctbW9yZSNobWFjLXNoYTI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudCI6IkRpdmFsdG9BcGlSZXN0IiwidXNlciI6IkFkbWluQEM2OTkwNTUuZGl2YWx0by5jb20iLCJwYXNzd29yZCI6Im5xNGpYZ2M0IiwiZW52IjoiVEVTVElORyIsImRvbWFpbiI6ImRpdmFsdG9jbG91ZCIsImV4cCI6IjQ0NDEzLjUyOTY5MzM2ODEifQ.7c5XsztQ_9y92uccgWZqKw4-oe55SlB8UZzAI6-AJmE",
"txterr": "",
"infos": ""
}
WebService DIVA
L'appel d'un WebService DIVA au travers du service REST API repose sur l'utilisation d'un code action qui lui-même fait référence à un programme (DHOP). Ce programme sera ensuite en mesure d'effectuer des opérations de type 'métier' selon les paramètres qui lui seront envoyés.
Les codes des actions sont définis par environnement en utilisant le programme d'Administration Cloud (Onglet 'Services Web) (cf. chapitre 'Administration'). Vous pouvez exploiter des codes actions prédéfinis ou effectuer une nouvelle déclaration en enchainant sur un programme spécifique.
Les paramètres doivent être envoyés au format de données JSON au travers d'une méthode HTTP "POST" sur le lien suivant : https://api.divaltocloud.com/[NUMEROSITE]/[ENVIRONNEMENT]/api/v1/WebService/Execute
"action" * : Nom de l'action
"param" : Liste des paramètres
"access_token" * : Token en cours de validité pour l'accès au service (Obligatoire si non déclaré en entête (Bearer Token))
* : Champs obligatoires
Le résultat se présentera dans une enveloppe au format de données JSON mais les données seront structurées au format XML ou JSON selon le programme Diva en charge du traitement :
"error" : Retourne le numéro d'erreur, la valeur '0' indique qu'il n'y a pas d'erreur
"result":: Réponse du service web au format XML
"txterr":: Précise le texte de l'erreur (si applicable)
"infos": : Réservé pour un usage ultérieur
Exemple : Utilisation du code action 'PING'
{
"action": "PING",
"param": ""
}
Résultat :
{
"error": 0,
"result": "Pong Version 2021 sur dclparwsc821 Action PING Xlogf= //DhsXlanServer/testing/config/global/xlog.dhfi Env=TESTING Tâche=355",
"txterr": "",
"infos": ""
}
RecordSQL DIVA
Cette API offre la possibilité d'interroger directement des informations situées dans la base de données SQL d'un environnement ERP. Ainsi, pour lire des données, vous n'avez plus besoin d'invoquer un programme Diva étant donné que l'API peut s'en charger directement.
Par défaut, le service API REST RecordSQL n'expose aucune donnée. La première opération à effectuer consiste à déclarer les fichiers Record SQL (Format DHOQ) dont vous souhaitez autoriser l'accès au travers de cette API. Ces paramètres sont définis par environnement en utilisant le programme d'Administration Cloud (Onglet 'REST') (cf. chapitre 'Administration').
Vous devez par ailleurs vous assurer que l'identifiant utilisé lors de l'obtention du token est bien associé à l'environnement sur lequel vous souhaitez réaliser le traitement (l'affectation à un modèle d'utilisateur ou un profil de licence n'est cependant pas nécessaire).
Vous pouvez récupérer jusqu'à 1000 enregistrements avec une seule requête. Il est possible de paginer les résultats en utilisant les paramètres « offset » et « count ». Par exemple si vous souhaitez récupérer les informations par lot de 100, la première requête doit contenir un offset à 0 et un count à 100, la seconde requête doit contenir un offset à 100 et un count à 100, etc...
Le nombre de résultat réellement retourné est contenu dans un paramètre de retour (Nbrecord) que vous pouvez exploiter pour déterminer la fin des enregistrements.
Les paramètres doivent être envoyés au format de données JSON sans oublier d'y intégrer la valeur du token d'authentification au travers d'une méthode HTTP "POST" sur le lien suivant :
https://api.divaltocloud.com/[NUMEROSITE]/[ENVIRONNEMENT]/api/v1/RecordSql/Execute
"dhoq" * : Indique le nom du fichier Record SQL (Fichier DHOQ)
"recordsql" * : Indique le nom du Record SQL du fichier DHOQ
"access_token" * : Token en cours de validité pour l'accès au service (Obligatoire si non déclaré en entête (Bearer Token))
"parameters" : Liste des champs et leurs valeurs (en majuscules et en précisant la table) séparés par un point-virgule pour servir de référence en tant que clé lors de l'exécution de la requête. Par défaut, ce champ est renseigné automatiquement avec les paramètres variables pour traiter la requête. (Exemple pour la notion de contexte (paramètres utilisateurs) : MZ.DOS=998)
"fields" : Liste des champs en retour (en majuscules sans préciser la table) séparés par un point-virgule. Par défaut le retour contient l'intégralité des champs de la table
"where" : Nom de la condition 'WHERE'
"where_parameters" : Liste des paramètres de la condition 'where' selon fichier Record SQL
"offset" : Décalage à appliquer pour la lecture (pagination)
"count" : Nombre d'enregistrements à récupérer (défaut : 1)
"orderby" : Nom du tri tel qu'il figure dans le fichier Record SQL.
"having" : Nom de la condition 'HAVING'
"having_parameters" : Liste des paramètres de la condition 'having'
"infos" : Obtenir des statistiques ou générer des traces à la suite de l'exécution de la requête (<perf>1)
"filter" : Filtres avancés
"operator_where" : La valeur 'OR' permet d'appliquer un OU logique (Défaut : ET)
"where" : Définition des clauses WHERE
"whereaddcondition": Définition des conditions entre les clauses WHERE
"createwhere" : Création de nouvelles conditions WHERE
"whereremovecondition" : Suppression de conditions WHERE spécifiques
"joindeactivate": Désactivation des jointures vers les tables en dépendance
* : Champs obligatoires
Le résultat se présentera également au format de données JSON.
"Error" : Retourne le numéro d'erreur, la valeur '0' indique qu'il n'y a pas d'erreur
"Txterr" : Précise le texte de l'erreur (si applicable)
"Tablename" : Indique le nom de la table SQL
"Nbrecord" : Indique le nombre d'enregistrement retourné
"Records" : Contient un tableau des enregistrements avec la liste des champs et de leurs valeurs
"infos" : Retourne les informations complémentaires (statistiques, ...)
Les valeurs retournées ne sont pas traduites, les montants sont toujours avec un point comme séparateur décimal et les dates sont au format 'AAAAMMJJ'.
Exemple : Récupération des 5 premiers résultats des champs 'CPOSTAL' et 'VIL' sur condition que le code postal débute par '6796' ou que le nom de la ville contienne le mot « PARIS » et suivant un tri par code postal.
Les statistiques sont activées afin d'obtenir les temps associés à l'exécution de la requête.
{
"dhoq": "gtrstab.dhoq", // Nom du fichier DHOQ
"recordsql": "CODEPOSTAL", // Nom du RecordSQL
"parameters": "",
"fields": "CPOSTAL;VIL", // Récupération des champs CPOSTAL et VIL
"where": "",
"where_parameters": "",
"offset": "0", // Décalage de 0 résultat
"count": "5", // Récupération de 5 résultats maximum
"orderby": "Par_Code", // Tri par Code Postal
"having": "",
"having_parameters": "",
"infos": "<perf>1", // Activation des statistiques
"filter": {
"operator_where":"OR", // Deux clauses WHERE avec un OU logique
"where": [ // Par défaut, un ET logique est appliqué
{
"name": "Like_Cpostal", // Première clause WHERE
"parameters": "6796%" // Code Postal contient la valeur "6796"
},
{
"name": "Like_Vil", // Seconde clause WHERE
"parameters": "%PARIS%" // Ville contient la valeur "PARIS"
}
]
}
}
Résultat :
{
"error": 0,
"txterr": "",
"tablename": "T057",
"nbrecord": 5,
"records": [
{
"record": "@{CPOSTAL=38170; VIL=SEYSSINET PARISET}"
},
{
"record": "@{CPOSTAL=39500; VIL=DAMPARIS}"
},
{
"record": "@{CPOSTAL=62520; VIL=LE TOUQUET PARIS PLAGE}"
},
{
"record": "@{CPOSTAL=67960; VIL=ENTZHEIM}"
},
{
"record": "@{CPOSTAL=71150; VIL=PARIS L HOPITAL}"
}
],
"infos":
{
"xperf":
{
"ExecuteRequestSQL": "297", // Temps total (ms)
"LoadDHXISAM": "47",
"LoadRecordForSQL": "1",
"LoadDataForSQL": "1",
"ImpersonationSQL": "1",
"ExecuteSQL": "16", // Temps d'exécution SQL (ms)
"ResultSQL": "19"
}
}
}
Autre exemple avec l'instruction 'whereaddcondition' qui permet de spécifier l'opérateur entre chaque clause WHERE au niveau du paramètre 'filter' :
(Les codes postaux qui commencent par 67 ET le nom de la ville correspond à 'ENTZHEIM') OU le nom de la ville contient le mot 'OBERN'
{
"dhoq":"gtrstab.dhoq", // Nom du fichier DHOQ
"recordsql":"CODEPOSTAL", // Nom du RecordSQL
"parameters":"",
"fields":"CPOSTAL;VIL", // Récupération des champs CPOSTAL et VIL
"where":"",
"where_parameters":"",
"offset":"0", // Décalage de 0 résultat
"count":"50", // Récupération de 50 résultats maximum
"orderby":"Par_Code", // Tri par Code Postal
"having":"",
"having_parameters":"",
"filter": {
"where": [
{
"name":"Like_Cpostal", // Première clause WHERE
"parameters":"67%" // Codes postaux qui commencent par '67'
},
{
"name":"Equal_Vil", // Seconde clause WHERE
"parameters":"ENTZHEIM" // Ville qui corresponde à 'ENTZHEIM'
},
{
"name":"Like_Vil", // Troisième clause WHERE
"parameters":"%OBERN%" // Ville dont le nom contient 'OBERN'
}
],
"whereaddcondition": // Définition des conditions
{
"name":"cond1","condition":"(Like_Cpostal and Equal_Vil) or Like_Vil"
}
}
}
Résultat :
{
"error": 0,
"txterr": "",
"tablename": "T057",
"nbrecord": 2,
"records": [
{
"record": "@{CPOSTAL=67210; VIL=OBERNAI}"
},
{
"record": "@{CPOSTAL=67960; VIL=ENTZHEIM}"
}
],
"infos": ""
}