Aller au contenu

Web Services / API Analytic V6

Prérequis

Prérequis à l’utilisation des web services analytic

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.

Voici l'URL pour requêter l'API analytic :

https://api.ekeynox.net/contract/v6/integration/analytic/events

Les chapitres suivants décrivent l’API JSON telle qu’elle est disponible à ce jour.

Dans le cadre des évolutions du produit, il est possible que des champs supplémentaires, non encore documentés, soient ajoutés dans les réponses. Nous vous recommandons donc de concevoir votre intégration de manière suffisamment souple afin de ne pas rejeter les payloads contenant des attributs additionnels.

IMPORTANT

Le nom des clés est sensible à la casse.

Les paramètres notés (*) sont obligatoires, les autres sont facultatifs.

Authentification

L’authentification basique 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)

L'exemple 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=

Consulter les événements de tous les dossiers

Sur une période donnée

Cette requête permet de récupérer les événements associés à tous les dossiers, terminés et en cours.

Chemin

GET /v6/integration/analytic/events

Paramètres

  • startDate (*) : date et heure de début de la période de recherche. Seuls les événements dont la date de l’événement est postérieure ou égale à cette valeur seront pris en compte. Le format attendu est ISO 8601.

  • endDate (*) : date et heure de fin de la période de recherche. Seuls les événements dont la date de l’événement est antérieure ou égale à cette valeur seront pris en compte. Le format attendu est ISO 8601.

  • page : la page de résultats que l'on souhaite consulter. Les pages contiennent 1000 événements. Si le paramètre n'est pas fourni, la page 1 sera retournée.

Retour

Le retour est un JSON contenant une liste d'événements. Les évènements sont regroupés par dossier et triés du plus récent au plus ancien.

Voir la réponse d'API

Exemple

/v6/integration/analytic/events?startDate=2025-08-03T23:50:00.000Z&endDate=2025-08-05T00:00:00.000Z&page=1

Sur un dossier particulier

Cette requête permet de récupérer tous les événements associés à un dossier, terminé ou en cours.

Chemin

GET /v6/integration/analytic/{clientFileUuid}/events

Paramètres

  • startDate : date et heure de début de la période de recherche. Seuls les événements dont la date de l’événement est postérieure ou égale à cette valeur seront pris en compte. Le format attendu est ISO 8601.

  • endDate : date et heure de fin de la période de recherche. Seuls les événements dont la date de l’événement est antérieure ou égale à cette valeur seront pris en compte. Le format attendu est ISO 8601.

  • page : la page de résultats que l'on souhaite consulter. Les pages contiennent 1000 événements. Si le paramètre n'est pas fourni, la page 1 sera retournée.

Retour

Voir la réponse d'API

Exemples

GET /v6/integration/analytic/0197fa0b-5714-74cd-9f23-623b846fb8af/events
GET /v6/integration/analytic/0197fa0b-5714-74cd-9f23-623b846fb8af/events?page=2
GET /v6/integration/analytic/0197fa0b-5714-74cd-9f23-623b846fb8af/events?startDate=2025-08-03T23:50:00.000Z&page=2
GET /v6/integration/analytic/0197fa0b-5714-74cd-9f23-623b846fb8af/events?startDate=2025-08-03T23:50:00.000Z&endDate=2025-09-03T23:50:00.000Z&page=3

Consulter les événements des dossiers terminés uniquement

Sur une période donnée

Cette requête permet de récupérer les événements associés aux dossiers terminés : acceptés ou rejetés.

Chemin

GET /v6/integration/analytic/closed
Paramètres

  • startDate (*) : date et heure de début de la période de recherche. Seuls les dossiers dont la date de clôture est postérieure ou égale à cette valeur seront pris en compte. Le format attendu est ISO 8601.

  • endDate (*) : date et heure de fin de la période de recherche. Seuls les dossiers dont la date de clôture est antérieure ou égale à cette valeur seront pris en compte. Le format attendu est ISO 8601.

  • page : la page de résultats que l'on souhaite consulter. Les pages contiennent 1000 événements. Si le paramètre n'est pas fourni, la page 1 sera retournée.

Retour

Le retour est sous la forme d'un JSON contenant une liste d'événements. Les évènements sont regroupés par dossier et triés du plus récent au plus ancien.

Voir la réponse d'API

Exemple

/v6/integration/analytic/closed?startDate=2025-08-03T23:50:00.000Z&endDate=2025-08-05T00:00:00.000Z&page=1

Sur un dossier particulier

Cette requête permet de récupérer tous les événements associés à un dossier terminé (accepté ou rejeté).

Chemin

GET /v6/integration/analytic/{clientFileUuid}/closed

Paramètres

  • startDate : Date et heure de début de la période de recherche. Seuls les événements dont la date de l’événement est postérieure ou égale à cette valeur seront pris en compte. Le format attendu est ISO 8601.

  • endDate : Date et heure de fin de la période de recherche. Seuls les événements dont la date de l’événement est antérieure ou égale à cette valeur seront pris en compte. Le format attendu est ISO 8601.

  • page : la page de résultats que l'on souhaite consulter. Les pages contiennent 1000 événements. Si le paramètre n'est pas fourni, la page 1 sera retournée.

Retour

Voir la réponse d'API

Exemples

GET /v6/integration/analytic/0197fa0b-5714-74cd-9f23-623b846fb8af/closed
GET /v6/integration/analytic/0197fa0b-5714-74cd-9f23-623b846fb8af/closed?page=2
GET /v6/integration/analytic/0197fa0b-5714-74cd-9f23-623b846fb8af/closed?startDate=2025-08-03T23:50:00.000Z&page=2
GET /v6/integration/analytic/0197fa0b-5714-74cd-9f23-623b846fb8af/closed?startDate=2025-08-03T23:50:00.000Z&endDate=2025-09-03T23:50:00.000Z&page=3

Réponse des appels API

Le JSON contient les clés suivantes :

  • eventId : l'UUID de l'évènement (différent de l'UUID Trust and Sign)
  • eventTypeKey : le type d'évènement, par exemple "CREATION" ou "SIGNATURE" ...etc
  • eventTimestamp : La date de l'évènement au format TIMESTAMP en millisecondes
  • eventStatus : le statut de l'évènement, cette clé est une énumération : OK|KO (Optionnel)
  • contextId : l'UUID du dossier dans Trust and Sign
  • participantKey : l'UUID du participant dans Trust and Sign (Optionnel)
  • rejectionReason : la raison du rejet (uniquement pour les évènements de type REJECTION)
  • signatureLevelKey : le niveau de signature (uniquement pour les évènements de type SIGNATURE)
  • workflowKey : l'UUID du workflow dans Trust and Sign
  • workflowVersion : la version du workflow dans Trust and Sign
  • workflowLabel : le nom du parcours dans Trust and Sign
  • productUuid : l'UUID du produit dans Trust and Sign
  • productLabel : le libellé du produit dans Trust and Sign
  • companyLabel : le libellé de la compagnie dans Trust and Sign
  • externalId : l'identifiant externe défini dans le dossier T&S, il est utilisé par le client afin de référencer le dossier dans son système (Optionnel)
  • source: l'identifiant de source du client
  • provider: le fournisseur de service de l'événement, peut être archivage, signature, ou un service interne
[
    {
        "eventId": "01983cdb-f945-7143-936a-6555dee79cac",
        "eventTypeKey": "VIDEO_IDENTIFICATION_PROCESSED",
        "eventTimestamp": 1752255975000,
        "eventStatus": "KO",
        "contextId": "0197fa0b-4bc7-7ecd-9a9b-d3e48fbceb2e",
        "participantKey": "0197fa27-bcba-76e6-9035-efe45013fe05",
        "workflowKey": "0197fa0b-4b09-7005-8201-ea6227ddaf67",
        "workflowVersion": "1",
        "workflowLabel": "facematch-identity",
        "productUuid": "0197fa09-1d0e-7eed-968f-0fb7ebb5506c",
        "productLabel": "Test product",
        "companyLabel": "Company test",
        "externalId": "external_id_123456",
        "source": "Chrome_13138#Linux",
        "provider": "ek_prevent_video"
    },
    {
        "eventId": "0197fa0b-4be0-7120-a88f-4ddf2a76e3f2",
        "eventTypeKey": "CREATION",
        "eventTimestamp": 1752253933000,
        "contextId": "0197fa0b-4bc7-7ecd-9a9b-d3e48fbceb2e",
        "workflowKey": "0197fa0b-4b09-7005-8201-ea6227ddaf67",
        "workflowVersion": "1",
        "workflowLabel": "facematch-identity",
        "productUuid": "0197fa09-1d0e-7eed-968f-0fb7ebb5506c",
        "productLabel": "Test product",
        "companyLabel": "Company test",
        "externalId": "external_id_123456"
    },
    {
        "eventId": "0199f28d-5aa6-7ab3-a593-f649362b0280",
        "eventTypeKey": "VIDEO_IDENTIFICATION_REQUESTED",
        "eventTimestamp": 1752250974000,
        "contextId": "0197fa0b-4bc7-7ecd-9a9b-d3e48fbceb2e",
        "participantKey": "0199f28d-0474-7b10-b88d-d377646bcd91",
        "workflowKey": "0197fa0b-4b09-7005-8201-ea6227ddaf67",
        "workflowVersion": "1",
        "workflowLabel": "facematch-identity",
        "productUuid": "0197fa09-1d0e-7eed-968f-0fb7ebb5506c",
        "productLabel": "Test product",
        "companyLabel": "Company test",
        "externalId": "external_id_123456",
        "source": "Chrome_14141#Linux",
        "provider": "ek_prevent_video"
    },
    {
        "eventId": "0197fa0b-5009-776d-b19e-cbc641a27bf2",
        "eventTypeKey": "UPDATE",
        "eventTimestamp": 1752253934000,
        "contextId": "0197fa0b-4e83-79d3-81e8-856d1149e8f0",
        "workflowKey": "0197fa0b-4b09-7005-8201-ea6227ddaf67",
        "workflowVersion": "2",
        "workflowLabel": "facematch-identity",
        "productUuid": "0197fa09-1d0e-7eed-968f-0fb7ebb5506c",
        "productLabel": "Test product",
        "companyLabel": "Company test",
        "externalId": "external_id_789012"
    },
    {
        "eventId": "0197fa0b-4e86-78b7-8e52-1ae3a589c7c7",
        "eventTypeKey": "CREATION",
        "eventTimestamp": 1752253934000,
        "contextId": "0197fa0b-4e83-79d3-81e8-856d1149e8f0",
        "workflowKey": "0197fa0b-4b09-7005-8201-ea6227ddaf67",
        "workflowVersion": "2",
        "workflowLabel": "facematch-identity",
        "productUuid": "0197fa09-1d0e-7eed-968f-0fb7ebb5506c",
        "productLabel": "Test product",
        "companyLabel": "Company test",
        "externalId": "external_id_789012"
    },
    {
        "eventId": "0197fa0b-54c0-7a0f-8dbb-ca91df5ef684",
        "eventTypeKey": "FINALIZATION",
        "eventTimestamp": 1752253936000,
        "contextId": "0197fa0b-52b9-76f7-8405-98091fde7401",
        "workflowKey": "0197fa0b-529a-7781-a133-e83d79249bbc",
        "workflowVersion": "1",
        "workflowLabel": "facematch-identity-validation",
        "productUuid": "0197fa09-1d0e-7eed-968f-0fb7ebb5506c",
        "productLabel": "Test product",
        "companyLabel": "Company test"
    },
    {
        "eventId": "0197fa0b-551b-73af-9739-87519a216086",
        "eventTypeKey": "REJECTION",
        "eventTimestamp": 1752253936000,
        "contextId": "0197fa0b-52b9-76f7-8405-98091fde7401",
        "rejectionReason": "FILE_REJECTED_AFTER_VERIFICATION",
        "workflowKey": "0197fa0b-529a-7781-a133-e83d79249bbc",
        "workflowVersion": "1",
        "workflowLabel": "facematch-identity-validation",
        "productUuid": "0197fa09-1d0e-7eed-968f-0fb7ebb5506c",
        "productLabel": "Test product",
        "companyLabel": "Company test"
    },
    {
        "eventId": "0197fa0b-54bc-7695-8335-a83e256979e3",
        "eventTypeKey": "PARTICIPANT_COMPLETION",
        "eventTimestamp": 1752253936000,
        "contextId": "0197fa0b-52b9-76f7-8405-98091fde7401",
        "participantKey": "0197fa0b-52bb-7c75-ac89-562a04b5f601",
        "workflowKey": "0197fa0b-529a-7781-a133-e83d79249bbc",
        "workflowVersion": "1",
        "workflowLabel": "facematch-identity-validation",
        "productUuid": "0197fa09-1d0e-7eed-968f-0fb7ebb5506c",
        "productLabel": "Test product",
        "companyLabel": "Company test",
        "source": "Chrome_5757#Linux"
    }
]