Web Services / API d'intégration One Click Contract V6

Cette API permet d’accélérer la souscription Trust and Sign de vos clients déjà connus (renouvellement, "up sales", etc.). Les clients éligibles ont uniquement besoin de s'authentifier à Trust and Sign via leur mobile pour que les informations et justificatifs de leur précédent dossier soient automatiquement récupérés dans leur nouveau dossier.

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 l'API One Click Contract, il faut disposer du couple login / mot de passe One Click Contract associé à votre compagnie. Ces informations sont envoyées par Namirial lorsque vous souhaitez utiliser cette fonctionnalité. Le login correspond à la clé 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/1cc. 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/1cc. Cet environnement est mis à jour à la même date que la production ;
pour l’environnement de production : https://api.ekeynox.net/contract/v6/1cc ;

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=

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

Vérification de l'éligibilité d'un dossier One Click Contract

** Requête **

Recherche globale sur tous les produits accessibles

POST /contract/v6/1cc/check-eligibility HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "email" : "participant@namirial.com"
}

Recherche affinée sur certains produits

POST /contract/v6/1cc/check-eligibility HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "email" : "participant@namirial.com",
  "products" : [{
    "label" : "Test product 1",
    "maxAge" : 180
  },
  {
    "label" : "Test product 2",
    "maxAge" : 90
  }]
}

Path	Type	Description
`email`*	`String`	(*) Email du participant demandant la vérification One click contract
`products[].label`	`String`	Label des produits où chercher un participant
`products[].maxAge`	`Number`	Age maximum de création du dossier au sein d'un produit (en jours)

** Retour **

Un objet JSON contenant les informations suivantes :

Path	Type	Description
`isEligible`*	`Boolean`	True si l'email est éligible One Click Contract
`mobilePhoneTruncated`	`String`	3 derniers chiffres du numéro de téléphone

{
  "isEligible" : true,
  "mobilePhoneTruncated" : "025"
}

Création d'un dossier One Click Contract

** Requête **

POST /contract/v6/1cc/authenticate HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "email" : "participant@namirial.com",
  "otpTemplate": "Votre code OTP ${otp}",
  "products" : [{
    "label" : "Test product 1",
    "maxAge" : 180
  },
  {
    "label" : "Test product 2",
    "maxAge" : 90
  }]
}

Path	Type	Description
`email`	`String`	(*) Email du participant demandant la vérification One click contract
`otpTemplate`	`String`	Modèle du SMS envoyé au participant. Il doit contenir obligatoirement la chaîne `${otp}`. Si ce champ n'est pas défini, le modèle par défaut sera utilisé
`products[].label`	`String`	Label des produits où chercher un participant
`products[].maxAge`	`Number`	Age maximum de création du dossier au sein d'un produit

** Retour **

Un objet JSON contenant les informations suivantes :

Path	Type	Description
`isEligible`	`Boolean`	(*) True si l'email est éligible One Click Contract
`oneccToken`	`String`	Token One Click Contract

{
  "isEligible" : true,
  "oneccToken" : "20190813_U5sSJsAjHoEe08ue8ow8Jbi4Othz0da"
}

Validaton d'un OTP One Click Contract

** Requête **

POST /contract/v6/1cc/validate HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "token" : "20190813_iDayMPuvhn0VeeEQ8jCSMBRqDJuX5D3",
  "otpCode" : "1234"
}

Path	Type	Description
`token`	`String`	(*) Token One click contract
`otpCode`	`String`	(*) Code OTP

** Retour **

Un objet JSON contenant les informations suivantes :

Path	Type	Description
`oneccUUID`	`String`	Uuid de l'enregistrement
`oneccToken`	`String`	Token d'authentification
`clientFile`	`Object`	Dossier de référence
`clientFile.uuid`	`String`	Uuid du Dossier
`clientFile.creationDate`	`String`	Date de création du dossier
`clientFile.finalizationDate`	`String`	Date de Finalisation du dossier
`clientFile.productLabel`	`String`	Label du produit
`clientFile.workflowLabel`	`String`	Label du parcours
`clientFile.state`	`String`	Etat du dossier
`clientFile.externalInfo`	`Object`	Données additionnelles du dossier.
`participant`	`Object`	Participant du dossier éligible
`participant.civility`	`String`	Civilité
`participant.email`	`String`	Email
`participant.lastName`	`String`	Nom
`participant.firstName`	`String`	Prénom
`participant.birthDate`	`String`	Date de naissance
`participant.birthPlace`	`String`	Lieux de naissance
`participant.birthName`	`String`	Nom de naissance
`participant.mobilePhone`	`String`	Numéro de mobile
`participant.iban`	`String`	IBAN
`participant.postalAddress`	`Object`	Adresse postale du participant
`participant.postalAddress.address1`	`String`	Première ligne de l’adresse postale
`participant.postalAddress.address2`	`String`	Deuxième ligne de l’adresse postale
`participant.postalAddress.address3`	`String`	Troisième ligne de l’adresse postale
`participant.postalAddress.city`	`String`	Ville
`participant.postalAddress.postalCode`	`String`	Code postal
`participant.postalAddress.countryCode`	`String`	Code Pays
`documents[]`	`Array`	Documents uploadés par le participant
`documents[].label`	`String`	Label
`documents[].type`	`String`	Type de document
`documents[].attachmentId`	`String`	Identifiant du document
`documents[].files`	`Array`	Fichiers envoyés dans le dossier
`documents[].files[].name`	`String`	Nom du fichier
`documents[].files[].mimeType`	`String`	Mime type du fichier
`documents[].controls`	`Object`	Contrôles des documents (liste non exhaustive)
`documents[].controls.participants[]`	`Array`	Contrôles spécifiques du participant

{
  "oneccUUID" : "b634185a-aced-4743-8607-24eae701ea51",
  "oneccToken" : "20190829_5XWR8JhphhNBtp6NGTGHMEwGQA9m5TE",
  "participant" : {
    "email" : "validate@namirial.com",
    "mobilePhone" : "067891234",
    "lastName" : "Doe",
    "firstName" : "John",
    "birthDate" : "1980-06-02",
    "birthPlace" : "Montpellier",
    "birthName" : "Doe",
    "iban" : "FR7630001007941234567890185",
    "postalAddress" : {
      "address1" : "10 Rue de Montpellier",
      "address2" : "Bat.2",
      "address3" : "2è étage",
      "city" : "Montpellier",
      "postalCode" : "34000"
    }
  },
  "clientFile" : {
    "uuid" : "7a72163f-5b7e-4fd2-9334-76f18e103b4e",
    "creationDate" : "2019-08-29T15:36:48Z",
    "finalizationDate" : "2019-08-29T15:36:51Z",
    "productLabel" : "Test product",
    "workflowLabel" : "dummy-simple",
    "state" : "ACCEPTED",
    "externalInfo" : {
      "ext1" : "v1"
    }
  },
  "documents" : [ {
    "label" : "ID card",
    "type" : "id_card",
    "attachmentId" : "1",
    "controls" : {
      "modelValid" : true,
      "containsAnnotations" : false,
      "documentNotExpired" : true,
      "ocrMrzDocumentNumberMatch" : true,
      "ocrMrzBirthNameMatch" : true,
      "faithfulFont" : true,
      "securityElements" : true,
      "ocrMrzIssuanceDateMatch" : true,
      "ocrMrzFirstNamesMatch" : true,
      "documentTypeMatch" : true,
      "documentCountryValid" : true,
      "documentAppearanceValid" : true,
      "ocrMrzBirthDateMatch" : true,
      "mrzValid" : true,
      "backSideFound" : true,
      "documentValid" : true,
      "issuanceAndExpirationDateMatch" : true,
      "mrzOcrConsistent" : true,
      "participants" : [ {
        "owner" : "70905b46-630a-4107-b70f-e3f6054fa328",
        "firstLastNamesInverted" : false,
        "lastNameMatch" : true,
        "namesInverted" : false,
        "birthDateMatch" : true,
        "firstNameMatch" : true,
        "civilityMatch" : true
      } ]
    },
    "files" : [ {
      "name" : "1_1_id_card_01.png",
      "mimeType" : "image/png"
    } ]
  }, {
    "label" : "Facture EDF",
    "type" : "payslip",
    "attachmentId" : "3",
    "controls" : {
      "companyIdValid" : true,
      "containsAnnotations" : false,
      "nirValid" : true,
      "companyOfficeIdValid" : true,
      "companyConnectorRequested" : true,
      "nirFound" : true,
      "documentTypeMatch" : true,
      "companyConnectorFailed" : false,
      "participants" : [ {
        "owner" : "70905b46-630a-4107-b70f-e3f6054fa328",
        "birthDateMatch" : true,
        "nameFound" : true,
        "civilityMatch" : true,
        "postalAddressFound" : true,
        "postalAddressMatch" : true
      } ]
    },
    "files" : [ {
      "name" : "3_1_payslip_01.png",
      "mimeType" : "image/png"
    } ]
  } ]
}

** Principales Erreurs **

Token inconnu, expiré ou déjà validé

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error" : {
    "code" : 1012,
    "invalidParameters" : [ "token" ],
    "message" : "Token not found"
  }
}

l'OTP ne correspond pas à celui envoyé

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error" : {
    "code" : 1071,
    "invalidParameters" : [ "OtpCode" ],
    "message" : "Invalid OTP code"
  }
}

l'OTP est en erreur, aucune validation possible, le dossier 1CC ne pourra pas être créé

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error" : {
    "code" : 1069,
    "invalidParameters" : [ "OtpCode" ],
    "message" : "OTP validation failed"
  }
}

l'OTP ne peut être validé, un nouvel OTP peut être redemandé

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error" : {
    "code" : 1072,
    "invalidParameters" : [ "OtpCode" ],
    "message" : "Validate OTP code error, can renew"
  }
}

Téléchargement des documents du registre One Click Contract

** Requête **

GET /contract/v6/1cc/document/${filename} HTTP/1.1

Path	Type	Description
`${filename}`	`String`	Nom du fichier à télécharger (obtenu dans `documents[].files[].name`)

** Retour **

HTTP/1.1 200 OK