Spécifications
SAINet fournit une API d’accès qui se base sur les standards du marché (REST-JSON). Cette interface permet à un logiciel externe de s’interfacer avec SAINet afin de récupérer différentes données selon ses besoins.
La communication set fait exclusivement à travers le protocole HTTPS et tous les échanges sont donc chiffrés.
Le point d’accès (endpoint) est https://<host>/SNV4SRV-ws-war/api/v1
.
Afin de pouvoir utiliser l’API, il est nécessaire de disposer d’un compte utilisateur actif dans SAINet avec les accès nécessaire aux différentes tâches permettant d’accéder aux données souhaitées.
Il est recommandé que les comptes utilisés pour utiliser l’API soient de type “système” en SYS02.
Les différents exemples sont de requêtes sont fait au moyen de la commande cURL.
Les termes ci-dessous font références à certains concepts de SAINet qui sont utilisés dans l’API.
Nom | Description |
---|---|
Tâche | Une tâche correspond à un écran. Un code de tâche est composé de 5 caractères (uniquement majuscules et chiffres, par exemple: ADR02 ou SYSUS ). Chaque tâche a un type qui lui est associé (voir ci-dessous). |
Saisie simple | C’est une tâche permettant la gestion (création,modification,suppression) d’un enregistrement quelconque (généralement 1 table en base de données). |
Saisie double | C’est une tâche permettant la gestion d’un enregistrement complexe (2 ou plusieurs tables en base de données). |
Saisie dossier | C’est une tâche permettant la gestion d’un dossier. Un dossier se compose de plusieurs champs dynamiques, regroupés dans des pages. |
Vue | Affichage d’une liste d’enregistrements. |
Liste | Impression d’une liste d’enregistements. Ce type de tâche renvoie un zip qui peut contenir plusieurs fichiers (html) et autres resources (images). |
Traitement | Effectue un traitement ne nécessitant pas de retour particulier (si ce n’est un message d’information). |
Les tâches de vue, liste et traitement peuvent être simples ou longues. Les tâches simples n’ont généralement pas de traitement particulier et un temps de réponse faible.
Les tâches longues comprennent souvent des traitements complexes et peuvent facilement durer plusieurs minutes, ce qui peut poser des problèmes de connexion. Pour ces cas-là, l’API permet de lancer le processus, d’en vérifier la progression puis de récupérer le résultat une fois terminé (polling).
Type de tâche | Code | Exemples | Support |
---|---|---|---|
Saisie simple | B |
SYS02 , CGE02 , SAL03 |
Accès en lecture (clés multiples non supportées) |
Saisie dossier | R |
ADR02 , SAL04 , CRM06 |
Accès en lecture |
Saisie double | F |
SYS01 , SAL21 , STO30 |
Non supporté |
Vue simple | V |
SYSUS , SALPA , CRMEV |
Accès en lecture |
Vue longue | W |
GTPLC , GTPEV |
Accès en lecture |
Traitement simple | T |
SYS87 , SYS46 |
Non supporté |
Traitement long | U |
SYS88 , SAL24 |
Non supporté |
Liste simple | L |
SYS12 |
Non supporté |
Liste longue | M |
SYS34 , SAL25 |
Non supporté |
Par défaut, l’accès à l’API est désactivé. Un administrateur SAINet doit l’activer en SYS22 (variable system.api_enabled
).
Lorsque l’API n’est pas active, SAINet renverra systématiquement une erreur HTTP 403.
Les échanges de données se font au format JSON. Les réponses JSON sont compressées. Il est possible d’utiliser un JSON Beautifier afin d’avoir une visualisation de la hiérarchie des objets.
Les réponses sont encodées en UTF-8
.
Les formats ci-dessous sont utilisés dans les échanges JSON:
Type | Format | Exemple |
---|---|---|
String | "Ceci est une chaîne de caractère" |
|
Date | yyyy-MM-dd'T'HH:mm:ssZ |
"2018-05-03T09:00:00-0100" |
Boolean | true ou false |
|
Liste | Array | [ "value1", "value2" ] |
Combo | Objet | { "key":"3", "value":"Libellé" } |
Integer | 42 |
|
Double | 1337.8523 |
Les valeurs null
ne sont pas sérialisées et donc absentes des objets dans les réponses retournées.
Les dates ont toujours le format complet (avec les heures et le TimeZone), même pour les champs pour lesquels ces données ne sont pas utilisées.
Les objets retournés contiennent les informations présentes dans l’écran de la tâche.
La clé spéciale $recordId
représente l’identifiant unique permettant d’accéder directement à l’enregistrement.
Cette clé n’est retournée que dans le cadre des requêtes permettant d’accéder aux enregistrements.
Les codes HTTP suivants peuvent être retournés:
Code | Description | Réponse |
---|---|---|
200 | La requête a été traitée. | Objet JSON |
400 | La requête n’a pas été traitée car elle est invalide. | - |
401 | Accès non autorisé. Soit les données d’authentification sont incorrectes, soit le token a été invalidé. | - |
403 | L’accès à l’API n’a pas été autorisé en SYS22. | - |
405 | Méthode invalide. | - |
406 | Erreur métier (voir ci-dessous). | Objet JSON |
500 | Erreur interne. | - |
En cas d’erreur métier (code HTTP 406), la réponse contient un objet JSON avec le détail de l’erreur.
{
"status":"FAILURE",
"type":"BUSINESS_FAILURE",
"code":"SYSTEM_SECURITY_ACCESS_DENIED",
"message":"Vous n\u0027avez pas les droits suffisants pour effectuer l\u0027action demandée.\nUtilisateur: <login>.\nTâche: SYS00.\nPage: -.\nDomaine: <domain>.\nAction: R."
}
La langue du message d’erreur correspond à la langue de l’utilisateur en SYS02.
Voici les différentes valeurs possibles:
Clé | Valeur | Description |
---|---|---|
status |
FAILURE |
Une erreur métier est survenue et le traitement a été interrompu. |
SUCCESS |
Le traitement a été effectué sans erreur, mais un message est affiché. Ce type de message n’est pas renvoyé dans le cadre de l’API. | |
ONGOING |
Le traitement a besoin d’une confirmation/réponse de la part de l’utilisateur. Ce type de message n’est pas renvoyé dans le cadre de l’API. | |
type |
COMMENT |
Simple remarque. N’apparaît que pour les message avec le status SUCCESS ou ONGOING . |
INVALID_INPUT |
Les données saisies sont invalides. Généralement ce type d’erreur est renvoyé lors d’une saisie. | |
BUSINESS_FAILURE |
Erreur métier. | |
SYSTEM_FAILURE |
Erreur système. | |
PASSWORD_EXPIRED |
Mot de passe expiré (uniquement lors du login, ne devrait jamais apparaître avec l’utilisation d’un compte système). | |
CORRUPTED_DATA |
Des données sont corrompues (typiquement suite à un import de données). | |
code |
Cette valeur est unique pour chaque type de message renvoyé. | |
message |
Message correspondant au code . |