Principes généraux

Glossaire :

Dans la documentation permettant d'exploiter les API REST Silae Paie, un certain nombre de termes spécifiques sont employés régulièrement. Pour faciliter la compréhension et éviter les confusions, chaque terme et sa signification sont décrits dans le glossaire.

Principes de connexion :

Pour pouvoir utiliser les API REST Silae Paie, il est nécessaire d'avoir :

• Un compte API
• Un accès API aux dossiers Silae sur lesquels on veut travailler (ou Configuration d'accès API)

Le compte API servira à s'authentifier auprès du service d'authentification Silae afin de pouvoir utiliser les APIs REST.

L'accès API à un dossier permettra de valider les autorisations d'accéder aux données du dossier.

URL utiles à noter :

• URL d'authentification : https://payroll-api-auth.silae.fr/oauth2/v2.0/token
• URL cible pour les appels API : https://payroll-api.silae.fr/payroll (Cette url sera la cible de tous les appels aux endpoints API REST)
• URL de connexion au portail API : https://api-portal.silae.fr

Dates et périodes :

Les dates sont toutes au format AAAA-MM-JJT00:00:00.00Z avec :
- AAAA = Année
- MM = Mois
- JJ = Jour
Les périodes, comme les périodes de paie par exemple, sont toutes au format AAAA-MM-01T00:00:00.00Z (le jour est toujours le premier jour du mois) avec :
- AAAA = Année
- MM = Mois

Caractères autorisés :

Les valeurs doivent contenir des caractères qui respectent le jeu de caractères ANSI (Windows1252)

Mise à jour conditionnelle :

Dans de nombreuses fonctions, les champs sont "doublés" d'un booléen permettant d'indiquer si la valeur du champ correspondant doit être prise en compte (true) ou non (false). Ces booléens ont le même nom que le champ auquel ils font référence, précédé d'un 'b'. Par exemple : "bPrenom" fait référence au champ "Prenom".

Fonctionnement des emplois et utilisation des identifiants

Dans Silae, chaque modification de la fiche salarié qui a un impact sur la paie génère un nouvel "emploi" (ou "emploi actif" ou "emploi en cours") avec un nouvel "identifiant emploi". L'emploi précédent devient alors un "emploi archivé".
Ces différents emplois au sens Silae ne reflètent pas forcément de vrais changements d'emplois.
Par exemple, un changement de salaire va générer dans Silae un nouvel emploi alors qu'il n'y a pas eu de changement de contrat pour le salarié.
Pour qu'au niveau des API il soit possible de faire la différence entre les changements d'emplois au sens Silae et les vrais changements d'emploi (type sortie/entrée du salarié), il existe la notion d'identifiant emploi externe. Dans l'utilisation des APIs c'est toujours cet "identifiant emploi externe" qui est présent.
Ainsi, pour un salarié qui garde le même emploi avec divers changements (comme des augmentations par exemple), l'identifiant emploi externe sera toujours le même, alors même qu'il y aura eu plusieurs emplois archivés dans Silae.

Les fonctions API en mode asynchrone

Le principe du mode asynchrone consiste à enregistrer la demande émise par la fonction API sans attendre immédiatement le résultat.
Ce mode de fonctionnement est très approprié lorsque la requête doit traiter un volume de données assez conséquent. Il permet ainsi d'éviter un échec lié à l'expiration de la requête réseau entre le client et le serveur.

Cette méthode asynchrone garantit donc la bonne exécution et réception du résultat.

Parmi toutes les fonctions API, certaines d’entre elles ont été sélectionnées pour être également proposées en mode asynchrone. Quelques exemples :

Chaque fonction API en mode asynchrone est accompagnée d’une seconde requête qui permet de vérifier le statut de la demande à intervalle régulier. L'état peut indiquer que le traitement est toujours en cours ou alors contenir tout simplement le résultat attendu (mode pull).

En résumé, il est indispensable d'exploiter le couple de fonctions API pour obtenir une réponse. Elles doivent être exécutées dans un ordre précis :

1. Lancer la fonction Asynchrone pour déclencher la demande et obtenir l'identifiant de la tâche (ex: SalariesBulletinsAsynchrone),

2. Exécuter la fonction de Statut correspondante avec en paramètre ce même identifiant de tâche pour obtenir le résultat (StatutSalariesBulletinsAsynchrone).