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.

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 et suppression (clés multiples non supportées)
Saisie dossier	R	ADR02, SAL04, CRM06	Accès en lecture et suppression
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.

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.
invalidFields		Liste des champs invalides correspondants au message. Cette valeur n’est pas spécifiée lorsque l’erreur n’est pas liée à un champ.