Web Services / One Click Contract V6 Integration API

This API allows you to accelerate the Trust and Sign subscription of your existing customers (renewals, up-sales, etc.). Eligible customers only need to authenticate to Trust and Sign via their mobile phone so that the information and proofs from their previous file are automatically retrieved in their new file.

Prerequisites

*** Prerequisites for the use of integration web services ***

To obtain authentication access to Trust and Sign web services, you must complete the account creation process with Namirial.

In order to use the One Click Contract API, you must have the One Click Contract login/password associated with your company. This information is sent by Namirial when you want to use this feature. The login is the public key and the password is the secret key.

The basic URLs for the integration services are as follows:

for the integration environment: https://integration-api.ekeynox.net/contract/v6/1cc. This environment is updated regularly and has the latest features;
for the pre-production environment: https://preprod-api.ekeynox.net/contract/v6/1cc. This environment is updated on the same date as production;
for the production environment: https://api.ekeynox.net/contract/v6/1cc;

The following chapters describe the JSON API. Depending on the evolution of the product, we may add undocumented fields in the returns. You should therefore not be too restrictive on the payloads.

Please note that the name of the keys is case sensitive. Mandatory fields will be marked (*), other fields will be optional.

Authentication

Basic" authentication is used here; it follows the [RFC1945] standard (http://tools.ietf.org/html/rfc1945). An HTTP header named AUTHORIZATION must be added to requests. This is of the form :

AUTHORIZATION = Basic base64(login:password)

The following code snippet can be used in Java to generate this header:

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

For example, for a login "john123456" and a password "azerty" we get the following header:

AUTHORIZATION = Basic am9objEyMzQ1NjphemVydHk=

Error handling

If an error occurs during a request, a standard HTTP code is returned with an error JSON containing server-specific code Trust and Sign, an explanatory message and any invalid parameters.

For example:

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

Checking the eligibility of a One Click Contract file

** Query **

Global search on all accessible products

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

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

Refined search on some products

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 from participant requesting One click contract verification
products[].label`\|`String`	Label of products to search for a participant
Products[].maxAge`\|`Number`	Maximum age of file creation within a product (in days)

** Return **

A JSON object containing the following information:

Path	Type	Description
`isEligible`*	`Boolean`	True if the email is eligible One Click Contract
MobilePhoneTruncated`\|`String`	Last 3 digits of phone number

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

Creating a One Click Contract file

** Request **

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

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

Path	Type	Description
`email`	`String`	(*) Email from participant requesting One click contract verification
Template of the SMS sent to the participant. It must contain the string `${otp}`. If this field is not defined, the default template will be used
products[].label`\|`String`	Label of products to search for a participant
Products[].maxAge`\|`Number`	Maximum age of record creation within a product

** Return **

A JSON object containing the following information:

Path	Type	Description
(*) True if the email is eligible One Click Contract
Token One Click Contract

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

Validation of an 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

** Back **

A JSON object containing the following information:

Path	Type	Description
`oneccUUID`	`String`	Uuid of the record
`oneccToken`	`String`	Authentication Token
ClientFile	`Object`	Reference File
ClientFile.uuid	Folder Uuid
ClientFile.creationDate	String	Folder creation date
ClientFile.finalizationDate	`String`	Date of File Finalization
clientFile.productLabel	`String`	Product Label
ClientFile.workflowLabel	String	Label of the workflow
ClientFile.state	File state
ClientFile.externalInfo	`Object`	Additional file data.
Participant`\|`Object`	Eligible file participant
participant.civility`\|`String`	Civility
participant.email`\|`String`	Email
participant.lastName`\|`String`	Name
Participant.firstName	FirstName
Participant.birthDate`\|`String`	Date of birth
Participant.birthPlace`\|`String`	Place of birth
participant.birthName`\|`String`	Birth name
participant.mobilePhone`\|`String`	Mobile number
participant.iban`\|`String`	IBAN
Participant.postalAddress`\|`Object`	Participant's postal address
Participant.postalAddress.address1`\|`String`	First line of postal address
Participant.postalAddress.address2	`String`	Second line of mailing address
participant.postalAddress.address3`\|`String`	Third line of mailing address
participant.postalAddress.city`\|`String`	City
participant.postalAddress.postalCode`\|`String`	Postal Code
participant.postalAddress.countryCode`\|`String`	Country Code
Documents[]`\|`Array`	Documents uploaded by the participant
documents[].label`\|`String`	Label
Documents[].type`	Document type
Documents[].attachmentId`\|`String`	Document identifier
Documents[].files`\|`Array`	Files sent to the folder
Documents[].files[].name`\|`String`	File name
Documents[].files[].mimeType`\|`String`	Mime type of file
Documents[].controls`\|`Object`	Document controls (non exhaustive list)
documents[].controls.participants[]`\|`Array`	Participant specific controls

{
  "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",
      "ville" : "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" : "ACCEPTÉ",
    "externalInfo" : {
      "ext1" : "v1"
    }
  },
  "documents" : [ {
    "label" : "ID card",
    "type" : "id_card",
    "attachmentId" : "1",
    "contrôles" : {
      "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" : [ {
        "propriétaire" : "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" : "fiche de paie",
    "attachmentId" : "3",
    "contrôles" : {
      "companyIdValid" : true,
      "containsAnnotations" : false,
      "nirValid" : true,
      "companyOfficeIdValid" : true,
      "companyConnectorRequested" : true,
      "nirFound" : true,
      "documentTypeMatch" : true,
      "companyConnectorFailed" : false,
      "participants" : [ {
        "propriétaire" : "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"
    } ]
  } ]
}

** Main Errors **

Token unknown, expired or already validated

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

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

the OTP does not match the one sent

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

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

the OTP is in error, no validation possible, the 1CC folder cannot be created

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

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

OTP cannot be validated, a new OTP can be requested

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

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

Downloading documents from the One Click Contract Registry

** Request **

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

Path	Type	Description
`${filename}`	`String`	Name of file to be uploaded (obtained from `documents[].files[].name`)

** Back **

HTTP/1.1 200 OK