USAGE

Introduction

Présentation

Nous allons décrire dans ce document le fonctionnement de l'API Nicoka. Ce fonctionnement est commun à l’ensemble de nos modules.

Il s’agit d’une API RestFull respectant les normes suivantes :

Méthode	Action
GET	Lecture
POST	Création / Modification d’un enregistrement
DELETE	Suppression d’un enregistrement

Chemin

Pour accéder à votre API depuis un compte en production vous devez utiliser le chemin suivant :

https://<account_subdomain>.nicoka.com/api/

Si vous souhaitez tester l’API depuis un compte d’essai vous devez utiliser le chemin suivant :

https://trial.nicoka.com/<account_subdomain>/api/

Note

<account_subdomain> désigne le nom de votre sous-domaine Nicoka

Connexion à l'API

Utilisateur API

Important

Il est fortement conseillé d’utiliser un utilisateur dédié pour se connecter à l’API.

Un utilisateur connecté sur l'application Nicoka en tant qu'administrateur doit créer un utilisateur API dédié.
Pour cela,il faut aller dans le menu « Paramétrage » /« Administration » puis « Utilisateurs » / « Utilisateur API » et créer votre utilisateur.
L’adresse email de cet utilisateur doit exister, car elle sera utilisée pour vous notifier en cas d’erreur.

Génération du token API

Il existe 3 solutions pour récupérer le token :

• Connecté en tant qu'administrateur autre que l'utilisateur API
• Connecté en tant qu'utilisateur API
• Depuis une requête directe (flux d'authentification OAuth)

Attention

Les jetons ont une durée de vie de 1 an, il faut donc les renouveler avant expiration!
Si vous n'avez pas accès à l'application Nicoka, vous devez utiliser un moyen de générer un nouveau jeton.
Voir le chapitre Depuis une requête directe (flux d'authentification OAuth)

Connecté en tant qu'administrateur autre que l'utilisateur API

Dans le menu « Paramétrage » /« Administration » puis « Utilisateurs » / « Utilisateur API », cliquez sur le nom de l'utilisateur pour lequel vous voulez générer un token. Puis cliquez sur "Générer un jeton d'accès"

Connecté en tant qu'utilisateur API

Lorsque vous êtes connecté à Nicoka en tant qu'utilisateur API, vous pouvez récupérer votre jeton d’accès actuel, en allant dans votre profil utilisateur dans « Mes informations » :

Puis allez dans le menu « Applications Externes », cliquez sur « Générer un jeton d'accès »

Depuis une requête directe (flux d'authentification OAuth)

Vous pouvez utiliser le flux d'authentification login-mot de passe pour générer le token uniquement si l'utilisateur a déjà été créé auparavant dans Nicoka.

Dans ce flux, les informations d'identification de l'utilisateur sont utilisées par l'application pour demander un jeton d'accès, comme indiqué dans les étapes suivantes.

Avertissement

Ce flux d'authentification OAuth transmet les informations d'identification de l'utilisateur.

Utilisez ce flux d'authentification uniquement lorsque nécessaire. Aucun jeton d'actualisation n'est émis.

1. Pour accéder à l’API vous avez besoin d’un jeton (« token »). Afin de générer votre jeton d’accès vous devez effectuer une première requête de type POST à l’adresse suivante :
   

   POST    https://<account_subdomain>.nicoka.com/api/login  
   

   Paramètres	Description
   login	Votre email de login Nicoka
   password	Votre mot de passe Nicoka

2. Nicoka vérifie les informations d'identification de l'utilisateur et, en cas de succès, envoie une réponse à l'application avec le jeton d'accès. Cette réponse contient la valeur suivante :

   Paramètres	Description
   token	Votre jeton d’accès

   Exemples de réponse :
   

   { 
   "token": "eyJ0eXAiOiJKV...bC5RsXdOfSuHd4Wbmhswb -V1nw" 
   }
   

3. L'application utilise le jeton d'accès fourni pour accéder aux données utilisateurs protégés. Gardez les considérations suivantes à l'esprit lorsque vous utilisez le flux OAuth de login/mot de passe.

Remarque

Comme l'utilisateur n'est jamais redirigé pour se connecter à Nicoka dans ce flux, l'utilisateur ne peut pas autoriser directement l'application, et donc il n’y a pas d'actualisation des jetons utilisés. Si votre application nécessite l'actualisation des jetons, vous devez envisager d'utiliser le flux OAuth du serveur Web ou de l'agent utilisateur.

Général

Liste d’objets

Maintenant que vous disposez d’un jeton d’accès nous allons voir comment récupérer une liste d’objet. Par exemple la liste des ressources humaines « employees ».

Requête

Le chemin d’accès à toujours la même forme :

https://<account_subdomain>.nicoka.com/api/<resource_name_in_plural>  

Paramètres d’entête	Description
Authorization	Bearer suivi de votre jeton d’accès

Exemple :

curl    -X GET https://<account_subdomain>.nicoka.com/api/employees/  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" 

Si vous testez l’API à partir d’un compte “Essai Gratuit” :
Exemple :

curl    -X GET https://trial.nicoka.com/api/<account_domain>/employees  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" 

Réponse

{ 
"queryUid ": "9edbf7bcddfbd0f0db649b6da8680d61",  
"offset": 0,  
"limit": 100 , 
"total": 25 0, 
"data": […] , 
"@odata.nextLink":  "https://trial.nicoka.com/api/<account_domain>/employees/?queryUi=9edbf7bcddfbd0f0db649b6da8680d61&queryPage=2 " 
}

Analyse de la réponse :

Paramètres	Type	Description
queryUid	string	Identifiant unique de la requête
offset	integer	Position de départ de la requête
limit	integer	Nombre d’enregistrements dans la requête (max. 200 par requête)
page	integer	Page actuelle
pages	integer	Nombre total de pages de résultat
total	integer	Nombre total d’enregistrements de la requête
@odata.nextLink	string	Lien vers la page suivante
data	JSON string	Liste des objets récupérés

Pagination

Lorsque que le résultat de la requête (total) est supérieur à la taille de votre buffer (limit), vous pouvez récupérer les pages suivantes en utilisant les paramètres suivants :

Paramètres	Description
queryUid	Identifiant unique de la requête que vous souhaitez traiter
queryPage	Page que vous souhaitez récupérer

Exemple de réponse :

{ 
 "queryUid": "9edbf7bcddfbd0f0db649b6da8680d61",  
 "offset": 10,  
 "limit": 10,  
 "page": 2,  
 "pages": 3,  
 "total": 25,  
 "data": […]  
}

Taille de buffer

Vous pouvez définir la taille du « buffer » en ajoutant le paramètre limit dans votre requête :

curl    -X GET https://trial.nicoka.com/api/<account_domain>/employees/?limit=100  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" 

Note

La taille maximum du buffer est de 200 enregistrements par requête pour des raisons de performance. Vous ne pouvez pas faire plus de 4 requêtes par seconde.

Trier les résultats

Vous pouvez trier les résultats de requête en ajoutant le paramètre suivant :

orderBy=<name_of_the_field>:<sort_direction>  

Name of the field

Il s’agit du nom d’un champ existant dans l’objet que vous souhaitez. Vous pouvez aussi effectuer un tri sur des objets liés ou sous-objets de l’objet principale. Dans ce cas vous devez utiliser la structure suivante :

<object_entityid>__<name_of_the_field> 

Si vous devez effectuer un tri sur plusieurs colonnes à la fois, il vous suffit de séparer les champs avec une virgule dans le requête :

orderBy=<name_of_the_field1>:<sort_direction_of_field1>,<name_of_the_field2>:<sort_direction_of_field2>

Sort direction

ASC pour croissant et DESC pour décroissant. Par défaut le tri est toujours croissant, il n’est donc pas nécessaire de le spécifier dans la requête :

orderBy=<name_of_the_field>  

Voici un exemple de requête avec un tri décroissant sur la date de dernière mise à jour :

curl    -X GET https://trial.nicoka.com/api/<account_domain>/employees/?orderBy=udate:DESC  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

Sélection restreinte à certains champs

Par défaut lorsque que vous faites un appel à l’API, le système vous retourne l’ensemble des champs auxquels vous avez accès. Si vous souhaitez faire un retour restreint à certains champs, il suffit de passer ceux-ci dans le paramètre $select.

Voici un exemple de requête avec le nom, prénom et email des collaborateurs en retour:

curl    -X GET https://trial.nicoka.com/api/<account_domain>/employees/?$select=first_name,last_name,email  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

Vous pouvez aussi passer l’identifiant unique des champs :

<entity_id>__<fieldname>

Format de sortie

L’API de Nicoka vous permet de récupérer vos données sous différents formats :

• xml : il faut ajouter le paramètre __format=xml
• odata : il faut ajouter le paramètre __format= odata

Filtres

Si vous souhaitez filtrer les résultats d’une recherche, il suffit d’ajouter les champs sur lesquels vous souhaitez filtrer dans votre requête.

<name_of_the_field>=<value> 

Remarque : pour passer plusieurs valeurs pour un champ il suffit d’utiliser les crochets :

<name_of_the_field>[]=<value1>&<name_of_the_field>[]=<value2>&…  

Champs de type texte

Sur les champs de type “texte” Nicoka fait par défaut une recherche « commence par ». Si vous souhaitez faire une recherche de type « contient le mot » vous devez ajouter des pourcentages (%) autour de votre mot :

<name_of_the_field>=%<value>% 

Si vous souhaitez faire une recherche stricte sur un mot, il faut ajouter des apostrophes « ' » autour du mot :

<name_of_the_field>='<value>'  

Champs de type date

Si vous souhaitez filtrer sur un champ de type date, il faut passer la date au format « YYYY-MM-DD » (ex 2025-12-31). Si vous souhaitez ajouter une heure le format devient « YYYY-MM-DD hh:mm:ss » (ex 2025-01-31 22:45:00). Le système est capable de reconnaitre d’autres types de formats mais il est préférable d’utiliser ceux-ci.

<name_of_the_date_field>=<start_date> 

Par défaut lorsque vous passez une date, Nicoka va effectuer un filtre « supérieur ou égale à cette date ». Si vous souhaitez filtrer sur une journée ou une période, vous devez ajouter la date de fin à votre paramètre, séparé par une virgule :

<name_of_the_date_field>=<start_date>,<end_date>  

Pour faire un filtre « inférieur à une date », il suffit de laisser le premier paramètre vide mais garder la virgule :

<name_of_the_date_field>=,<end_date>  

Champs type liste déroulante

Pour les recherches sur les champs de type liste déroulante, vous pouvez passer l’id système du champ ou bien son libellé.

status=1 ou status=actif 

Champs de type Montant ou Quantité

Pour les recherches sur les champs de type montant ou quantité, le paramètre doit être un chiffre sans séparateur de milliers et avec un point comme séparateur de décimales si besoin. Si vous souhaitez faire un filtre en utilisant des opérateurs comme « plus grand que » ou « plus petit que », il suffit d’ajouter l’opérateur juste avant le chiffre :

salary=> 1 ou salary=<1000.10  

Recherche par mots clés

Certaines entités autorisent une recherche par mots clés. Dans ce cas vous devez utiliser le paramètre term :

term=<keywords>  

La recherche fonctionne comme dans l’application, à savoir :

• Si vous séparez vos mots clés par des espaces, le système fera une recherche « inclusive » et ne retournera que les enregistrements qui contiennent tous vos mots clés. En terme de performance il vaut mieux commencer par les mots les plus discriminants (ex: projet chef sera plus rapide que chef de projet).
• Si vous séparez vos mots par des virgules, le système fera une recherche de type « ou ».
• Si vous ajoutez des apostrophes autour de vos mots clés,il fera une recherche stricte. Sinon, par défaut, il fait une recherche approximative.

Détail d’un objet

Nous allons maintenant voir comment récupérer les informations d’un objet. Par exemple, le détail d’un collaborateur.

Requête

Le chemin d’accès à toujours la même forme :

https://<account_subdomain>.nicoka.com/api/<resource_name_in_plural>/<id_of_the_resource>/ 

Exemple :

curl    -X GET https://<account_subdomain>.nicoka.com/api/employees/1/  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

Réponse

Exemple :

{ 
"id": "1",  
"employeeid": "1",  
"code": "",  
"status": "1",  
"todo_state": "100",  
"last_name": "LUTHOR",  
"middle_name": null,  
"first_name": "Lex",  
"keyname": null,  
"keysound": null,  
"gender": "M",  
"birth_date": 1977 -01-01, 
"place_of_birth": "New York",  
"country_of_birth": "us",  
"nationality": "us",  
"nationality_2": "fr",  
"civil_status": "2",  
"email": "xvilain@nicoka.com",  
"communication_language": "fr",  
"social_networks": null,  
"social_security_nb": "XXXXXXXXXXXXXXX",  
"kn_number_year": null,  
"kn_year_from": null,  
"picture": "1ygvpwtue4cd8pb5j4t539yn0i12e59.jpg",  
"picture_location": "users",  
"creation_type": "0",  
"source": null,  
"headline": "CEO", 
"compid" : "1", 
"hire_date": "2010 -03-04", 
… 
"whid": "2",  
"candidateid": null,  
"indexing_status": "1",  
"active": "1",  
"archive ": null,  
"loekz": "0",  
"cdate": "2012 -01-19 20:35:39",  
"cname": "1",  
"udate": "2018 -01-19 20:35:39",  
"uname": "1",  
"versi": "105"  
}

Nous retrouvons dans la réponse l’ensemble des champs auxquels l’utilisateur qui effectue la requête a accès.
Nous allons détailler les champs « commun » aux objets principaux. Vous trouverez le détail complet des champs de la fiche collaborateur dans le chapitre consacré à cet objet.

Paramètres	Type	Description
id	integer/ string	Il s’agit de l’identifiant unique de l’objet. Pour les objets « maitre », cet identifiant est toujours un entier. Pour les enfants d’un objet principale, l’identifiant peut être composé de plusieurs éléments. Dans ce cas, il s’agit d’une liste d'entiers séparés par « : ».
label	String	Libellé de l’ objet
active	boolean	Indicateur Actif ou non
archive	integer	Niveau d’archivage
loekz	boolean	Indicateur de suppression. Si l’objet est supprimé, cet attribut prend la valeur « 1 »
cdate	datetime	Date de création de l’objet
cname	integer	Identifiant de l’utilisateur qui a créé l’objet
udate	datetime	Date de dernière mise à jour de l’objet
uname	integer	Identifiant de l’utilisateur qui a effectué la dernière mise à jour de l’objet
versi	integer	Numéro de version de l’objet. Ce chiffre est incrémenté à chaque modification de l’objet

Paramètres de la requête

Lecture « Human Friendly »

Lorsque que vous faites une requête de détail d’un objet, on ne retrouve que les identifiants numériques des champs liés à d’autres objets ou bien à des listes de valeurs. Pour afficher la valeur « textuelle » des champs en question, il suffit d'ajouter le paramètre __hr (Human Readable) à votre requête.

Exemple :

curl    -X GET https://<account_subdomain>.nicoka.com/api/employees/1/?__hr=1  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

RESPONSE

{ 
"id": "1",  
"employeeid": "1",  
… 
"communication_language__formated": "Français",  
"civil_status__formated": "Marié",  
"proid__formated": "Administrateur",  
"compid__formated": "Lex Corp",  
"jobtitle__formated": "Associé",  
"contract_type__formated": "Freelance",  
"departmentid__formated": "Informatique",  
"hire_date__formated": "04/03/2010",  
"status__formated": "Nouveau",  
"salary_cost__formated": "150,00",  
"global_cost__formated": "176,00",  
"whid__formated": "36",   
"gender__formated": "Homme",  
"salary_time_unit__formated": "Par mois",  
"cdate__formated": "19/01/2012",  
"cname__formated": "Lex Luthor",  
"udate__format ed": "19/01/2018",  
"uname__formated": "Lex Luthor",  
}

Langue

Par défaut, les libellés sont retournés par l’API dans la langue de l’utilisateur de l’API. Pour modifier la langue, il suffit d’ajouter le paramètre language à votre requête.

Exemple :

curl    -X GET https://<account_subdomain>.nicoka.com/api/employees/1/?__hr=1&language=en  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

RESPONSE

{ 
"id": "1",  
"employeeid": "1",  
… 
"communication_language__formated": "French",  
"civil_status__formated": "Married",  
"proid__formated": "Administrator",  
"departmentid__formated": " Information System ", 
"status__formated": "New",  
… 
"gender__formated": "Male",  
"salary_time_unit__formated": "Per Month",  
… 
}

Détail des sous-objets

Ces objets de Nicoka se comportent comme des « objets d’entêtes » contenant des « objets enfants ».
Par exemple, un collaborateur peut avoir des expériences professionnelles. Dans ce cas, pour accéder au détail des sous-objets, vous avez deux possibilités:

• Accès direct à un type de sous-objet
• Accès à un objet parent avec ses sous-objets

Accès direct à un type de sous-objet

https://<account_subdomain>.nicoka.com/api/<resource _name_in_plural>/<id_of_the_ resource>/<branch_name_in_plural>  

<branch_name_in_plural> représente le nom du sous-objet en minuscule et au pluriel.

Exemple :

curl    -X GET https://<account_subdomain>.nicoka.com/api/employees/4/experiences/  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

RESPONSE

[ 
{ 
    "id": "2",  
    "label": "Associé",  
    "expid": "2",  
    "employeeid": "4",  
    "candidate_expid": null,  
    "type": 1,  
    "start_date": "1996 -10-03", 
    "end_date": null,  
    "compid": "1",  
    "jobtitle": "12",  
    "departmentid": "1",  
    "divisionid" : "0", 
    "contract_type": "0",  
    "locationid": "0",  
    "currency": "EUR",  
    "salary": "4800",  
    "bonus": null,  
    "mobility": null,  
    "comment": null,  
    "current": "1",  
    "importance": null,  
    "linkedin_reference": null,  
    "company_name": "Lex Corp",  
},
{ 
    "id": "14",  
    "label": "Project Manager",  
    "expid": "14",  
    "employeeid": "4",  
    "candidate_expid": null,  
    "type": 2,  
    "start_date": "1995 -12-01", 
    "end_date": "1995 -12-30", 
    "compid": "10",  
    "jobtitle": "6",  
    "departmentid": "0",  
    "divisionid": "0",  
    "contract_type": "0",  
    "locationid": null,  
    "currency": null,  
    "salary": null,  
    "bonus": null,  
    "mobility": null,  
    "comment": "",  
    "current": "0",  
    "importance": null,  
    "linkedin_reference": null,  
    "company_name": "lexx",  
}
]

Accès à un objet parent avec ses sous-objets

Si vous souhaitez récupérer le détail des sous objets, directement au niveau de l’objet principal et sans avoir à faire des requêtes distinctes, vous devez utiliser le paramètre __branches.

https://<account_subdomain>.nicoka.com/api/<resource _name_in_plural>/<id_of_the_ resource>/?__branches=<branch1_name_in_plural>,<branch2_name_in_plural>,<branch3_name_in_plural>  

Exemple :

curl    -X GET https://<account_subdomain>.nicoka.com/api/employees/1/?__branches=skills,languages  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

RESPONSE

{ 
"id": "1",  
"label": "Lex Luthor",  
"employeeid": "1",  
… 
"skills": [ 
    { 
    "id": "1:1",  
    "label": "MySql",  
    "employeeid": "1",  
    "skillid": "1",  
    "level": "2",  
    "skill_label": "MySql"  
    },
    { 
    "id": "1:2",  
    "label": "Php",  
    "employeeid": "1",  
    "skillid": "2",  
    "level": "4",  
    "skill_label": "Php"  
    }], 
    "languages": [  
    { 
    "id": "1:en",  
    "label": "English",  
    "employeeid": "1",  
    "code": "en",  
    "level": "4"  
    },
    { 
    "id": "1:es",  
    "label": "Spanish",  
    "employeeid": "1",  
    "code": "es",  
    "level": "3"  
    }] 
} 

Liste avec les objets et les sous-objets ($expand)

Si vous souhaitez récupérer le détail des sous-objets, directement au niveau de la liste de l'objet principal et sans avoir à faire des requêtes distinctes, vous devez utiliser le paramètre $expand.

https://<account_subdomain>.nicoka.com/api/<resource _name_in_plural>/?$expand=<branch1_name_in_plural>,<branch2_name_in_plural>,<branch3_name_in_plural>  

Exemple :

curl    -X GET https://<account_subdomain>.nicoka.com/api/employees/?$expand=languages  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

RESPONSE

{ 
    "queryUid": "9edbf7bcddfbd0f0db649b6da8680d61",  
    "offset": 10,  
    "limit": 10,  
    "page": 2,  
    "pages": 3,  
    "total": 25,  
    "data": [ { 
        "id": "1",  
        "label": "Lex Luthor",  
        "employeeid": "1",  
        … 
        "languages": [ 
            { 
            "id": "1:en",  
            "label": "English",  
            "employeeid": "1",  
            "code": "en",  
            "level": "4"  
            },
            … 
            ]       
    }] 
}

Liste avec les sous-objets uniquement

Si vous souhaitez récupérer la liste des sous-objets uniquement, vous devez utiliser la requête suivante :

https://<account_subdomain>.nicoka.com/api/<resource_name_in_plural/<branch_name_in_plural>/

Exemple :

curl    -X GET https://<account_subdomain>.nicoka.com/api/employees/languages/  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

RESPONSE

{
"queryUid": "bebc8ceb7fd697bc97d84bd75be12799",
"offset": 0,
"limit": 3,
"page": 1,
"pages": 1,
"total": 3,
"data": [
    {
    "employeeid": 8,
    "code": "en",
    "level": 2
    },
    {
    "employeeid": 49,
    "code": "de",
    "level": 1
    },
    {
    "employeeid": 49,
    "code": "en",
    "level": 4
    }
]
}

Schéma

Pour connaitre la liste des champs d’un objet et la liste des sous-objets disponibles, vous pouvez utiliser la requête suivante :

https://<account_subdomain>.nicoka.com/api/<resource_name_in_plural>/schema

Exemple :

curl    -X GET https://<account_subdomain>.nicoka.com/api/employees/schema  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

RESPONSE

{
    "entityid": 101,
    "label": "Collaborateur",
    "labelPlural": "Collaborateurs",
    "gender": "M",
    "fields": [
        {
        "id": "employeeid",
        "label": "ID Système",
        "bulkable": 0,
        "required": 0,
        "uiComponent": {
            "id": 7,
            "label": "Nombre"
        },
        "length": null
        },
        {
        "id": "first_name",
        "label": "Prénom",
        "bulkable": 1,
        "required": 1,
        "uiComponent": {
            "id": 1,
            "label": "Alphanumérique"
        },
        "length": 255
        }, 
        … 
    ], 
    "branches": [  
        "user", 
        "addresses",  
        "experiences",  
        "skills",  
        "partners",  
        "certifications",  
        "documents",  
        "salaryHistory",  
        "languages",  
        "publications",  
        "salaryBonus",  
        …  
    ], 
}

Schéma des « sous-objets / branches »

Pour obtenir le schéma des sous-objets d’un objet principal, il suffit d’utiliser le point d’entrée suivant :

https://<account_subdomain>.nicoka.com/api/<resource_name_in_plural>/schema/<branch_name>

Exemple :

curl    -X GET https://<account_subdomain>.nicoka.com/api/employees/schema/languages  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

RESPONSE

    {
    "entityid": 127,
    "label": "Langue",
    "labelPlural": "Langues",
    "gender": "F",
    "fields": [
        {
        "id": "code",
        "label": "Langue Parlée",
        "bulkable": 1,
        "required": 0,
        "uiComponent": {
            "id": 2,
            "label": "Liste déroulante",
            "related": {
            "id": 112,
            "label": "Langue Parlée",
            "urn": "application/entities/112/values/"
            }
        },
        "length": null
        },
        {
        "id": "level",
        "label": "Niveau",
        "bulkable": 1,
        "required": 0,
        "uiComponent": {
            "id": 2,
            "label": "Liste déroulante",
            "related": {
            "id": 113,
            "label": "Niveau",
            "urn": "application/entities/113/values/"
            }
        },
        "length": null
        }
    ],
    "branches": [
        "endorsements",
        "languages"
    ]
    }

Certains champs reposent sur des composants de type liste déroulante. Il s’agit soit de liste statique (non modifiable via le paramétrage) soit de liste dynamique (reposant elle -même sur une entité de Nicoka). Dans le second cas vous verrez apparaitre les informations related vous donnant :

• id : l’identifiant unique de l’entité de référence
• label : le libellé dans la langue de requête
• urn : le point d’entrée de l’api qui affiche les paramètres de l’entité. Si l’entité n’a pas un point d’entrée spécifique, il sera toujours sous la forme application/entities/<id_of_the_entity>/values/ afin d’obtenir la liste des valeurs existantes pour cette entité.

Exemple :

curl    -X GET https://<account_subdomain>.nicoka.com/api/application/entities/113/values/  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

Cas particulier des champs spécifiques

Informations

Lorsque vous ajoutez des champs à un objet Nicoka, vous pouvez y accéder via la « branch » metadata (au singulier).
Pour obtenir la description des champs spécifiques, vous devez utiliser le point d’entrée customFields.

https://<account_subdomain>.nicoka.com/api/<resource_name_in_plural>/customFields/

REMARQUE

Vous n'avez pas la possibilité d'enrichir tous les objets de Nicoka avec des champs spécifiques.

Exemple :

curl    -X GET https://<account_subdomain>.nicoka.com/api/contacts/customFields  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

RESPONSE

{
"fields": [
    {
    "id": 12,
    "label": "surnom",
    "fieldid": 12,
    "language": "en",
    "placeholder": "",
    "tooltip": 0,
    "related_entityid": null,
    "related_fieldname": null,
    "ui_componentid": 1,
    "ui_size": 3,
    "size": null,
    "required": 0,
    "in_search_engine": 0,
    "position": 1,
    "categoryid": 4,
    "params": null,
    "active": 1,
    "loekz": 0,
    "cdate": "2025-09-02 16:20:14",
    "cname": 46,
    "udate": "2025-09-02 16:20:14",
    "uname": 46,
    "versi": 1,
    "labelInOriginalLanguage": "surnom",
    "placeholder__orginal": "",
    "updateLink": "?route=contacts/admin/fields&fieldid=12"
    },
    {
    "id": 13,
    "label": "source du contact",
    "fieldid": 13,
    "language": "en",
    "placeholder": "",
    "tooltip": 0,
    "related_entityid": null,
    "related_fieldname": null,
    "ui_componentid": 1,
    "ui_size": 3,
    "size": null,
    "required": 0,
    "in_search_engine": 0,
    "position": 2,
    "categoryid": 4,
    "params": null,
    "active": 1,
    "loekz": 0,
    "cdate": "2025-09-02 16:22:48",
    "cname": 46,
    "udate": "2025-09-02 16:22:48",
    "uname": 46,
    "versi": 1,
    "labelInOriginalLanguage": "source du contact",
    "placeholder__orginal": "",
    "updateLink": "?route=contacts/admin/fields&fieldid=13"
    }
],
"categories": []
}

Afficher les champs spécifiques dans une recherche d’objets

Si vous souhaitez récupérer la valeur des champs spécifiques dans vos requêtes de liste d’objets, vous devez ajouter le paramètre __metadata dans l’url de la requête :

https://<account_subdomain>.nicoka.com/api/<resource_name_in_plural>/?__metadata=1 

Exemple :

curl    -X GET https://<account_subdomain>.nicoka.com/api/employees/?__metadata=1  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

RESPONSE

{ 
"queryUid": "9edbf7bcddfbd0f0db649b6da8680d61",  
"offset": 0,  
"limit": 26,  
"page": 1,  
"pages": 1,  
"total": 26,  
"data": [  
    { 
        "employeeid": "7",  
        "code": "0005",  
        … 
        "id": "7",  
        "label": "Adam Black",  
        "cus_fld_1": " Ok", 
        "cus_fld_3": "Bleu ", 
        "cus_fld_4": "12",  
        "cus_fld_5": "1",  
        "cus_fld_20": "2016 -02-02" 
    }, 
    … 
    ]
} 

Les champs spécifiques ont la forme suivante :

cus_fld_<fieldid>:<value>  

Liste des Points d’entrée par module

Candidature

- /jobs/{jobid}/apply  
- /jobs/openApplicationApply

Utilisateur

- /users  
- /users/{userid}  
- /me

Branches

- applicationsLinks  
- passwordRecoveryToken  
- pushSubscriptions

Document

- /documents  
- /documents/{documentid}

Branches

- partners  
- contentVersions

Société

- /companies  
- /companies/{companyid}

Branches

- metadata  
- addresses  
- documents

Collaborateur

- /employees  
- /employees/{employeeid}

Branches

- skills  
- partners  
- certifications  
- languages  
- educations  
- publications  
- notes  
- assets  
- lunchVouchers  
- user  
- emergencyContacts  
- medicalVisits  
- experiences  
- positions  
- contracts  
- salaryHistory  
- dependents  
- beneficiaries  
- meansOfTransportation  
- workAccidents  
- salaryBonus  
- costHistory  
- disciplinaryMeasures  
- attendanceTerms  
- mandates  
- accreditations  
- handicaps  
- healthInsurances  
- metadata  
- addresses  
- documents

Agence

- /locations  
- /locations/{locationid}

Formation

- /trainings  
- /trainings/{trainingid}

Branches

- attendees  
- metadata  
- addresses  
- documents

Demande de formation

- /trainingRequests  
- /trainingRequests/{requestid}

Plan de formation

- /trainingPlans  
- /trainingPlans/{planid}

Branches

- items

Feuille de temps

- /timesheets  
- /timesheets/{timesheetid}

Branches

- items

Ligne de temps

- /timesheetItems  
- /timesheetItems/{itemid}

Branches

- items

Compteur

- /timeoffCounters  
- /timeoffCounters/{counterid}

Dépense

- /expenses  
- /expenses/{expenseid}

Branches

- attachments  
- partners

Note de frais

- /expenseClaims  
- /expenseClaims/{claimid}

Branches

- attachments

Compte

- /customers  
- /customers/{customerid}

Branches

- partners  
- sites  
- customizingPoints  
- catalogs  
- materials  
- externalIds  
- metadata  
- addresses  
- documents

Contact

- /contacts  
- /contacts/{contactid}

Branches

- partners  
- accounts  
- externalIds  
- user  
- metadata  
- addresses  
- documents

Activité

- /crmActivities  
- /crmActivities/{activityid}

Branches

- targets  
- surveyAnswers

Fournisseur

- /suppliers  
- /suppliers/{supplierid}

Branches

- partners  
- references  
- areas  
- interventionArea  
- user  
- metadata  
- addresses  
- documents

Demande d'Achat

- /purchaseRequests  
- /purchaseRequests/{requestid}

Branches

- items  
- partners  
- contributors  
- documents

Commande d'Achat

- /purchaseOrders  
- /purchaseOrders/{orderid}

Branches

- items  
- contributors  
- deadLines  
- partners  
- metadata  
- documents

Ligne de commande

- /purchaseOrderItems  
- /purchaseOrderItems/{itemid}

Branches

- items

Facture d'achat

- /purchaseInvoices  
- /purchaseInvoices/{invoiceid}

Branches

- items  
- contributors  
- partners  
- invoiceLinks  
- metadata  
- documents

Ligne de Facture

- /purchaseInvoiceItems  
- /purchaseInvoiceItems/{itemid}

Branches

- materialDocumentLinks  
- items

Candidat

- /candidates  
- /candidates/{candidateid}

Branches

- activities  
- experiences  
- skills  
- partners  
- certifications  
- languages  
- publications  
- educations  
- tests  
- desireLocalizations  
- consentRequests  
- consents  
- references  
- workflowInstances  
- applicationErrors  
- externalIds  
- user  
- metadata  
- addresses  
- documents

Action

- /candidatesActivities  
- /candidatesActivities/{activityid}

Branches

- targets  
- activities

Mission

- /jobs  
- /jobs/{jobid}  
- /jobs/\bopenApplicationApply\b/  
- /jobs/published

Branches

- i18n  
- partners  
- candidates  
- postingLogs  
- externalPartners  
- metadata  
- addresses  
- documents

Produit

- /materials  
- /materials/{materialid}

Branches

- texts  
- pricings  
- pictures  
- attributes  
- references  
- bomComponents  
- serialNumbers  
- stocks

Catalogue

- /catalogs  
- /catalogs/{catalogid}

Branches

- i18n  
- artefacts  
- items  
- categories

Activité

- /employeeActivities  
- /employeeActivities/{activityid}

Branches

- targets

Projet

- /projects  
- /projects/{projectid}

Branches

- items  
- computerSystems  
- customizingPoints  
- catalogs  
- materials  
- ticketSlas  
- sapSystems  
- risks  
- partners  
- directories  
- steps  
- metadata  
- addresses  
- documents

Activité

- /projectItems  
- /projectItems/{itemid}

Branches

- references  
- plans  
- prices  
- items

Evénement

- /agendaEvents  
- /agendaEvents/{eventid}

Branches

- attendees  
- references  
- documents

Lieu de travail

- /worklocations  
- /worklocations/{worklocationid}

Notification

- /pushNotifications  
- /pushNotifications/{notificationid}

Branches

- targets

Opportunité

- /opportunities  
- /opportunities/{opportunityid}

Branches

- contributors  
- metadata  
- documents

Devis

- /quotations  
- /quotations/{quotationid}

Branches

- items  
- deadLines  
- contributors  
- metadata  
- documents

Ligne de Devis

- /quotationItems  
- /quotationItems/{itemid}

Branches

- items

Commande

- /orders  
- /orders/{orderid}

Branches

- items  
- deadLines  
- contributors  
- revenuDistributions  
- metadata  
- documents

Ligne de Commande/Contrat

- /orderItems  
- /orderItems/{itemid}

Branches

- items

Facture

- /invoices  
- /invoices/{invoiceid}

Branches

- partners  
- items  
- contributors  
- revenuDistributions  
- metadata  
- documents

Ligne de Facture/Avoir

- /invoiceItems  
- /invoiceItems/{itemid}

Branches

- items

Paiement

- /payments  
- /payments/{paymentid}  
- /payments/paypal\/notifications/

Branches

- items

Ticket

- /tickets  
- /tickets/{ticketid}

Branches

- events  
- contributors  
- sapTransportOrders  
- additionnalCosts  
- notes  
- deadLines  
- planActivities  
- metadata  
- documents

Evènement

- /ticketEvents  
- /ticketEvents/{eventid}

Branches

- events

Temps passé par statut

- /ticketStatusTimes  
- /ticketStatusTimes/{timeid}

Log changement de statut

- /ticketStatusLogs

Tâche Plannifiée

- /planActivities  
- /planActivities/{planactivityid}

Branches

- planActivities

Domaine

- /hseDomains  
- /hseDomains/{domainid}

Branches

- i18n  
- partners  
- directories  
- documents

Attention

Cette liste n’est pas exhaustive.

Mise à jour d’un objet

Nous allons maintenant voir comment mettre à jour un objet.

Requête

Il faut utiliser la méthode « POST ». Le chemin d’accès a toujours la même forme :

https://<account_subdomain>.nicoka.com/api/<resource _name_in_plural>/<id_of_the_ resource>/

Exemple :

curl    -X POST https://<account_subdomain>.nicoka.com/api/employees/1/  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

Exemple de modification du champ first_name, voici le corps de la requête :

{ 
  "first_name" : "Marie",  
}

RESPONSE

{
    "success": "Collaborateur <b>Marie Dupont</b> a été modifié",
    "object": {
        "id": 48,
        "label": "Marie Dupont",
        "employeeid": 48,
        "uid": "1-1756194989f7c5fe2f54565b7214d772f5483e334effe",
        "assign_to_employeeid": null,
        "code": null,
        "external_reference": null,
        "status": 2,
        "last_name": "Dupont",
        "birth_name": "Saulnier",
        "middle_name": null,
        "first_name": "Marie",  
        … 
    "loekz": 0,
    "cdate": "2025-08-26 09:56:28",
    "cname": 46,
    "udate": "2025-08-28 16:49:51",
    "uname": 54,
    "versi": 2,
    "updateLink": "?route=employees/main&employeeid=48"
    }
}

Paramètres	Type	Description
success	string	Si le traitement s'est effectué avec succès, ce paramètre contiendra le message de succès
object	JSON	Détail de l’objet qui vient d’être modifié. Il s’agit de la même réponse que pour une requête de « détail d’objet »
error	string	Si une erreur est survenue, ce paramètre sera non vide et contiendra le message d’erreur
code	integer	Code de l’erreur

Mise à jour d’un sous-objet

Nous allons maintenant voir comment mettre à jour un objet.

Requête

Il faut utiliser la méthode « POST ».
Le chemin d’accès à toujours la même forme. Il faut obligatoirement spécifier l’id de la ressource.

https://<account_subdomain>.nicoka.com/api/<resource_name_in_plural>/<id_of_the_resource>/<branch_name>/<id_of_the_branch_in_line> 

Remarque

<id_of_the_branch_in_line> est généralement l’id (un identifiant numérique) du sous-objet.
Parfois, les sous-objets ont un identifiant composite (plusieurs champs pour définir une clé uniquement). Dans ce cas, l’id aura la forme suivante : <id_of_the_resource> :<key_field_2>… :<key_field_n>

Exemple :

curl    -X POST https://<account_subdomain>.nicoka.com/api/employees/1/languages/1:en/  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

Exemple de modification du champ level pour le sous-objet « langues parlées » (languages), voici le corps de la requête :

{ 
  "level" : "1 " 
}

Réponse :

{ 
    "success" : "Ressource <b>Lext Luthor</b> a été modifiée",  
    "object"   :  
 { 
   "label": "Lex Luthor",  
   "employeeid": "1",  
   "code": "",  
   "status": "1",  
   "todo_state": "100",  
          "last_name": "Lex",  
   "middle_name": " Peter ", 
   "first_name": "Luthor",  
   … 
   "loekz": "0",  
   "cdate": "2012 -01-22 12:33:28",  
   "cname": "1",  
   "udate": "2018 -01-22 12:33:28",  
   "uname": "4",  
   "versi": "106"  
 },
    "languages"   : 
{ 
          "id": "1:en",  
     "label": "Anglais",  
  "employeeid": "1",  
  "code": "en",  
  "level": "1",  
  "updateLink": "?mod=employees&act=languages&sac=update&inlineid=1:en",  
  "employeeid__formated": "Lex Luthor",  
  "code__formated": "Anglais",  
  "level__formated": "Débutant"  
 }

Création d’un objet

Nous allons maintenant voir comment créer une ressource depuis l’API de Nicoka. Le fonctionnement est très proche de la requête de mise à jour.

Requête

Il faut utiliser la méthode « POST ». Le chemin d’accès à toujours la même forme :

https://<account_subdomain>.nicoka.com/api/<resource_name_in_plural>/ 

Exemple :

curl    -X POST https://<account_subdomain>.nicoka.com/api/contacts/  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

Exemple de création d’une ressource , voici le corps de la requête (en alimentant les champs obligatoires) :

{ 
  "first_name" : "Luc",  
  "last_name": "Cage",   
}

RESPONSE

{
    "success": "Contact <b>Luc Cage</b> a été ajouté",
    "object": {
        "id": "5279",
        "label": "Luc Cage",
        "contactid": "5279",
        "uid": "1-1756393881a7cc39a6f1bf56fbb386267e5632b5554b5",
        "type": 1,
        … 
        "first_name": "Luc",
        "last_name": "Cage",
        … 
    "loekz": 0,
    "cdate": "2025-08-28 17:11:21",
    "cname": 54,
    "udate": "2025-08-28 17:11:21",
    "uname": 54,
    "versi": 1,
    "initials": "L C",
    "consent_management_link": "https://master.nicoka.dev/public/contacts/consent/1-1756393881a7cc39a6f1bf56fbb386267e5632b5554b5/",
    "unsubscribe_link": "https://master.nicoka.dev/public/subscriptions/unsubscribe/1-1756393881a7cc39a6f1bf56fbb386267e5632b5554b5/?eid=250&id=5279",
    "portal_registering_link": "https://master.nicoka.dev/portal/?a=register&token=1-1756393881a7cc39a6f1bf56fbb386267e5632b5554b5&id=5279",
    "name": "Luc Cage",
    "updateLink": "?route=contacts/main&contactid=5279"
    }
} 

Cas Particulier des Documents

Vous pouvez rattacher des documents à certaines entités. Dans ce cas, vous verrez dans le schéma de l’entité la branche « documents ».

Requête

Il faut utiliser la méthode « POST ».

https://<account_subdomain>.nicoka.com/api/<resource_name_in_plural>/<id_of_the_resource>/documents/

Exemple :

curl    -X POST https://<account_subdomain>.nicoka.com/api/employees/48/documents  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

Exemple du corps de la requête :

{ 
    "filename" : "file.pdf",  
    "doctype ": "1",  
    "categoryid ": "1", 
    "base64_file": "Qm9uam91cg==",  
}

Paramètres	Type	Description
filename	string	Il s’agit du nom du fichier avec son extension
doctype	int	Il s’agit de l’id interne du type de document
categoryid	int	l s’agit de l’id interne de la catégorie du document
base64_file	string	Il s’agit du contenu du fichier encodé en Base64

Réponse

RESPONSE

{
"success": "Le document file.pdf a été ajouté au Collaborateur Marie Dupont",
"docid": "66230"
}

Remarque

Nicoka va effectuer un contrôle de doublon sur le contenu du document et renvoyer une erreur en cas de doublon. Vous pouvez, dans certains cas, ajouter des documents lors de la création d’un objet. Mais, généralement, il faut créer l’objet et ensuite lui ajouter les documents un par un.

Cas Particulier des « Adresses (ville, code postal…) »

Pour certaines entités, vous aurez une branche « addresses ». Cette branche a une propriété particulière. Les données « Ville, Code Postal, Région (State), Pays » qu'elle contient sont recopiées au niveau de l’entité, pour de raison d’optimisation.
Comme une entité peut avoir plusieurs types d’adresses, il n’y a que le type d’adresse marqué comme « par défaut » qui sera recopié ou bien s'il n'y a' qu’un seul type d’adresse.

Requête

Il faut utiliser la méthode « POST ».

• Soit directement au niveau de l’entité :

  https://<account_subdomain>.nicoka.com/api/<resource_name_in_plural>/<id_of_the_resource>/
  

• Soit en utilisant directement la branche :
  

  https://<account_subdomain>.nicoka.com/api/<resource_name_in_plural>/<id_of_the_resource>/addresses/
  

  Exemple :
  

  curl    -X GET https://<account_subdomain>.nicoka.com/api/employees/48/addresses  
          -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"
  

  RESPONSE

  [
      {
      "id": 45,
      "label": "Adresse Principale",
      "adrid": 45,
      "employeeid": 48,
      "type": 1,
      "lat": "47.47683742",
      "lng": "-0.55612600",
      "uid": "ChIJoSVJIep4CEgR90OJUo8PoAo",
      "name1": null,
      "name2": null,
      "street_number": "25",
      "street": "25 Rue Lenepveu",
      "street_only": "Rue Lenepveu",
      "city": "Angers",
      "zipcode": "49100",
      "state": "Pays de la Loire",
      "stateid": 759,
      "county": "49 - Maine-et-Loire",
      "countyid": 897,
      "country": "FR",
      "areaid": 2289,
      "area_level": 8,
      "area_lvl1": 4,
      "area_lvl2": 21,
      "area_lvl3": 681,
      "area_lvl4": 744,
      "area_lvl5": 759,
      "area_lvl6": 897,
      "area_lvl7": 2233,
      "phone1": null,
      "phone2": null,
      "fax1": null,
      "fax2": null,
      "email1": null,
      "email2": null,
      "updateLink": "?route=&adrid=45"
      }
  ]
  

Suppression d’un objet

Nous allons maintenant voir comment supprimer une ressource depuis l’API de Nicoka.
Il existe deux principaux types d'objets dans Nicoka :

• Les objets sans gestion de version. Pour ces objets, la suppression signifie que l’on supprime la ligne correspondante dans la table.
• Les objets avec gestion de version. Pour ces objets, la suppression signifie de passer le paramètre « loekz » à 1. Attention cela ne signifie pas que l’on peut annuler la suppression de l’objet mais que l’on garde l’information que l’objet a été supprimé.

ATTENTION

Vous ne pouvez pas annuler la suppression d’un objet.

Requête

Il faut utiliser la méthode « DELETE » . Le chemin d’accès à toujours la même forme en ajoutant le paramètre __confirmed :

https://<account_subdomain>.nicoka.com/api/< resource_name_in_plural>/<id_of_the_resource>/?__confirmed=1

Exemple :

curl    -X DELETE https://<account_subdomain>.nicoka.com/api/contacts/5279/?__confirmed=1  
        -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}"

Réponse

RESPONSE

{ 
    "success": "Contact Luc Cage a été supprimé" 
}