API de Management

Web Services / API d'intégration V6

Prérequis

*** Prérequis à l’utilisation des web services de management ***

Pour obtenir les accès d’authentification auprès des web services de Trust and Sign, il faut effectuer les démarches de création de compte auprès de Namirial.

Les APIs de management sont accessibles avec un opérateur Admin créé spécifiquement ou non au sein de la page d'administration des opérateurs.

Les URL de base des APIs de management sont les suivantes :

pour l’environnement d’intégration : https://integration-api.ekeynox.net. Cet environnement est mis à jour régulièrement et possède les toutes dernières fonctionnalités ;
pour l’environnement de pré-production : https://preprod-api.ekeynox.net. Cet environnement est mis à jour à la même date que la production ;
pour l’environnement de production : https://api.ekeynox.net ;

Les chapitres suivants décrivent l'API JSON. Suivant l'évolution du produit, nous pouvons ajouter des champs non documentés dans les retours. Il ne faudra donc pas être trop restrictif sur les payloads.

Attention, le nom des clés est sensible à la casse.

Authentification

L’authentification « Basic » est utilisée ici ; elle suit la norme RFC1945. Un header HTTP nommé AUTHORIZATION doit être ajouté aux requêtes. Ce dernier est de la forme :

AUTHORIZATION = Basic base64(email:password)

Le bout de code suivant peut être utilisé en Java pour générer ce header :

String header = "Basic " + Base64.getEncoder().encodeToString( ( email + ":" + password ).getBytes( StandardCharsets.UTF_8 ) );

Par exemple, pour un login “john123456” et un mot de passe “azerty” on obtient le header suivant :

AUTHORIZATION = Basic am9objEyMzQ1NjphemVydHk=

Gestion d’erreur

Si une erreur se produit lors d’une requête, un code HTTP standard est renvoyé avec un JSON d’erreur contenant un code spécifique au serveur Trust and Sign, un message explicatif et les éventuels paramètres invalides.

Par exemple :

{
  "error":{
    "message":"Server error",
    "code":1000
  }
}

Récupération des opérateurs

** Requête **

GET /contract/management/users?withInactive=false HTTP/1.1
Content-Type : application/json

Parameter	Description
`withInactive`	(optionnel) Inclut les opérateurs supprimés : true. Valeur par défault : false

withInactive : (optionnel) Inclut les opérateurs supprimés true. Valeur par défault : false

** Retour **

Un objet JSON contenant les informations suivantes :

Path	Type	Description
`[].uuid`	`UUID`	Uuid
`[].firstName`	`String`	Prénom
`[].lastName`	`String`	Nom
`[].email`	`String`	Email
`[].state`	`[ACTIVE, DELETE]`	Etat de l'opétateur
`[].authorizations`	`[ADMINISTRATION, VALIDATION, CLIENT_FILES_DOWNLOAD, CLIENT_FILES_TRANSFER, UPDATE_CLIENT_FILES]`	Authorisations
`[].linkedToAllProducts`	`Boolean`	Visibilité de tous les Produits
`[].linkedToAllGroups`	`Boolean`	Visibilité de tous les Groupes
`[].reportTypes`	`[ACTIVITY, EMAIL]`	Liste des types de rapports d'activité
`[].externalId`	`String`	Identifiant externe
`[].reporting`	`Boolean`	Dépréciée, utilisez reportTypes

[
  {
    "uuid" : "28f4b088-fccf-4842-9319-09f4844c3d4a",
    "firstName" : "john",
    "lastName" : "doe",
    "email" : "john.doe@namirial.com",
    "state" : "ACTIVE",
    "authorizations" : [ ],
    "reportTypes" : [ "ACTIVITY", "EMAIL" ],
    "linkedToAllProducts" : false,
    "linkedToAllGroups" : false,
    "externalId": "IdExterne"
  }
]

Création d'un opérateur

** Requête **

POST /contract/management/users/create HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "email" : "john.doe@namirial.com",
  "firstName" : "john",
  "lastName" : "doe",
  "authorizations" : [ "VALIDATION" ],
  "reportTypes" : [ "ACTIVITY", "EMAIL" ],
  "linkedToAllProducts" : false,
  "linkedToAllGroups" : false,
  "externalId": "IdExterne"
}

Path	Type	Description
`firstName`	`String`	Prénom
`lastName`	`String`	Nom
`email`	`String`	Email
`authorizations`	`[ADMINISTRATION, VALIDATION, CLIENT_FILES_DOWNLOAD, CLIENT_FILES_TRANSFER, UPDATE_CLIENT_FILES]`	Authorisations
`linkedToAllProducts`	`Boolean`	Visibilité de tous les Produits
`linkedToAllGroups`	`Boolean`	Visibilité de tous les Groupes
`externalId`	`String`	Identifiant externe
`[].reportTypes`	`[ACTIVITY, EMAIL]`	Liste des types de rapports d'activité
`[].reporting`	`Boolean`	Dépréciée, utilisez reportTypes

** Retour **

HTTP/1.1 204 No Content

Mise à jour d'un opérateur

Tous les champs sont optionnels (sauf l'email). Seuls les champs présents dans la requête sont mis à jour.

** Requête **

PUT /contract/management/users/update HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "email" : "john.doe@namirial.com",
  "firstName" : "john",
  "lastName" : "doe",
  "authorizations" : [ "VALIDATION" ],
  "reportTypes" : [ "ACTIVITY", "EMAIL" ],
  "linkedToAllProducts" : false,
  "linkedToAllGroups" : false,
  "externalId": "IdExterne"
}

Path	Type	Description
`firstName`	`String`	Prénom
`lastName`	`String`	Nom
`email`	`String`	Email
`.authorizations`	`[ADMINISTRATION, VALIDATION, CLIENT_FILES_DOWNLOAD, CLIENT_FILES_TRANSFER, UPDATE_CLIENT_FILES]`	Authorisations
`linkedToAllProducts`	`Boolean`	Visibilité de tous les Produits
`linkedToAllGroups`	`Boolean`	Visibilité de tous les Groupes
`externalId`	`String`	Identifiant externe
`[].reportTypes`	`[ACTIVITY, EMAIL]`	Liste des types de rapports d'activité
`[].reporting`	`Boolean`	Dépréciée, utilisez reportTypes

** Retour **

HTTP/1.1 204 No Content

Suppression d'un opérateur

DELETE /contract/management/users/delete HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "email" : "john.doe@namirial.com"
}

Path	Type	Description
`email`	`String`	Email de l'opérateur

** Retour **

HTTP/1.1 204 No Content

Mise à jour des produits accessibles

PUT /contract/management/users/products/bind HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "email" : "john.doe@namirial.com",
  "productsPublicId" : [ "P1" ]
}

Path	Type	Description
`email`	`String`	Email
`productsPublicId`	`Array`	Id Publique des produits

** Retour **

HTTP/1.1 204 No Content

Mise à jour des groupes accessibles

PUT /contract/management/users/groups/bind HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "email" : "john.doe@namirial.com",
  "groupsLabel" : [ "DEFAULT" ]
}

Path	Type	Description
`email`	`String`	Email
`groupsLabel`	`class java.util.UUID`	Label des groupes

** Retour **

HTTP/1.1 204 No Content

Création des opérateurs par batch

** Requête **

Le contenu du fichier .csv doit respecter la norme RFC4180 https://tools.ietf.org/html/rfc4180, avoir une ligne de header avec toutes les colonnes ci-dessous.

POST /contract/management/users/create/csv HTTP/1.1
Content-Type: multipart/form-data; boundary=boundary

--boundary
Content-Disposition: form-data; name=csv; filename=file
Content-Type: text/plain

email,firstName,lastName,authorizations,reportTypes,linkedToAllProducts,linkedToAllGroups,productsPublicId,groupsLabel,externalId
john1.doe@namirial.com,john1,doe1,[ADMINISTRATION],[ACTIVITY|EMAIL],false,false,[],[DEFAULT],ext1
john2.doe@namirial.com,john2,doe2,[VALIDATION],[ACTIVITY],true,false,[P1|P2],[DEFAULT|G2],ext2
john3.d@@@namirial.com,john3,doe3,[],[],false,true,[P1],[],ext3

Part	Description
`csv`	The .csv file

Les colonnes authorizations, productsPublicId, groupsLabel sont des listes. Le format des éléments de type liste est celui-ci :

Préfix : [
Séparateur : |
Suffix : ]

** Retour **

HTTP/1.1 200 OK
Content-Type: application/json

{
  "action" : "create",
  "usersSend" : 3,
  "usersSuccess" : 2,
  "usersError" : 1,
  "errors" : [ {
    "email" : "john3.d@@@namirial.com",
    "index" : 2,
    "reason" : "Invalid parameter 'email' format (Invalid email format)",
    "errorCode" : 1005
  } ]
}

Mise à jour des opérateurs par batch

** Requête **

Le contenu du fichier .csv doit respecter la norme RFC4180 https://tools.ietf.org/html/rfc4180, avoir une ligne de header avec toutes les colonnes ci-dessous.

L'email est la seule colonne obligatoire, toutes les colonnes vides ne seront pas modifiées.

POST /contract/management/users/update/csv HTTP/1.1
Content-Type: multipart/form-data; boundary=boundary

--boundary
Content-Disposition: form-data; name=csv; filename=file
Content-Type: text/plain

email,firstName,lastName,authorizations,reportTypes,linkedToAllProducts,linkedToAllGroups,productsPublicId,groupsLabel,externalId
john1.doe@namirial.com,john1,doe1,[VALIDATION],[ACTIVITY|EMAIL],false,false,[],[DEFAULT],ext1
john2.doe@namirial.com,john2,,,,,,,,
john3.d@@@namirial.com,john3,doe3,,[],false,true,[P1],[],ext3

Part	Description
`csv`	The .csv file

Les colonnes authorizations, productsPublicId, groupsLabel sont des listes. Le format des éléments de type liste est celui-ci :

Préfix : [
Séparateut : |
Suffix ]

** Retour **

HTTP/1.1 200 OK

{
  "action" : "update",
  "usersSend" : 3,
  "usersSuccess" : 2,
  "usersError" : 1,
  "errors" : [ {
    "email" : "john3.d@@@namirial.com",
    "index" : 2,
    "reason" : "Invalid parameter 'email' format (Invalid email format)",
    "errorCode" : 1005
  } ]
}

Suppression des opérateurs par batch

** Requête **

Le contenu du fichier .csv doit respecter la norme RFC4180 https://tools.ietf.org/html/rfc4180, avoir une ligne de header avec toutes les colonnes ci-dessous.

DELETE /contract/management/users/delete/csv HTTP/1.1
Content-Type: multipart/form-data; boundary=boundary

--boundary
Content-Disposition: form-data; name=csv; filename=file
Content-Type: text/plain

email
john1.doe@namirial.com
john2.doe@namirial.com
john3.d@@@namirial.com

Part	Description
`csv`	The .csv file

** Retour **

HTTP/1.1 200 OK

{
  "action" : "delete",
  "usersSend" : 3,
  "usersSuccess" : 2,
  "usersError" : 1,
  "errors" : [ {
    "email" : "john3.d@@@namirial.com",
    "index" : 2,
    "reason" : "Invalid parameter 'email' format (Invalid email format)",
    "errorCode" : 1005
  } ]
}