Web Services / API d'intégration 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 :

pour l’environnement d’intégration : https://integration-api.ekeynox.net/contract/v6/integration. 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/contract/v6/integration. Cet environnement est mis à jour à la même date que la production ;
pour l’environnement de production : https://api.ekeynox.net/contract/v6/integration ;

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. Ce dernier est de la forme :

AUTHORIZATION = Basic base64(login:password)

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

String header = "Basic " + Base64.getEncoder().encodeToString((login + ":" + 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=

Pour certaines requêtes, il est également nécessaire d’identifier l’utilisateur. Pour cela, un header nommé USER est utilisé et il correspond à l’identifiant d’un opérateur de Trust and Sign.

USER = 2e891756-cbbb-11e3-9d6a-57f4740d8223

Création d’un dossier client

** Requête **

Content-Type : multipart/form-data
POST /v6/integration/client-files

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;
amount : montant du dossier au format texte exemple : 123.45
documentToSign-{id} : données binaires des documents PDF qui seront signés. La valeur id correspond à l’identifiant du document défini dans Workflow. Seuls les documents à signer, ou bien tous les documents peuvent être envoyés(même ceux qui, pour des raisons d’inactivation liés aux profils ne seront in fine pas signés); dans le premier cas, la modification des profils lors d’une mise à jour du dossier n’est pas possible car certains documents pourraient manquer. Si la signature est désactivée pour ce parcours, ce champ ne doit pas être défini. Ces documents peuvent être omis lors de la création du dossier, mais dans ce cas il devront être définis avant signature à l'aide de l'appel de mise à jour des documents;
documentTemplateFields-{id} : un JSON contenant les informations pouvant être insérées dans les modèles PDF. Ces modèles sont des pdf contenant des champs de formulaires et sont insérés dans la configuration du parcours. A noter que l'utilisation de cette fonctionnalité et des champs de signature sont incompatibles. Ces documents peuvent être omis lors de la création du dossier, mais dans ce cas il devront être définis avant signature à l'aide de l'appel de mise à jour des documents. Ce JSON contient des paires clé / valeur avec clé = nom du champ dans le formulaire PDF. Les valeurs diffèrent selon le type de champ :
- texte : un simple texte (peut contenir des variables)
- checkbox : un booléen (true pour cocher / false pour décocher)
- choix (liste déroulante, groupe de bouton radio ...) : le nom du choix

{
    "name": "${signer.firstName} ${signer.lastName?upper}",
    "num_securite_sociale": "${externalInfo.numSecuriteSociale}",
    "status": "pacse",
    "recevoir_offres_promotionnelles": false
}

appendix-{id} : données binaires des fichiers annexes qui seront sauvegardés avec le reste des documents (archive et fichier de preuve). La valeur id doit être un identifiant unique contenant uniquement des caractères ASCII et des chiffre (pas d'espace). Le paramètre form-data filename est obligatoire

Exemple :

Content-Disposition: form-data; name="appendix-doc1"; filename="doc1.pdf"
Content-Type: application/pdf

données binaires

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 ;
groupLabel: Label du groupe au sein duquel le dossier doit être ajouté. Si aucune valeur n'est saisie, le dossier est ajouté au groupe par défaut. Si le label du groupe n'existe pas, l'erreur 1062 sera remontée.
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 Victor Hugo",
        "postalCode": "75000",
        "city": "Paris"
    }
}

entityStamps : les cachets (signature organisme) à appliquer sur les contrats. Ce paramètre n'est utile que si la signature est activée dans le parcours. Si ce champ n'est pas présent, tous les cachets définis dans le parcours sont appliqués ; sinon seuls ceux définis ici seront appliqués. Ce paramètre est un tableau JSON avec les clés suivantes :
- id : l'identifiant du contrat recevant le cachet (défini dans l'interface du parcours)
- visualsIds : tableau des identifiants de visuels devant être appliqués

[
    {
        "id": "contract-1",
        "visualsIds": [
            "visual-01",
            "visual-02"
        ]
    }
]

participants : les informations des participants sous forme d’un tableau de JSON encodé en UTF-8. Les clés suivantes doivent être utilisées :
- type (*) : permet d'identifier un participant comme configuré dans l'interface de configuration des parcours ;
- state : l’état de chaque participant
- 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 (toutes les lettres des différents alphabets ainsi que les chiffres et jointures sont acceptés, les caractères spéciaux ne sont pas autorisés) ;
- lastName (*) : le nom de famille du participant encodé en UTF-8, contenant au maximum 64 caractères (toutes les lettres des différents alphabets ainsi que les chiffres et jointures sont acceptés, les caractères spéciaux 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). Si la signature est présente dans le parcours, ce champ devient obligatoire. Le dossier ne sera pas créé si le format du téléphone n'est pas valide ; le format suit la norme E164 (+336XXXXXXXX), si le format est local (06XXXXXXXX), nous calculerons la région de France éligible (non recommandé). Hors numéro français, seul le format E164 est accepté. Il est impératif que le format E164 commence bien par un + ;
- 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 (toutes les lettres des différents alphabets ainsi que les chiffres et jointures sont acceptés, les caractères spéciaux 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
- profiles : liste de profils à utiliser sous forme d’un JSONArray. Chaque valeur doit être une chaîne de caractères. La taille de ce champ 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 signataire 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 signataire encodée en UTF-8 et ne devant pas dépasser 128 caractères.
  - address3 : troisième ligne de l’adresse postale du signataire encodée en UTF-8 et ne devant pas dépasser 128 caractères.
  - city (*) : la ville postale du signataire 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 signataire encodée en UTF-8 et ne contenant que des chiffres.
  - countryCode : code pays où réside le signataire encodée en UTF-8 et respectant le standard ISO3166-1.
- phone : numéro de téléphone fixe du signataire au format +33666666666 ou 0666666666. Le format suit la norme E164 ( +336XXXXXXXX), si le format est local (06XXXXXXXX), nous calculerons la région de France éligible (non recommandé). Hors numéro français, seul le format E164 est accepté. Il est impératif que le format E164 commence bien par un + ;
- birthDate : la date de naissance du signataire au format YYYY-MM-JJ (ISO8601).
- signatures : la liste des documents que le participant doit signer (Ce paramètre est déprécié depuis la version 21.2 et il est conseillé d'utiliser les paramètres documentsToSign et documentsToVisualize) :
  - documentToSignId (*) : l'identifiant du document à signer (comme défini dans l'interface de configuration du parcours)
  - visualIds (*) : les identifiants des visuels de signature à utiliser dans le document. Si le tableau est vide, le contrat ne sera pas signé (uniqument visualisé par l'utilisateur). Il faudra qu'au moins un des contrat défini possède un lien vers un visuel
- documentsToSign : la liste des documents que le participant doit signer
  - id (*) l'identifiant du document à signer (comme défini dans l'interface de configuration du parcours)
  - visualIds (*) : les identifiants des visuels de signature à utiliser dans le document. Si ce tableau n'est pas présent ou s'il est vide alors une signature sans visuel sera appliquée. Il faudra qu'au moins un des contrat défini possède un lien vers un visuel
- documentsToVisualize : la liste des documents qui seront visualisés, mais non signés par le participant (pas de signature)
  - id (*) l'identifiant du document à visualiser (comme défini dans l'interface de configuration du parcours)
- 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
- oneccToken : Token One Click Contract du dossier de référence du participant
- externalId : Identifiant externe du participant

[
    {
        "type": "signer",
        "state": "PENDING",
        "civility": "MR",
        "firstName": "John",
        "lastName": "Doe",
        "email": "j.doe@example.com",
        "mobilePhone": "+33606060606",
        "birthDate": "1970-02-12",
        "birthPlace": "MACON",
        "oneccToken": "20190920_eWticz85PZRHhB8gexjWYkK77bXs0f",
        "externalId": "idExterne",
        "postalAddress": {
            "address1": "123 rue Victor Hugo",
            "postalCode": "75000",
            "city": "Paris"
        },
        "documentsToSign": [
            {
                "id": "my-contract3",
                "visualIds": [
                    "visual-01",
                    "visual-02"
                ]
            }
        ],
        "documentsToVisualize": [
            {
                "id": "my-contract4"
            }
        ]
    }
]

** 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 du dossier
state: l’état du dossier (INITIALIZED ou PENDING);
workflowLabel: le libellé du workflow utilisé pour le dossier;
archivingState: l'état d'archivage du dossier. Les valeurs suivantes sont possibles :
- NO_ARCHIVING: l'archivage n'est pas activé pour ce dossier
- ARCHIVED: le dossier a été archivé
- NOT_YET_ARCHIVED: le dossier n'est pas encore archivé
- ARCHIVING_IS_SCHEDULED: le dossier n'est pas encore archivé, l'archivage est programmé
- NOT_ARCHIVED: le dossier n'a pas été archivé car il a été rejeté ou le délai d'archivage a été dépassé
participants: les informations des participants sous forme d'un tableau de JSON
- uuid: identifiant du participant
- accessToken: le token servant à identifier le dossier lors des appels à /api
- type: le type du participant comme défini dans l'interface de configuration du parcours;
- civility: la civilité (MR, MRS, MISS ou UNKNOWN);
- email: adresse email du signataire;
- birthName: le nom de naissance du signataire;
- postalAddress: adresse postale du signataire. Il s’agit d’un JSON contenant les champs postalAddress1, postalAddress2, postalAddress3, postalCode, city et countryCode;
- mobilePhone: numéro de téléphone mobile. Le format suit la norme E164 (+336XXXXXXXX), si le format est local (06XXXXXXXX), nous calculerons la région de France éligible (non recommandé). Hors numéro français, seul le format E164 est accepté. Il est impératif que le format E164 commence bien par un + ;
- phone: numéro de téléphone fixe. Le format suit la norme E164 (+336XXXXXXXX), si le format est local (06XXXXXXXX), nous calculerons la région de France éligible (non recommandé). Hors numéro français, seul le format E164 est accepté. Il est impératif que le format E164 commence bien par un + ;
- birthDate: la date de naissance du signataire;
- downloadDocumentsBeforeSignature: Tous les documents avant signature ont été téléchargés (absent si Forcer le téléchargement des documents avant signature = Non)
- downloadSignedDocuments : Tous les documents signés ont été téléchargés (absent si Forcer le téléchargement des documents après signature = Non)
signDocuments : la liste des document pouvant être signés
- id: l'identifiant unique du contrat (défini dans l'interface de configuration du parcours). Le document pourra être téléchargé grâce à cet identifiant ;
- label: le nom du document
group: le groupe du dossier
- uuid: identifiant du groupe
- label: label du groupe
- defaultGroup: true si il s'agit du groupe par défaut de la compagnie

{
    "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",
    "recoverableDocumentTypes": [
        "ID_CARD"
    ],
    "participants": [
        {
            "uuid": "546875455-e815-4725-acd",
            "type": "signer",
            "firstName": "John",
            "lastName": "Doe",
            "civility": "MR",
            "mobilePhone": "+33606060606",
            "profiles": [
                "single",
                "otherprofile"
            ],
            "birthDate": "1987-03-16",
            "email": "john@doe.com",
            "accessToken": "20161005_eWticz85PZRHhB8gexjWYkK77bXs0f",
            "externalId": "idExterne",
            "downloadDocumentsBeforeSignature": true,
            "downloadSignedDocuments": false
        }
    ],
    "signDocuments": [
        {
            "id": "contract",
            "label": "Mon contrat"
        }
    ],
    "group": {
        "uuid": "8cb80ab2-a689-4568-ab85-07c33203842b",
        "label": "DEFAULT",
        "defaultGroup": "true"
    }
}

Mise à jour des informations d'un participant

Les informations d'un participant peuvent être mises à jour. La requête doit contenir toutes les informations du participant, pas uniquement celles que l'on souhaite mettre à jour. Les dossiers signés ne peuvent plus être modifiés.

Attention Si vous avez soumis des documents avant signature, et que des erreurs de cohérence sont remontées, ces contrôles resteront en erreur.

Attention Le type de participant ne peut être modifié.

** Requête **

Content-Type : multipart/form-data
PUT /v6/integration/client-files/{clientFileUuid}/participants/{participantUuid}

clientFileUuid (*): l’identifiant technique du dossier
participantUuid (*): l’identifiant technique du participant à mettre à jour. Il peut être récupéré depuis l'appel de création du dossier ou depuis l'appel de récupération des informations d'un 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:
- type (*) : permet d'identifier un participant : identifiant définit dans l'interface de configuration des parcours (cette information ne peut être modifiée) ;
- 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). Si la signature est présente dans le parcours, ce champ devient obligatoire ; le format suit la norme E164 (+336XXXXXXXX), si le format est local (06XXXXXXXX), nous calculerons la région de France éligible (non recommandé). Hors numéro français, seul le format E164 est accepté. Il est impératif que le format E164 commence bien par un + ;
- 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. La taille de ce champ ne doit pas dépasser 256 caractères. Si le participant a déjà effectué la signature de ses contrats, il n'est plus possible de modifier les profils. A noter qu'il n'est pas possible de supprimer un profil, hormis si ce dernier est associé à une ou plusieurs clauses de consentement. Les autres types de profils ne peuvent qu'être ajoutés. Il est conseillé de ne pas ajouter de profil à un participant lorsque le dossier est dans l'état à valider, à débloquer, accepté ou rejeté.
- 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 signataire 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 signataire encodée en UTF-8 et ne devant pas dépasser 128 caractères.
  - address3: troisième ligne de l’adresse postale du signataire encodée en UTF-8 et ne devant pas dépasser 128 caractères.
  - city: la ville postale du signataire 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 signataire encodée en UTF-8 et ne contenant que des chiffres.
  - countryCode: code pays où réside le signataire encodée en UTF-8 et respectant le standard ISO3166-1.
- phone: numéro de téléphone fixe du signataire (peut commencer par +33). Le format suit la norme E164 (+336XXXXXXXX), si le format est local (06XXXXXXXX), nous calculerons la région de France éligible (non recommandé). Hors numéro français, seul le format E164 est accepté. Il est impératif que le format E164 commence bien par un + ;
- externalId: Identifiant externe du participant
- birthDate: la date de naissance du signataire au format YYYY-MM-JJ (ISO8601).
- signatures: la liste des documents que le participant doit signer :
  - documentToSignId: l'identifiant du document à signer (comme défini dans l'interface de configuration du parcours)
  - visualIds: les identifiants des visuels de signature à utiliser dans le document. Si le tableau est vide, le contrat ne sera pas signé (uniqument visualisé par l'utilisateur). Il faudra qu'au moins un des contrat défini possède un lien vers un visuel

{
    "type": "signer",
    "civility": "MR",
    "firstName": "John",
    "lastName": "Doe",
    "email": "j.doe@example.com",
    "mobilePhone": "+33606060606",
    "birthDate": "1970-02-12",
    "birthPlace": "MACON",
    "externalId": "idExterne",
    "postalAddress": {
        "address1": "123 rue Victor Hugo",
        "postalCode": "75000",
        "city": "Paris"
    },
    "signatures": [
        {
            "documentToSignId": "my-contract",
            "visualIds": [
                "visual-01"
            ]
        }
    ]
}

** 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é).

Lors d’un appel à l’API de mise à jour, toutes les informations métier doivent être incluses dans le corps de la requête, y compris celles qui ne sont pas modifiées. En effet, tout champ omis sera automatiquement réinitialisé à une chaîne vide.

ATTENTION : Pour éviter toute perte de données, veillez à toujours transmettre un payload complet contenant l’ensemble des valeurs métier, même celles qui ne changent pas.

** Requête **

Content-Type: multipart/form-data
PUT /v6/integration/client-files/{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

Mise à jour des documents à signer

Les documents à signer ne peuvent être mis à jour qu'avant la signature. Il est uniquement possible de modifier les documents ajoutés lors de la création du dossier.

** Requête**

Content-Type : multipart/form-data
PUT /v6/integration/client-files/{clientFileUuid}/sign-documents

clientFileUuid (*): l’identifiant technique du dossier récupéré lors de sa création

Contenu de la requête

documentToSign-{id} (*): données binaires des documents PDF qui seront signés. La valeur id correspond à l’identifiant du document défini dans Workflow. Seuls les documents à signer, ou bien tous les documents peuvent être envoyés(même ceux qui, pour des raisons d’inactivation liés aux profils ne seront in fine pas signés); dans le premier cas, la modification des profils lors d’une mise à jour du dossier n’est pas possible car certains documents pourraient manquer. Si la signature est désactivée pour ce parcours, ce champ ne doit pas être défini.
documentTemplateFields-{id}: un JSON contenant les informations pouvant être insérées dans les modèles PDF. Ce JSON contient des paires clé / valeur avec clé = nom du champ dans le formulaire PDF. Les valeurs diffèrent selon le type de champ :
- texte : un simple texte (peut contenir des variables)
- checkbox: un booléen (true pour cocher / false pour décocher)
- choix (liste déroulante, groupe de bouton radio ...) : le nom du choix

** Retour **

aucun

Mise à jour des documents annexes

Les documents annexes peuvent être mises à jour (ajout et/ou modification) durant le cycle de vie d’un dossier. Ils 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/client-files/{clientFileUuid}/appendices

clientFileUuid (*): l’identifiant technique du dossier récupéré lors de sa création

Contenu de la requête

appendix-{id}: données binaires des fichiers annexes qui seront sauvegardés avec le reste des documents (archive et fichier de preuve). Le paramètre form-data filename est obligatoire

Exemple :

Content-Disposition: form-data; name="appendix-doc1"; filename="doc1.pdf"
Content-Type: application/pdf

données binaires

** Retour **

aucun

Mise à jour du groupe

Le groupe peut être mise à jour durant tout le cycle de vie d’un dossier.

** Requête **

PUT /v6/integration/client-files/{clientFileUuid}/group/{groupLabel}

clientFileUuid (*): l’identifiant technique du dossier récupéré lors de sa création
groupLabel (*): label du nouveau groupe

Contenu de la requête

vide

** Retour **

aucun

Recherche de dossiers

** Requête **

GET /v6/integration/client-files/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/client-files/search?exported=false&state=WAITING&state=SUSPENDED&page=0&perPage=500
/v6/integration/client-files/search?state=WAITING&creationDateFrom=2018-01-01T12%3A00%3A00.000Z&creationDateTo=2018-02-01T12%3A00%3A00.000Z
/v6/integration/client-files/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 des signataires, date de création…)

** Requête **

GET /v6/integration/client-files/{clientFileUuid}?withReport=false

clientFileUuid (*): l’identifiant technique du dossier
withReport: inclus le rapport 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 ;
archivingState: l'état d'archivage du dossier. Les valeurs suivantes sont possibles :
- NO_ARCHIVING: l'archivage n'est pas activé pour ce dossier
- ARCHIVED: le dossier a été archivé
- NOT_YET_ARCHIVED: le dossier n'est pas encore archivé
- NOT_ARCHIVED: le dossier n'a pas été archivé car il a été rejeté ou le délai d'archivage a été dépassé
participants: les informations des participants sous forme d'un tableau de JSON
- type: le type du participant comme défini dans l'interface de configuration du parcours ;
- 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 signataire;
- birthName: le nom de naissance du signataire;
- postalAddress: adresse postale du signataire. Il s’agit d’un JSON contenant les champs postalAddress1, postalAddress2, postalAddress3, postalCode, city et countryCode;
- mobilePhone: numéro de téléphone mobile. Le format suit la norme E164 (+336XXXXXXXX), si le format est local (06XXXXXXXX), nous calculerons la région de France éligible (non recommandé). Hors numéro français, seul le format E164 est accepté. Il est impératif que le format E164 commence bien par un + ; ;
- phone: numéro de téléphone fixe. Le format suit la norme E164 (+336XXXXXXXX), si le format est local (06XXXXXXXX), nous calculerons la région de France éligible (non recommandé). Hors numéro français, seul le format E164 est accepté. Il est impératif que le format E164 commence bien par un + ; ;
- externalId: Identifiant externe du participant
- birthDate: la date de naissance du signataire
- downloadDocumentsBeforeSignature: Tous les documents avant signature ont été téléchargés (absent si Forcer le téléchargement des documents avant signature = Non)
- downloadSignedDocuments: Tous les documents signés ont été téléchargés (absent si Forcer le téléchargement des documents après signature = Non)
- documentToSign: Liste des documents qui seront signés par le participant.
  - id: Id du document
  - participantVisualIds: Id des visuels qui seront signés par la participant
  - entityStampVisualIds: Id des visuels organisme du contrat
- documentToVisualize: Liste des documents qui seront visualisés par le participant
  - id: Id du document
signDocuments: la liste des document pouvant être signés
- id: l'identifiant unique du contrat (défini dans l'interface de configuration du parcours). Le document pourra être téléchargé grâce à cet identifiant ;
- label: le nom du document
updatable: booléen indiquant si les informations du dossier peuvent être mise à jour (noms des participants, mise à jour d'un contrat ...)
group: le group du dossier
- uuid: identifiant du groupe
- label: label du groupe
- defaultGroup: true si il s'agit du groupe par défaut de la compagnie
amount: le montant du dossier
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",
    "updatable": true,
    "participants": [
        {
            "type": "signer",
            "state": "PENDING",
            "firstName": "John",
            "lastName": "Doe",
            "civility": "MR",
            "mobilePhone": "+33606060606",
            "profiles": [],
            "birthDate": "1987-03-16",
            "email": "john@doe.com",
            "accessToken": "20161005_eWticz85PZRHhB8gexjWYkK77bXs0f",
            "externalId": "idExterne",
            "downloadDocumentsBeforeSignature": true,
            "downloadSignedDocuments": false,
            "documentToSign": [
                {
                    "id": "contract",
                    "participantVisualIds": [
                        "visual-1"
                    ],
                    "entityStampVisualIds": [
                        "visual-11"
                    ]
                }
            ],
            "documentToVisualize": [
                {
                    "id": "contract_2"
                }
            ]
        }
    ],
    "signDocuments": [
        {
            "id": "contract",
            "label": "Mon contrat"
        }
    ],
    "group": {
        "uuid": "8cb80ab2-a689-4568-ab85-07c33203842b",
        "label": "DEFAULT",
        "defaultGroup": "true"
    },
    "report": {
        ...
    }
}

Récupération d'un document à signer

** Requête **

GET /v6/integration/client-files/{clientFileUuid}/sign-documents/{documentId}

clientFileUuid (*): l’identifiant technique du dossier
documentId (*): l’identifiant du document à télécharger. Cet identifiant peut être récupéré depuis l'appel de récupération des informations d'un dossier

** Retour **

Le flux binaire du document.

Récupération d'un fichier soumis

** Requête **

GET /v6/integration/client-files/{clientFileUuid}/files/{fileId}

clientFileUuid (*): l’identifiant technique du dossier
fileId (*): l’identifiant du fichier à télécharger.

** Retour **

Le flux binaire du document.

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/client-files/{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
les éventuels documents annexe
Les documents pouvant être signés
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

Récupération du fichier de preuve

Ce fichier provient du tiers de confiance. Il contient le contrat signé et les documents soumis par l'utilisateur. Uniquement pour les dossiers acceptés.

** Requête **

GET /v6/integration/client-files/{clientFileUuid}/proof-file

clientFileUuid (*) : l’identifiant technique du dossier

** Retour **

Le flux du dossier de preuve contient :

Dans le cas de Docusign un fichier au format docx
Dans le cas de Namirial un fichier au format 7zip

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/client-files/{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 acceptation déclenchera l’archivage légal du dossier si la signature est activée dans le parcours du dossier. 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 : multipart/form-data
POST /v6/integration/client-files/{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

Archivage d'un dossier

Si l'archivage "retardé" est activé sur un dossier, il peut être déclenché par cet appel.

Ceci ne fonctionne que sur les dossiers acceptés et qui ont l'état d'archivage NOT_YET_ARCHIVED (voir l'API de récupération des informations de dossier).

** Requête **

Content-Type : application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/archive

clientFileUuid (*): l’identifiant technique du dossier

Headers de requête

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

Contenu de la requête

aucun

** Retour **

aucun

Annulation de l'archivage d'un dossier

Si l'archivage "retardé" est activé sur un dossier, il peut être annulé par cet appel.

Ceci ne fonctionne que sur les dossiers acceptés et qui ont l'état d'archivage NOT_YET_ARCHIVED (voir l'API de récupération des informations de dossier).

** Requête **

Content-Type : application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/archive/cancel

clientFileUuid (*) : l’identifiant technique du dossier

Headers de requête

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

Contenu de la requête

aucun

** Retour **

aucun

Rejet d’un dossier client

Si un dossier client n’est pas valide (cf causes ci-dessous), il peut être rejeté. Cela évitera notamment l’archivage légal. Il s’agit d’une action finale.

** Requête **

Content-Type : multipart/form-data
POST /v6/integration/client-files/{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

message: la description du rejet;
cause: la cause de rejet ;

** Retour **

aucun

Déblocage d'un dossier client

Si un dossier se trouve dans l'état SUSPENDED, il peut être débloqué par cet appel. Pour avoir plus de détails sur les tâches qui ont provoqué ce blocage, il faut lire le fichier report.json.

** Requête **

Content-Type : multipart/form-data
POST /v6/integration/client-files/{clientFileUuid}/unblock

clientFileUuid (*) : l’identifiant technique du dossier

Headers de requête

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

Paramêtres de la requête

message: un commentaire.

** Retour **

aucun

Réouverture d'un dossier client

La réouverture peut être faite lorsque le dossier se trouve soit dans l'état WAITING (après finalisation de l'utilisateur), soit dans l'état SUSPENDED.

Lors d'une réouverture, il est possible d'accepter certaines soumissions, d'en rejeter d'autres, et de demander des documents supplémentaires.

Il est également possible de réouvrir un dossier pour signature : dans ce cas tous les participants devront signer à nouveau ; les nouveaux documents à signer doivent être fournis dans la requête multi-part, de la même façon qu'à la création du dossier.

Contrainte lors la réouverture d'une tâche de soumission de document qui précède une tâche de reconnaissance faciale : dans ce cas il n'est pas possible de redemander la resoumission du document seul, il est nécessaire de réouvrir les deux tâches liées (document + face match). Il est possible en revanche de redemander uniquement l'identification faciale.

La réouverture d'une tâche d'identité du participant entraine la réouverture des signatures des tous les participants si un participant a déjà réalisé sa signature.

Un dossier signalé comme "exporté" puis réouvert, apparaitra de nouveau dans la liste des dossiers non exportés (suppression automatique du flag "exporté").

** Requête **

Content-Type : multipart/form-data
POST /v6/integration/client-files/{clientFileUuid}/reopen

clientFileUuid (*): l’identifiant technique du dossier

Headers de requête

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

Contenu de la requête

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. Pour redemander une signature, spécifier les identifiants des tâches de signature dans le tableau des événements (tâches de "type": "SIGNATURE", champ taskId).

La valeur de ces identifiants est dynamique et susceptible de changement.

reopenedTasks (*): liste des tâches de document et de reconnaissances faciales devant être réouvertes (dans un JSONArray). Cf. ci-dessus sur comment déterminer ces identifiants techniques.
acceptedTasks: liste des tâches acceptées et ne devant pas être réouvertes (dans un JSONArray). Ces identifiants doivent être récupérés depuis le report.json (clé taskId)
message: un commentaire
extraDocuments: liste des documents additionnels à ajouter au dossier. Ce champ ne doit être présent que pour les dossiers dans l'état WAITING. Chaque entrée doit contenir les champs owner (uuid du participant), description (une description du document) et label (identifiant du document)

[
    {
        "owner": "06ef3650-c999-4c30-a538-b771fbcc807d",
        "description": "Document additionnel",
        "label": "extra document"
    }
]

documentToSign-{id} : nouveaux contrats à signer, si les tâches de signature ont été re-ouvertes.
documentTemplateFields-{id} : nouvelles informations des modèles PDF, si les tâches de signature ont été re-ouvertes.

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

cause : la cause de rejet

** Retour **

aucun

Annulation de la validation d'une tâche

Si un document soumis est validé 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

Soumission d'un document

Les pièces justificatives peuvent être envoyées via cet API. Le dossier devra se trouver dans l'état PENDING (en cours).

** Requête **

Content-Type: multipart/form-data
POST /v6/integration/client-files/{clientFileUuid}/documents/{attachmentId}

clientFileUuid (*): l’identifiant technique du dossier
attachmentId (*): l'identifiant du document comme défini dans le champ "Identifiant" de l'interface de configuration du parcours (onglet "Justificatifs")

Contenu de la requête

participantUuid (*): l'identifiant du participant qui soumet le document
documentId (*): l'identifiant du document. Pour les documents présents dans la liste des types de documents supportés, sa valeur doit être le nom du type. Par exemple, "ID_CARD"pour une carte d'identité. Pour les documents de type générique, il est visible dans l'interface de configuration du parcours ( onglet "Justificatifs"), par exemple la valeur peut être "generic_1".
documentType (*): le type du document soumis lors de cet appel. Ceci est utile quand une tâche de soumission accepte plusieurs types. Ce paramètre est déprécié ; il est préférable d'utiliser le paramètre " documentId".
file-{x} (*): les donnée binaire du document à soumettre. La valeur {x} doit être remplacée par un index incrémental débutant à la valeur 1. Elle sert à soumettre plusieurs fichiers pour un même document. Par exemple pour un scan de trois pages dont chacune est au format JPEG il faudra envoyer les paramètres file-1, file-2 et file-3.

** Retour **

Si l'aide à la décision n'est pas activée, le service ne retourne aucune donnée (HTTP/204). Dans l'autre cas les données extraites et les contrôles seront retournés :

documentType: le type du document détecté
documentDetails: les données extraites du document
- holder: les informations du possesseur du document (nom, prénom, date de naissance ...)
- document: les informations du document (date, mots clés ...)
controlsGroups: les contrôles effectués sur le document avec leur status (OK=aucun problème, KO=un problème détecté, SKIPPED=contrôle non effectué). Ils sont regroupés dans le catégories suivantes :
- document: contrôles liés aux informations document (peut contenir la vérification d'un contrôle externe comme DocVérif)
- documentAspect: contrôles liés à l'apparence du document
- documentHolder: contrôles liés au possesseur du document
- legalEntity: contrôles liés à la personne morale
- externalData: contrôles entre les informations du document et une source externe (ex: site des impôts)
pages : Liste des informations des pages
- skewAngle : Orientation de la page
remainingTries: le nombre de tentatives restantes pour cette soumission de document
errors : liste des erreurs remontées lors du traitment du document
keysWithError : liste des clés dans les controlsGroups qui sont en erreur. Ce champ est de la forme "{groupe}.{control}" ( ex: "documentHolder.fullNameFound")

Le retour diffère selon le type de document :

RIB

La clé documentDetails/document/iban contient la valeur de l'IBAN lue sur le document. La clé documentDetails/document/bicCode contient la valeur du code BIC.

Les contrôles suivants peuvent être effectués sur le document :

Nom du contrôle	Description
typeRecognized	le système a reconnu le type du document
ibanFound	un IBAN a été trouvé dans le document
bicCodeFound	le code BIC a été trouvé dans le document
ibanFormatValid	le format de l'IBAN est correct
ibanMatch	la valeur extraite de l'IBAN correspond à celle du dossier. Si aucun IBAN n'a été défini lors de la création du dossier, ce contrôle aura toujours la valeur SKIPPED
ibanBankCountryValid	le pays de l'IBAN est autorisé. Si tous les pays ont été autorisés depuis l'interface d'administration de Trust and Sign, ce contrôle aura toujours la valeur SKIPPED
fullNameFound	le nom du participant a été trouvé dans le document

{
    "documentType": "RIB",
    "documentDetails": {
        "document": {
            "iban": "FR7000000000000000000000000",
            "bicCode": "CEPAFRPP348"
        },
        "holder": {
            "lastName": "DOE",
            "firstNames": [
                "JOHN"
            ]
        }
    },
    "controlsGroups": {
        "document": {
            "typeRecognized": "OK",
            "ibanFound": "OK",
            "bicCodeFound": "OK",
            "ibanChecksumValid": "OK",
            "ibanMatch": "SKIPPED",
            "ibanBankCountryValid": "SKIPPED"
        },
        "documentHolder": {
            "fullNameFound": "OK"
        }
    }
}

Fiche de paie

La valeur nir contient le numéro de sécurité sociale du pssesseur de la fiche de paie.

Les contrôles suivant peuvent être effectués sur le document:

Nom du contrôle	Description
typeRecognized	le système a reconnu le type du document
dateFound	la date d'émission de la fiche de paie a été trouvée
maxAgeNotExceeded	la date d'émission du document n'excède pas la date maximale définie dans l'interface d'administration de Trust and Sign
fullNameFound	le nom du participant a été trouvé dans le document
postalAddressFound	une adresse postale a été trouvée dans le document. Si l'adresse n'a pas été définie lors de la création du dossier, ce contrôle aura toujours la valeur SKIPPED
postalAddressMatch	l'adresse postale trouvée correspond à celle du participant. Si l'adresse n'a pas été définie lors de la création du dossier, ce contrôle aura toujours la valeur SKIPPED
legalEntityAlive	indique si l'entreprise (dont le SIRET est présent sur la fiche de paie) est toujours active
legalEntityIdExists	indique si l'entreprise (dont le SIRET est présent sur la fiche de paie) existe
legalEntityOfficeIdExists	indique si l'établissement de l'entreprise (dont le SIRET est présent sur la fiche de paie) existe ou a existé par le passé
legalEntityOfficeAlive	indique si l'établissement de l'entreprise (dont le SIRET est présent sur la fiche de paie) est encore ouvert

{
    "documentType": "PAYSLIP",
    "documentDetails": {
        "document": {
            "nir": "000000000000000",
            "legalEntityOfficeId": "00000000000000",
            "periodDate": "2015-06-01",
            "annualNetTaxableIncome": 25054.29,
            "monthlyNetTaxableIncome": 25054.29,
            "legalEntityAddress": "123 rue Victor Hugo"
        },
        "holder": {
            "lastName": "DOE",
            "firstNames": [
                "JOHN"
            ]
        }
    },
    "controlsGroups": {
        "document": {
            "typeRecognized": "OK",
            "dateFound": "OK",
            "maxAgeNotExceeded": "OK"
        },
        "documentHolder": {
            "fullNameFound": "OK",
            "postalAddressFound": "SKIPPED",
            "postalAddressMatch": "SKIPPED"
        },
        "legalEntity": {
            "legalEntityAlive": "OK",
            "legalEntityIdExists": "OK",
            "legalEntityOfficeIdExists": "OK",
            "legalEntityOfficeAlive": "OK"
        }
    }
}

Avis d'imposition

Attention, suite à l'arrêt de service du site des impôts, un certains nombre de ces contôles sont dépréciés. Ces derniers peuvent être remplacés par les informations extraites du doc2D présent sur le document.

Les contrôles suivant peuvent être effectués sur le document:

Nom du contrôle	Description
typeRecognized	le système a reconnu le type du document
dateFound	la date d'émission de l'avis d'impôt a été trouvée
maxAgeNotExceeded	la date d'émission du document n'excède pas la date maximale définie dans l'interface d'administration de Trust and Sign
fullNameFound	le nom du participant a été trouvé dans le document et correspond avec le nom sur le dossier
postalAddressFound	une adresse postale a été trouvée dans le document et elle correspond à celle présente sur le dossier. Si l'adresse n'a pas été définie lors de la création du dossier, ce contrôle aura toujours la valeur SKIPPED
fullNameMatch (nouveau)	le nom dans le doc2D correspond avec le nom du participant sur le dossier
taxNoticeReferenceFound (nouveau)	la référence de l'avis d'impôt a été trouvée sur le document
fiscalNumberFound (nouveau)	au moins un numéro fiscal a été trouvé sur le document
doc2DFound (nouveau)	le doc2D existe et a été trouvé sur le document, certains avis d'impôts n'ont pas de doc2D
doc2DValid (nouveau)	le doc2D sur le document est valide
doc2DAndDocumentMatch (nouveau)	tous les contrôles entre le document et le doc2D sont OK (résultat de l'ensemble des contrôle suivants : doc2DAndDocumentTypeMatch, doc2DAndFullName1Match, doc2DAndFullName2Match, doc2DAndReferenceIncomeMatch et doc2DAndIncomeYearMatch. Ce contrôle aura la valeur SKIPPED si le contrôle doc2DFound n'a pas la valeur OK
doc2DAndDocumentTypeMatch (nouveau)	le type de document détecté par le system correspond au type de document présent dans le doc2D. Ce contrôle aura la valeur SKIPPED si le contrôle doc2DFound n'a pas la valeur OK
doc2DAndFullName1Match (nouveau)	le nom du premier déclarant correspond entre le document et le doc2D. Ce contrôle aura la valeur SKIPPED si le contrôle doc2DFound n'a pas la valeur OK
doc2DAndFullName2Match (nouveau)	le nom du second déclarant correspond entre le document et le doc2D. Ce contrôle aura la valeur SKIPPED si le contrôle doc2DFound n'a pas la valeur OK
doc2DAndReferenceIncomeMatch (nouveau)	le revenu fiscal de référence correspond entre le document et le doc2D. Ce contrôle aura la valeur SKIPPED si le contrôle doc2DFound n'a pas la valeur OK
doc2DAndIncomeYearMatch (nouveau)	l'année pour laquelle les impôts sur les revenus sont calculés trouvé sur le document correspond avec l'année détectée dans le doc2D. Ce contrôle aura la valeur SKIPPED si le contrôle doc2DFound n'a pas la valeur OK
~~postalAddressMatch~~ (déprécié)	l'adresse postale trouvée correspond à celle du participant. Si l'adresse n'a pas été définie lors de la création du dossier, ce contrôle aura toujours la valeur SKIPPED (ce contrôle n'est disponible que dans le groupe "externalData")
~~issuanceDateMatch~~ (déprécié)	la date d'émission de l'avis correspond à la date depuis le site des impôts
~~checkable~~ (déprécié)	le document est vérifiable car toujours présent sur le site des impôts (un avis est disponible deux ans)
~~fullNameMatch~~ (déprécié)	le nom du participant correspond entre le dossier et le site des impôts
~~identifiersExist~~ (déprécié)	les identifiants de l'avis d'impôts existe sur le site des impôts
~~refIncomeMatch~~ (déprécié)	le montant des revenus trouvé dans le document correspond à celui retourné par le site des impôts

Nouveau payload de retour basé sur les informations extraites du doc2D présent sur le document.

{
    "documentType": "TAX_NOTICE",
    "documentDetails": {
        "document": {
            "issuanceDate": "2016-04-24",
            "fiscalNumber1": "0000000000000C",
            "fiscalNumber2": "1000000000000C",
            "reference": "0000000000000",
            "refIncome": "15000",
            "incomeYear": 2021,
            "doc2D": {
                "documentType": "TAX_NOTICE",
                "signedBy": "C=COUNTRYCODE, O=ORGANISM, OU=0000 00000000000000, CN=0000",
                "signatureDate": "2016-04-24",
                "fullName1": "DOE JOHN JAMES",
                "fiscalNumber1": "0000000000000C",
                "fiscalNumber2": "1000000000000C",
                "taxNoticeReference": "0000000000000",
                "referenceIncome": 15000,
                "partsCount": 1,
                "incomeYear": 2021,
                "assessmentDate": "2016-04-24"
            }
        },
        "holder": {
            "firstName": "JOHN",
            "firstNames": [
                "JOHN"
            ],
            "lastName": "DOE",
            "rawAddress": "ADDRESS1 POSTALCODE CITY"
        }
    },
    "controlsGroups": {
        "document": {
            "dateFound": "OK",
            "maxAgeNotExceeded": "OK",
            "typeRecognized": "OK",
            "doc2DFound": "OK",
            "doc2DValid": "OK",
            "doc2DAndDocumentMatch": "OK",
            "taxNoticeReferenceFound": "OK",
            "fiscalNumberFound": "OK",
            "doc2DAndDocumentTypeMatch": "OK",
            "doc2DAndFullName1Match": "OK",
            "doc2DAndFullName2Match": "SKIPPED",
            "doc2DAndReferenceIncomeMatch": "OK",
            "doc2DAndIncomeYearMatch": "OK"
        },
        "documentHolder": {
            "fullNameFound": "OK",
            "postalAddressFound": "KO",
            "fullNameMatch": "OK"
        }
    }
}

Ancien payload de retour déprécié basé sur les informations retournées par le service du site des impôts, qui n'est plus fonctionnel.

{
    "documentType": "TAX_JUSTIFICATION",
    "documentDetails": {
        "document": {
            "reference": "0000000000000",
            "fiscalNumber1": "0000000000000C",
            "refIncome": "15000",
            "fiscalNumber2": "0000000000000C",
            "issueDate": "2016-04-24",
            "incomesDetails": [
                {
                    "name": "DECLARANT_1",
                    "incomes": [
                        {
                            "label": "DEDUCTION 10 OU FRAIS REELS",
                            "value": -1000
                        },
                        {
                            "label": "SALAIRES",
                            "value": 30000
                        },
                        {
                            "label": "SALAIRES PENSIONS RENTES NETS",
                            "value": 32000
                        }
                    ]
                }
            ]
        },
        "holder": {
            "lastName": "DOE",
            "firstNames": [
                "JOHN"
            ]
        }
    },
    "controlsGroups": {
        "document": {
            "typeRecognized": "OK",
            "dateFound": "OK",
            "maxAgeNotExceeded": "OK"
        },
        "documentHolder": {
            "fullNameFound": "OK",
            "postalAddressFound": "SKIPPED",
            "postalAddressMatch": "SKIPPED"
        },
        "externalData": {
            "issuanceDateMatch": "OK",
            "checkable": "OK",
            "fullNameMatch": "OK",
            "birthDateMatch": "OK",
            "postalAddressMatch": "OK",
            "identifiersExists": "OK",
            "refIncomeMatch": "OK"
        }
    }
}

Documents d'identité

Sauf spécificités, ce retour est identique pour les cartes d'identité, passeports, titres de séjour et permis de conduire.

Les contrôles suivants peuvent être effectués sur le document:

Nom du contrôle	Description
typeRecognized	le système a reconnu le type du document
mrzValid	indique la les lignes de ZLA sont correctes (somme de contrôle)
documentCountryValid	le pays du document est autorisé. Si tous les pays ont été autorisé dans l'interface d'administration de *Trust and Sign, ce contrôle retournera toujours SKIPPED
documentAppearanceValid	l'apparence du document est correcte (ligne de ZLA cohérente avec l'apparence du reste du document)
birthDateMatch	la date de naissance extraite du document correspond à celle du participant
fullNameMatch	le nom du participant correspond à celui trouvé dans le document
civilityMatch	la civilité du participant correspond à celle trouvée dans le document
birthPlaceMatch	(CNI française uniquement) la ville de naissance du participant correspond à celle trouvée dans le document.
ocrMrzBirthDateMatch	La date de naissance est cohérent entre la ZLA et le reste du document.
ocrMrzBirthNameMatch	Le nom de naissance est cohérent entre la ZLA et le reste du document.
ocrMrzFirstNamesMatch	Les prénoms sont cohérents entre la ZLA et le reste du document.
ocrMrzDocumentNumberMatch	Le numéro du document est cohérent entre la ZLA et le reste du document.
faithfulFont	La police de caractère semble cohérente (uniquement pour les cartes d'identité française)
expirationDateRead	La date d'expiration a été lue
documentExpirationValid	le document n'est pas expiré
issuanceDateRead	La date de délivrance a été lue
issuanceAndExpirationDateMatch	Les dates de délivrance et d'expiration sont cohérentes
securityElementsValid	Les éléments de sécurité suivants sont corrects: Initiales du coin supérieur droit de la photo de la CNI française Nombre de perforations sur le passeport français Cohérence basique entre le numéro de passeport et sa date d'expiration
issuerReferentialConnectorSuccess	L'appel au référentiel DOCVERIF des documents d'identité a réussi.
issuerReferentialKnownDocument	Le document envoyé au référentiel DOCVERIF est connu.
issuerReferentialValid	Le document envoyé au référentiel DOCVERIF est valide et en règle.
issuerReferentialHolderValid	Le nom et le prénom extrait sont conformes avec le référentiel DOCVERIF.
notSpecimen	Le document envoyé n'est pas une speciment
backSideFound	Le verso du document n'a pas été trouvé
frontSideFound	Le recto du document n'a pas été trouvé

Les contrôles avec le référentiel (issuerReferential*) ne sont utilisés que :

pour les documents d'identité
si la qualité du document est suffisante
le numéro du document a pu être extrait
la date de délivrance du document a pu être extraite
la date de délivrance de la ZLA est cohérente avec celle de l'OCR
la date de délivrance est cohérente avec la date d'expiration du document
la ZLA est correcte

{
    "documentType": "ID_CARD",
    "documentDetails": {
        "document": {
            "issuanceCountry": "FR",
            "issuanceDate": "1988-06-22",
            "expirationDate": "1998-06-21",
            "number": "880692310285"
        },
        "holder": {
            "firstNames": [
                "CORINNE"
            ],
            "firstName": "CORINNE",
            "gender": "F",
            "birthDate": "1965-12-06",
            "birthName": "BERTHIER",
            "birthPlace": "PARIS 1ER (75",
            "rawAddress": "104 RUE DES FLEURS\n 92100 BOULOGNE BILLANCOURT"
        },
        "mrz": {
            "line1": "IDFRABERTHIER<<<<<<<<<<<<<<<<<<<<<<<",
            "line2": "8806923102858CORINNE<<<<<<<6512068F6"
        }
    },
    "controlsGroups": {
        "document": {
            "typeRecognized": "OK",
            "ocrMrzDocumentNumberMatch": "OK",
            "issuanceDateRead": "OK",
            "faithfulFont": "OK",
            "ocrMrzBirthNameMatch": "OK",
            "ocrMrzIssuanceDateMatch": "OK",
            "ocrMrzFirstNamesMatch": "OK",
            "documentCountryValid": "SKIPPED",
            "securityElementsValid": "OK",
            "expirationDateRead": "OK",
            "ocrMrzBirthDateMatch": "OK",
            "mrzValid": "OK",
            "backSideFound": "OK",
            "frontSideFound": "OK",
            "documentExpirationValid": "SKIPPED",
            "issuanceAndExpirationDateMatch": "OK",
            "issuerReferentialConnectorSuccess": "OK",
            "issuerReferentialKnownDocument": "OK",
            "issuerReferentialValid": "OK"
        },
        "documentAspect": {
            "modelValid": "OK",
            "documentAppearanceValid": "OK"
        },
        "documentHolder": {
            "firstLastNamesNotInverted": "OK",
            "birthPlaceMatch": "OK",
            "lastNameMatch": "OK",
            "birthNameMatch": "OK",
            "namesNotInverted": "OK",
            "birthDateMatch": "OK",
            "fullNameMatch": "OK",
            "firstNameMatch": "OK",
            "civilityMatch": "OK"
        }
    },
    "pages": [
        {
            "skewAngle": 6.279538631439209
        },
        {
            "skewAngle": -0.005252533592283726
        }
    ]
}

Carte de service italienne

Les contrôles suivants peuvent être effectués sur le document :

Nom du contrôle	Description
typeRecognized	le système a reconnu le type du document
documentExpirationValid	le document n'est pas expiré
documentAppearanceValid	l'apparence du document est correcte (ligne de ZLA cohérente avec l'apparence du reste du document)
birthDateMatch	la date de naissance extraite du document correspond à celle du participant
fullNameMatch	le nom du participant correspond à celui trouvé dans le document
documentNumberValid	Le numéro de la carte est valide
personalNumberValid	Le numéro du possesseur de la carte est valide
personalNumberAndHolderMatch	Le numéro du possesseur et le numéro de la carte sont cohérents
personalNumberMatch	Le numéro du possesseur de la carte est cohérent avec les informations du participant

{
    "documentType": "ITA_TS_CNS",
    "documentDetails": {
        "document": {
            "issuanceCountry": "IT",
            "expirationDate": "2026-08-31",
            "number": "110834303223"
        },
        "holder": {
            "firstNames": [
                "JOHN"
            ],
            "birthDate": "1984-08-13",
            "birthName": "DOE",
            "personalNumber": "ABCDE123456789"
        }
    },
    "controlsGroups": {
        "document": {
            "typeRecognized": "OK",
            "mrzValid": "OK",
            "documentExpirationValid": "OK",
            "documentCountryValid": "SKIPPED",
            "documentNumberValid": "OK",
            "personalNumberValid": "OK",
            "personalNumberAndHolderMatch": "OK"
        },
        "documentAspect": {
            "documentAppearanceValid": "OK"
        },
        "documentHolder": {
            "birthDateMatch": "OK",
            "fullNameMatch": "OK",
            "personalNumberMatch": "OK"
        }
    }
}

Re-soumission d'un document

Les pièces justificatives peuvent être re-contrôlées avec cette API. Suite à une mise à jour du dossier ou d'un participant, les contrôles peuvent devenir obsolètes. Cette API permet dans ce cas de relancer les contrôles avec les derniers documents soumis.

** Requête **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/documents/{attachmentId}/reprocess

Contenu de la requête

participantUuid : l'identifiant du participant possédant la tâche de signature à recontrôler. Si ce paramètre n'est pas présent, alors le premier participant du dossier sera utilisé.

** Retour **

Même contenu que la requête de soumission d'un document dans l' API d'intégration

Relance des contrôles lors d'une identification video

A l'issue d'une identification vidéo, les valeurs extraites des pièces peuvent être incohérentes avec les éléments définis dans le dossier. Dans tous les cas, suite à une mise à jour du dossier ou d'un participant, les contrôles peuvent devenir obsolètes. Les contrôles liés à l'identification peuvent donc être relancés par cette API.

Attention : cette fonctionnalité est spécifique au parcours d'identification vidéo ne comportant pas d'autres justificatifs que les pièces d'identités fournies lors de l'identification vidéo.

** Requête **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/identity-recompare

Contenu de la requête

participantUuid : l'identifiant du participant possédant la tâche de signature à recontrôler. Si ce paramètre n'est pas présent, alors le premier participant du dossier sera utilisé.

** Retour **

Même contenu que la requête de soumission d'un document dans l' API d'intégration

Modification visibilité des documents

Certains documents peuvent ne pas être affichés (et donc soumis) dans le Signbook. Dans ce cas, ils ne peuvent être envoyés que via l'API d'intégration.

En cas de problème retourné par l'API de soumission de document (document expiré, mauvais nom ...) il est conseillé de rendre le document visible pour que le participant le soumette.

Les documents masqués doivent être soumis juste après la création du dossier afin de ne pas bloquer le parcours de l'utilisateur final. Si ces documents sont soumis uniquement par API, il faut positionner le compteur d'essais à 1 pour permettre au dossier d'être finalisé.

** Requête **

Content-Type: multipart/form-data
POST /v6/integration/client-files/{clientFileUuid}/documents/{attachmentId}/visibility

clientFileUuid: l’identifiant technique du dossier
attachmentId: l'identifiant du document comme défini dans le champ "Identifiant" de l'interface de configuration du parcours (onglet "Justificatifs")

Contenu de la requête

participantUuid: l'identifiant unique du participant possédant le document à cacher
visiblity: les valeurs suivantes peuvent être utilisées :
- HIDDEN indiquant que le document ne doit pas être visible dans le Signbook
- VISIBLE indiquant que le document doit devenir visible dans le Signbook

** Retour **

aucun

Finalisation d'un dossier

Cette API n'est accessible que si la finalisation manuelle a été activée dans l'interface de configuration du parcours.

La finalisation n'est possible que si le dossier est signé, que tous les documents avant signature ont été acceptés et qu'au moins une soumission de document sans erreur a été faite sur chaque document (de chaque participant).

** Requête **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/finalize

clientFileUuid: l’identifiant technique du dossier

Headers de requête

USER (*): identifiant optionel de l'opérateur responsable de la finalisation (par exemple un utilisateur physique ou un utilisateur générique). Permet de finalizer un dossier avec toutes les pièces soumises dont certaines en erreur.

Contenu de la requête

aucun

** Retour **

aucun

Soumission d'un dossier par un participant

Cette API n'est accessible que si la finalisation manuelle a été activée dans l'interface de configuration du parcours.

La soumission n'est possible que si le participant a signé ses contrats, que tous les documents avant signature ont été acceptés et qu'au moins une soumission de document sans erreur a été faite sur chaque document. Une fois cette soumission effectuée, ce participant ne pourra plus modifier ses documents, mais cela ne bloque pas les autres participants qui n'ont pas encore soumis leur dossier.

** Requête **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/participants/{participantUuid}/complete

clientFileUuid: l’identifiant technique du dossier
participantUuid: l’identifiant technique du participant devant être finalisé

Contenu de la requête

message: Message du participant (maximum 800 caractères)

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

Collection Postman

Nous mettons à votre disposition une collection Postman (format 2.1) des requêtes documentées ci-dessus.

Une fois importée, vous devrez modifier à la racine de la collection les variables de l'onglet "Variables".

Statut du service

Une url de statut est disponible pour vous permettre de récupérer l’état de fonctionnement de la plate-forme Trust and Sign.

Il est conseillé de requêter ce service avant de procéder à la création d’un dossier ce qui permettra par exemple d’afficher un message d’erreur à vos clients au plus tôt.

** Requête **

GET /v6/status

** Retour **

Code HTTP 200

Il est conseillé de manière générale pour tous vos appels de définir un timeout supérieur ou égal à 90 secondes.