Aller au contenu

Web Services / API d'intégration Facematch V6

Prérequis

*** Prérequis à l’utilisation des web services d’intégration ***

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.

Afin de pouvoir utiliser les APIs exposées par Trust and Sign, il faut disposer d'un couple login / mot de passe. Ces informations sont fournies dans le fichier document_product.pdf envoyées par Namirial lorsqu’un produit est créé. Le login correspond à l'ID publique et le mot de passe à la clé secrète.

Les URL de base des services d’intégration sont les suivantes :

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. Les champs obligatoires seront notés (*), les autres champs seront facultatifs.

Authentification

L’authentification « Basic » est utilisée ici; elle suit la norme RFC1945. Un header HTTP nommé AUTHORIZATION doit être ajouté aux requêtes. Voir l'exemple sur l'API d'intégration.

Création d’un dossier client

** Requête **

Content-Type : multipart/form-data
POST /v6/integration/facematch

Description des “parts”

  • workflowLabel (*) : nom du parcours configuré dans l’interface d’administration des parcours. Cette chaîne doit être encodée en UTF-8 et ne pas dépasser 64 caractères;

  • externalId : identifiant externe servant à identifier (de manière unique) un dossier. Pour un même produit, deux dossiers ne pourront avoir le même externalId, sinon l'erreur 1047 sera remontée. Cette valeur ne doit pas dépasser 36 caractères ;

  • externalInfo : données additionnelles du dossier. Cette valeur doit être sous la forme d’un JSON encodé en UTF-8. Il s’agit d’une liste de clés / valeurs permettant d’ajouter des informations à un dossier. Chaque valeur doit être une chaîne de caractères encodée en UTF-8. Par exemple, l’identifiant du dossier dans le système d’information externe;

    • clef : 128 caractères maximum
    • valeur : 1023 caractères maximum
{
  "clientId":"123456789",
  "my_key":"my_value"
}
  • legalEntity : données de la personne morale sous forme d’un JSON encodé en UTF-8. Ce champ doit uniquement être présent si le parcours supporte les personnes morales. Ce JSON possède les clés
    • legalName (*) pour la raison sociale ;
    • companyId (*) pour l’identifiant (SIREN ou SIRET) de la personne morale ;
    • iban : l'iban à comparer avec le document que le participant va fournir ;
    • postalAddress : l'adresse postale
      • address1 (*) : la première ligne de l'adresse postale de la personne morale
      • address2 : la seconde ligne de l'adresse postale
      • address3 : la troisième ligne de l'adresse postale
      • city (*) : la ville de l'adresse postale Caractères autorisés : chiffres, lettres unicode, apostrophes, virgule, tirets, point et espace. Caractères non autorisés : caractères spéciaux :! @ # $ % & * ( ) _ + = { } [ ] | ; : " < > ? / symboles mathématiques : / = < > ^ % | Caractères de ponctuation, Caractères diacritiques.
      • postalCode (*) : le code postal de la ville

Liste des caractères acceptés pour le champ legalName : [a-Z][0-9]éèàùçâêûîäëïüö£!#%&'()*-./:;=?@[]^_` {|}\"€<>+\

{
  "legalName":"My company",
  "companyId":"123456789",
  "postalAddress": {
    "address1": "123 rue Vistor Hugo",
    "postalCode":"75000",
    "city":"Paris"
  }
}
  • participant : les informations du participant sous forme d’un JSON encodé en UTF-8. Les clés suivantes doivent être utilisées :
    • civility (*) : la civilité du participant (MR, MRS, MISS ou UNKNOWN) ;
    • firstName (*) : le premier prénom du participant encodé en UTF-8, contenant au maximum 64 caractères (les caractères |, /, @, ,, $ et + ne sont pas autorisés) ;
    • lastName (*) : le nom de famille du participant encodé en UTF-8, contenant au maximum 64 caractères (les caractères |, /, @, ,, $ et + ne sont pas autorisés) ;
    • email (*) : l’adresse électronique du participant encodée en UTF-8, ne dépassant pas 128 caractères et devant respecter la norme rfc2822 ;
    • mobilePhone : numéro de téléphone portable du participant (peut commencer par +33) ;
    • birthName : le nom de naissance du participant si ce dernier est différent de son nom de famille (à cause d’un mariage par exemple). Cette chaîne doit être encodée en UTF-8, contenant au maximum 64 caractères (les caractères |, /, @, ,, $ et + ne sont pas autorisés) ;
    • birthPlace : le lieu de naissance du participant, tel qu'il apparaît sur sa carte nationale d'identité. Ce champ contient le nom de la ville en majuscules (sans numéro de département ou pays, sans abbréviations ST/SAINT, etc.) ; il peut comporter un numéro d'arrondissement pour les grandes villes, séparé par un espace et suivi de la lettre E. Les autres caractères sont interdits. Exemples : PARIS, MARSEILLE 2E
    • iban : l'iban à comparer avec le document que le participant va fournir
    • postalAddress : l'adresse postale du participant
      • address1 (*) : première ligne de l’adresse postale du participant encodée en UTF-8 et ne devant pas dépasser 128 caractères. Si ce champ est donné, les champs city et postalCode devront être fournis également ;
      • address2 : seconde ligne de l’adresse postale du participant encodée en UTF-8 et ne devant pas dépasser 128 caractères.
      • address3 : troisième ligne de l’adresse postale du participant encodée en UTF-8 et ne devant pas dépasser 128 caractères.
      • city (*) : la ville postale du participant encodée en UTF-8, ne devant pas dépasser 64 caractères. Caractères autorisés : chiffres, lettres unicode, apostrophes, virgule, tirets, point et espace. Caractères non autorisés : caractères spéciaux :! @ # $ % & * ( ) _ + = { } [ ] | ; : " < > ? / symboles mathématiques : / = < > ^ % | Caractères de ponctuation, Caractères diacritiques.
      • postalCode (*) : code postal du participant encodée en UTF-8 et ne contenant que des chiffres.
      • countryCode : code pays où réside le participant encodée en UTF-8 et respectant le standard ISO3166-1.
    • phone : numéro de téléphone fixe du participant au format +33666666666 ou 0666666666.
    • birthDate : la date de naissance du participant au format YYYY-MM-JJ (ISO8601).
    • legalAgent : booléen indiquant que le participant fait partie des mandataires de la personne morale. Ce champ n'est utile que si la personne morale est activée dans le parcours
    • externalId : Identifiant externe du participant
{
  "civility":"MR",
  "firstName":"John",
  "lastName":"Doe",
  "email":"j.doe@example.com",
  "mobilePhone":"0606060606",
  "birthDate":"1970-02-12",
  "birthPlace":"MACON",
  "externalId":"idExterne",
  "postalAddress": {
    "address1": "123 rue Victor Hugo",
    "postalCode": "75000",
    "city": "Paris"
  }
}

** Retour **

Un objet JSON contenant les informations suivantes:

  • creationDate: la date de création du dossier;
  • externalInfo: JSON contenant les informations externes définies lors de la création du dossier
{
  "clientId":"123456789",
  "my_key":"my_value"
}
  • externalId : identifiant externe donné lors de la création du dossier
  • uuid : identifiant unique du dossier
  • id : identifiant du dossier
  • state : l’état du dossier (PENDING);
  • workflowLabel : le libellé du workflow utilisé pour le dossier;
  • participant: les informations du participant
    • uuid : identifiant du participant
    • accessToken : le token servant à identifier le dossier lors des appels à /api
    • civility: la civilité (MR, MRS, MISS ou UNKNOWN);
    • email : adresse email du participant;
    • birthName: le nom de naissance du participant;
    • postalAddress: adresse postale du participant. Il s’agit d’un JSON contenant les champs postalAddress1, postalAddress2, postalAddress3, postalCode, city et countryCode;
    • mobilePhone: numéro de téléphone mobile;
    • phone: numéro de téléphone fixe;
    • birthDate: la date de naissance du participant
{
  "externalInfo": {
    "my_key":"my_value"
  },
  "externalId":"myExternalId00003",
  "workflowLabel":"workflow-simple",
  "state":"PENDING",
  "id":10002,
  "creationDate":"2020-12-05T09:50:30Z",
  "uuid":"28af2a55-e815-4725-acdf-2ede49cd6933",
  "participant":{
    "uuid":"546875455-e815-4725-acd",
    "firstName":"John",
    "lastName":"Doe",
    "civility":"MR",
    "mobilePhone":"0606060606",
    "profiles":[],
    "birthDate":"1987-03-16",
    "email":"john@doe.com",
    "accessToken": "20161005_eWticz85PZRHhB8gexjWYkK77bXs0f",
    "externalId":"idExterne"
  }
}

Mise à jour des informations du participant

Les informations du participant peuvent être mises à jour. La requête doit contenir toutes les informations du participant, pas uniquement celles que l'on souhaite mettre à jour.

** Requête **

Content-Type : multipart/form-data
PUT /v6/integration/facematch/{clientFileUuid}/participant
  • clientFileUuid (*) : l’identifiant technique du dossier

Description des “parts”

  • participant : les informations du participant sous forme d’un JSON encodé en UTF-8. Les clés suivantes doivent être utilisées :
    • civility (*) : la civilité du participant (MR, MRS, MISS ou UNKNOWN);
    • firstName (*) : le premier prénom du participant encodé en UTF-8, contenant au maximum 64 caractères ;
    • lastName (*) : le nom de famille du participant encodé en UTF-8, contenant au maximum 64 caractères ;
    • email (*) : l’adresse électronique du participant encodée en UTF-8, ne dépassant pas 128 caractères et devant respecter la norme rfc2822;
    • mobilePhone : numéro de téléphone portable du participant (peut commencer par +33);
    • birthName : le nom de naissance du participant si ce dernier est différent de son nom de famille (à cause d’un mariage par exemple). Cette chaîne doit être encodée en UTF-8, contenant au maximum 64 caractères ;
    • birthPlace : le lieu de naissance du participant, tel qu'il apparaît sur sa carte nationale d'identité. Ce champ contient le nom de la ville en majuscules (sans numéro de département ou pays, sans abbréviations ST/SAINT, etc.) ; il peut comporter un numéro d'arrondissement pour les grandes villes, séparé par un espace et suivi de la lettre E. Les autres caractères sont interdits. Exemples : PARIS, MARSEILLE 2E
    • profiles : liste de profils à utiliser sous forme d’un JSONArray. Chaque valeur doit être une chaîne de caractères. A noter qu'il n'est pas possible de supprimer un profil. On peut uniquement en ajouter un ou plusieurs. La taille ne doit pas dépasser 256 caractères.
    • iban : l'iban à comparer avec le document que le participant va fournir
    • postalAddress : l'adresse postale du participant
      • address1 : première ligne de l’adresse postale du participant encodée en UTF-8 et ne devant pas dépasser 128 caractères. Si ce champ est donné, les champs city et postalCode devront être fournis également ;
      • address2 : seconde ligne de l’adresse postale du participant encodée en UTF-8 et ne devant pas dépasser 128 caractères.
      • address3 : troisième ligne de l’adresse postale du participant encodée en UTF-8 et ne devant pas dépasser 128 caractères.
      • city : la ville postale du participant encodée en UTF-8, ne devant pas dépasser 64 caractères. Caractères autorisés : chiffres, lettres unicode, apostrophes, virgule, tirets, point et espace. Caractères non autorisés : caractères spéciaux :! @ # $ % & * ( ) _ + = { } [ ] | ; : " < > ? / symboles mathématiques : / = < > ^ % | Caractères de ponctuation, Caractères diacritiques.
      • postalCode : code postal du participant encodée en UTF-8 et ne contenant que des chiffres.
      • countryCode : code pays où réside le participant encodée en UTF-8 et respectant le standard ISO3166-1.
    • phone : numéro de téléphone fixe du participant (peut commencer par +33).
    • externalId : Identifiant externe du participant
    • birthDate : la date de naissance du participant au format YYYY-MM-JJ (ISO8601).
{
  "civility":"MR",
  "firstName":"John",
  "lastName":"Doe",
  "email":"j.doe@example.com",
  "mobilePhone":"0606060606",
  "birthDate":"1970-02-12",
  "birthPlace":"MACON",
  "externalId":"idExterne",
  "postalAddress": {
    "address1": "123 rue Victor Hugo",
    "postalCode": "75000",
    "city": "Paris"
  }
}

** Retour **

aucun

Mise à jour des informations métier d'un dossier

Les informations métier peuvent être mises à jour (ajout et/ou modification) durant le cycle de vie d’un dossier. Elles ne sont plus modifiables lorsque le dossier se trouve dans un état final (accepté ou rejeté).

** Requête **

Content-Type : multipart/form-data
PUT /v6/integration/facematch/{clientFileUuid}/external-info
  • clientFileUuid (*) : l’identifiant technique du dossier

Contenu de la requête

  • externalInfo : données additionnelles du dossier. Cette valeur doit être sous la forme d’un JSON encodé en UTF-8. Il s’agit d’une liste de clés / valeurs permettant d’ajouter ou de mettre à jour des informations métiers à un dossier existant. Chaque valeur doit être une chaîne de caractères encodée en UTF-8
{
  "clientId":"123456789",
  "my_key":"my_value"
}

** Retour **

aucun

Recherche de dossiers

** Requête **

GET /v6/integration/facematch/search

Paramètres de requête

Cet appel peut retourner un grand nombre de dossiers. Pour cela nous utilisons un système de pagination (voir les paramètres "page" et "perPage").

  • page : l'index de la page à récupérer (la première page possède l'index 0). Par défaut la valeur est 0 ;

  • perPage : nombre de dossiers sur la page. Cette valeur ne doit pas dépasser 1000. Par défaut la valeur est 1000 ;

  • exported : un booléen indiquant si les dossiers exportés doivent être inclus dans le retour. Si sa valeur est true, alors seuls les dossiers exportés sont renvoyés dans la réponse. Si sa valeur est false, alors seuls les dossiers non exportés sont renvoyés. Si le paramètre est omis, alors tous les dossiers sont renvoyés ;

  • state : recherche de dossiers à partir de leur état. Pour renvoyer plusieurs états à la fois il faut utiliser autant de fois que nécessaire ce paramètre ;

  • externalId : recherche de dossiers à partir d'un identifiant externe ;

  • creationDateFrom et creationDateTo : recherche de dossiers créés dans l'intervalle de temps donné. Ces valeurs doivent être au format ISO8601 ou représenter le nombre de secondes depuis le temps epoch (01/01/1970) ;

  • participantName : recherche de dossiers à partir du nom d'un des participants. Ce paramètre gère les noms, prénoms et nom de naissances ;

  • participantEmail : recherche de dossiers à partir de l'adresse email d'un des participants ;

  • participantMobilePhone : recherche de dossiers à partir du numéro de téléphone portable d'un des participant ;

/v6/integration/facematch/search?exported=false&state=WAITING&state=SUSPENDED&page=0&perPage=500
/v6/integration/facematch/search?state=WAITING&creationDateFrom=2018-01-01T12%3A00%3A00.000Z&creationDateTo=2018-02-01T12%3A00%3A00.000Z
/v6/integration/facematch/search?state=WAITING&creationDateFrom=1526135291&creationDateTo=1528727291

** Retour **

Le retour est sous la forme d'un JSON "paginé". Les dossiers sont triés selon leur date de création (du plus ancien au plus récent). Le JSON contient les clés suivantes :

  • page : l'index de la page (comme donné en entrée du service) ;
  • perPage : le nombre de valeurs demandées dans cette page ;
  • values : la liste des uuids identifiants les dossiers clients. Pour avoir plus de détails sur les dossiers retournés, vous devrez utiliser l'appel de récupération des informations de dossiers.

Pour savoir si vous vous trouvez sur la dernière page il faut vérifier que le nombre de "values" est inférieur à "perPage".

{
  "page":0,
  "perPage":500,
  "values":[
    "2a35ed70-cc59-11e3-b644-e3907c571fd3",
    "2e45ef64-cc59-11e3-b5a0-672ab5fc322f"
  ]
}

Récupération des informations d’un dossier

Cet appel permet de récupérer les informations essentielles sur un dossier donné (nom du participant, date de création ...)

** Requête **

GET /v6/integration/facematch/{clientFileUuid}?withReport=false
  • clientFileUuid (*) : l’identifiant technique du dossier
  • withReport : inclut le report au format json si true. Valeur par défault : false

** Retour **

Un objet JSON contenant les informations suivantes :

  • creationDate : la date de création du dossier;
  • finishDate : la date de cloture du dossier (n’est présent que si le dossier est accepté ou rejeté);
  • externalInfo : JSON contenant les informations externes définies lors de la création du dossier
{
  "clientId":"123456789",
  "my_key":"my_value"
}
  • externalId : identifiant externe donné lors de la création du dossier
  • rejectionCause : la cause de rejet du dossier (n’est présent que si le dossier a été rejeté);
  • validationMessage : le message entré par un opérateur lors de l’acceptation ou du rejet du dossier;
  • state : l’état du dossier;
  • workflowLabel : le libellé du workflow utilisé pour le dossier;
  • participant: les informations du participant
    • state : l’état de chaque participant
    • accessToken : le token servant à identifier le dossier lors des appels à /api;
    • civility : la civilité (MR, MRS, MISS ou UNKNOWN);
    • email : adresse email du participant;
    • birthName : le nom de naissance du participant;
    • postalAddress : adresse postale du participant. Il s’agit d’un JSON contenant les champs postalAddress1, postalAddress2, postalAddress3, postalCode, city et countryCode;
    • mobilePhone : numéro de téléphone mobile;
    • phone : numéro de téléphone fixe ;
    • externalId : Identifiant externe du participant
    • birthDate : la date de naissance du participant
  • report : un rapport au format JSON contenant les informations de base du dossier client et la liste des pièces jointes avec leurs éventuels contrôles d’intégrité.
{
  "externalInfo": {
    "my_key":"my_value"
  },
  "externalId":"myExternalId00003",
  "workflowLabel":"workflow-simple",
  "state":"PENDING",
  "id":10002,
  "creationDate":"2016-09-05T09:50:30Z",
  "uuid":"28af2a55-e815-4725-acdf-2ede49cd6933",
  "participants":[{
    "state": "PENDING",
    "firstName":"John",
    "lastName":"Doe",
    "civility":"MR",
    "mobilePhone":"0606060606",
    "profiles":[],
    "birthDate":"1987-03-16",
    "email":"john@doe.com",
    "accessToken":"20161005_eWticz85PZRHhB8gexjWYkK77bXs0f",
    "externalId":"idExterne"
  }],
  "report": {
    ...
  }
}

Récupération de l’archive d’un dossier client

La récupération de l’archive peut se faire à n'importe quel moment.

Le fichier report.json contenu dans l’archive retournée par ce service doit être conservée dans le SI du client car il contient des informations essentielles telle que la référence de l’archivage légal.

Pour rappel : les dossiers clos (accepté ou rejeté) sont conservés 3 mois (par défaut) avant d’être anonymisé.

** Requête **

GET /v6/integration/facematch/{clientFileUuid}/archive
  • clientFileUuid (*) : l’identifiant technique du dossier

** Retour **

Le flux direct sur l’archive au format ZIP. Cette archive contient

  • les pièces justificatives fournies par le client
  • un rapport au format JSON contenant les informations de base du dossier client et la liste des pièces jointes avec leurs éventuels contrôles d’intégrité.
  • un rapport au format PDF

Indiquer qu’un dossier client a été exporté

Une fois qu’un dossier client a été traité, afin qu’il ne soit plus renvoyé dans la liste des dossiers à traiter, il faut le signaler comme exporté.

** Requête **

Content-Type : application/x-www-form-urlencoded
PUT /v6/integration/facematch/{clientFileUuid}/export
  • clientFileUuid (*) : l’identifiant technique du dossier

** Retour **

aucun

Acceptation d’un dossier client

Lorsqu’un dossier est reconnu comme valide, il faut le signaler au serveur. Cette opération ne peut être effectuée que sur les dossiers qui sont dans l’état WAITING (en attente de validation). Il s’agit d’une opération finale.

Les dossiers qui ne sont pas acceptés ne seront pas archivés.

** Requête **

Content-Type : application/x-www-form-urlencoded
POST /v6/integration/facematch/{clientFileUuid}/accept
  • clientFileUuid (*) : l’identifiant technique du dossier

Headers de requête

  • USER (*) : identifiant de l'opérateur responsable de l'acceptation (par exemple un utilisateur physique ou un utilisateur générique de type batch).

Contenu de la requête

  • message (*) : commentaire

** Retour **

aucun

Rejet d’un dossier client

Si un dossier client n’est pas valide, il peut être rejeté. Il s’agit d’une action finale.

** Requête **

Content-Type : application/x-www-form-urlencoded
POST /v6/integration/facematch/{clientFileUuid}/reject
  • clientFileUuid (*) : l’identifiant technique du dossier

Headers de requête

  • USER (*) : identifiant de l'opérateur responsable du rejet (par exemple un utilisateur physique ou un utilisateur générique de type batch).

Contenu de la requête

** Retour **

aucun

Acceptation d'une tâche

Si un document soumis est à valider, il peut être accepté.

** Requête **

Content-Type : application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/tasks/{taskId}/accept
  • clientFileUuid (*) : l’identifiant technique du dossier.
  • taskId : l'identifiant technique de la tâche Les listes des identifiants de tâches décrites dans la suite doivent être récupérées depuis le report.json, champ taskId au niveau de la liste des documents et de la liste des face-match.

Headers de requête

  • USER (*) : identifiant de l'opérateur responsable du rejet (par exemple un utilisateur physique ou un utilisateur générique de type batch).

Contenu de la requête

aucun

** Retour **

aucun

Rejet d'une tâche

Si un document soumis est à valider, il peut être rejeté avec une cause.

** Requête **

Content-Type : application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/tasks/{taskId}/reject
  • clientFileUuid (*) : l’identifiant technique du dossier.
  • taskId : l'identifiant technique de la tâche Les listes des identifiants de tâches décrites dans la suite doivent être récupérées depuis le report.json, champ taskId au niveau de la liste des documents et de la liste des face-match.

Headers de requête

  • USER (*) : identifiant de l'opérateur responsable du rejet (par exemple un utilisateur physique ou un utilisateur générique de type batch).

Contenu de la requête

** Retour **

aucun

Annulation de la validation d'une tâche

Si un document soumis est valider avec une des API accept ou rejet, cette validation peut être annulée pour être à nouveau acceptée ou rejetée.

** Requête **

Content-Type : application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/tasks/{taskId}/cancel
  • clientFileUuid (*) : l’identifiant technique du dossier.
  • taskId : l'identifiant technique de la tâche Les listes des identifiants de tâches décrites dans la suite doivent être récupérées depuis le report.json, champ taskId au niveau de la liste des documents et de la liste des face-match.

Headers de requête

  • USER (*) : identifiant de l'opérateur responsable du rejet (par exemple un utilisateur physique ou un utilisateur générique de type batch).

Contenu de la requête

aucun

** Retour **

aucun

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
  }
}