> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sahlfinancial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contrôle eID

> Vérification d'identité à distance d'un client canadien : démarrer, interroger, lire le résultat, télécharger le rapport.

Un contrôle eID prouve qu'un client qui n'est pas devant vous est bien la personne figurant sur sa pièce d'identité. Le client reçoit un courriel avec un PIN et un lien, scanne une pièce d'identité et prend un selfie dans l'application du fournisseur eID. Trois endpoints couvrent le parcours. Scope pour les trois : `kyc:eid`.

Dans cette version, le moteur n'accepte que les clients canadiens pour l'eID. Les exemples de cette page utilisent donc le pays `CA`, contrairement aux autres guides, qui utilisent `MA`.

| Endpoint | Fonction |
| - | - |
| `POST /v1/kyc/eid` | Démarre le contrôle. Le fournisseur envoie aussitôt un courriel au client. Renvoie HTTP 201 et une `key`. |
| `GET /v1/kyc/eid/{key}` | Où en est le contrôle, ce qu'il a prouvé, et ses contrôles. |
| `GET /v1/kyc/eid/{key}/report` | Le rapport PDF du fournisseur sur le contrôle. |

## Avant de commencer

| Condition | Si elle n'est pas remplie |
| - | - |
| Le client est canadien : `country` vaut `CA` ou `CAN`. | 422 `identity verification is available for Canadian clients only` |
| Votre espace de travail a son propre compte chez le fournisseur eID. Sahl le configure. | 404 `identity verification is not set up for this tenant` |
| La clé a le scope `kyc:eid` et l'espace de travail est activé pour l'API Partner. | 403 |

<Warning>
  `environment` ne change pas le fournisseur. Une requête faite avec `environment: "sandbox"` envoie quand même un courriel au client et appelle quand même le fournisseur. `environment` choisit seulement le dossier sur lequel la requête est classée. Utilisez une adresse courriel que vous contrôlez pour vos tests.
</Warning>

## Démarrer un contrôle

```json theme={null}
{
  "reference": "client-0001",
  "first_name": "Test",
  "last_name": "Client",
  "email": "test.client@example.com",
  "country": "CA",
  "language": "en",
  "documents": 1,
  "environment": "sandbox"
}
```

| Champ | Type | Par défaut | Règle |
| - | - | - | - |
| `reference` | string | obligatoire | De 1 à 64 caractères parmi `A-Z a-z 0-9 _ . : -`. Votre identifiant du client. |
| `first_name` | string | obligatoire | De 1 à 100 caractères. |
| `last_name` | string | obligatoire | De 1 à 100 caractères. |
| `email` | string | obligatoire | Un courriel valide. Le PIN et le lien y sont envoyés. |
| `country` | string | obligatoire | 2 ou 3 caractères. Seuls `CA` ou `CAN` sont acceptés. |
| `language` | string | `en` | `en` ou `fr`. |
| `documents` | entier | `1` | `1` ou `2` : combien de pièces d'identité le client doit scanner. |
| `environment` | string | `sandbox` | `sandbox` ou `production`. Choisit le dossier. |

La réponse :

```json theme={null}
{ "key": 123456, "reference": "client-0001" }
```

`key` est l'identifiant avec lequel vous interrogez. Le PIN est envoyé au client uniquement et ne vous est jamais renvoyé.

La requête est classée comme `pending` sur le dossier de (espace de travail, environnement, `reference`). Une nouvelle requête pour la même référence et le même environnement remplace l'enregistrement, car vous avez recommencé la vérification du client. Le fournisseur stocke la requête sous un identifiant client composé de votre espace de travail et de votre référence, ce qui empêche un autre espace de travail de la lire.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://app.sahlfinancial.com/api/v1/kyc/eid \
    -H "Authorization: Bearer $SAHL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"reference":"client-0001","first_name":"Test","last_name":"Client","email":"test.client@example.com","country":"CA","language":"en","documents":1,"environment":"sandbox"}'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://app.sahlfinancial.com/api/v1/kyc/eid", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SAHL_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      reference: "client-0001",
      first_name: "Test",
      last_name: "Client",
      email: "test.client@example.com",
      country: "CA",
      language: "en",
      documents: 1,
      environment: "sandbox",
    }),
  });
  if (res.status !== 201) throw new Error(`${res.status} ${await res.text()}`);
  const { key } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.post(
      "https://app.sahlfinancial.com/api/v1/kyc/eid",
      headers={"Authorization": f"Bearer {os.environ['SAHL_API_KEY']}"},
      json={
          "reference": "client-0001",
          "first_name": "Test",
          "last_name": "Client",
          "email": "test.client@example.com",
          "country": "CA",
          "language": "en",
          "documents": 1,
          "environment": "sandbox",
      },
      timeout=60,
  )
  assert res.status_code == 201, res.text
  key = res.json()["key"]
  ```
</CodeGroup>

## États

Le fournisseur n'envoie aucun rappel. Vous interrogez `GET /v1/kyc/eid/{key}`. Sahl déduit l'état de l'interrogation.

```mermaid theme={null}
stateDiagram-v2
    [*] --> pending: POST /v1/kyc/eid (client prévenu par courriel)
    pending --> complete: le client a scanné un document
    pending --> archived: demande archivée, jamais terminée
    complete --> passed: aucun contrôle critical n'a échoué
    complete --> failed: un contrôle critical a échoué
    passed --> [*]
    failed --> [*]
    archived --> [*]
```

| État | `complete` | `passed` | Ce que vous faites |
| - | - | - | - |
| `pending` | false | false | Continuez d'interroger. Le contrôle `eid:completed` dit `the client has not completed the verification yet`. |
| `passed` | true | true | Utilisez-le. Téléchargez le rapport. |
| `failed` | true | false | Regardez quel contrôle `eid:` a échoué. Démarrez une nouvelle requête pour réessayer. |
| `archived` | false | false | La requête a été archivée sans contrôle terminé. `eid:completed` dit `the request was archived without a completed verification`. Démarrez une nouvelle requête. |

`pending`, `passed`, `failed` et `archived` sont aussi le statut que Sahl enregistre sur le dossier. Seul `passed` satisfait l'exigence eID d'une politique.

## Interroger

`GET /v1/kyc/eid/{key}` a un seul paramètre de requête facultatif, `environment` (`sandbox` par défaut). Il ne sert qu'à situer une requête démarrée avant que Sahl ne conserve l'enregistrement eID. Une requête faite via `POST /v1/kyc/eid` garde son propre environnement.

Sahl ne fixe aucun intervalle d'interrogation. Le seul plafond est de 100 requêtes par minute et par IP. Un rythme raisonnable : toutes les 30 secondes pendant les 10 premières minutes, puis toutes les 5 minutes. Le client doit ouvrir le courriel, donc des minutes ou des heures sont normales.

Un contrôle terminé (complete ou archived) est le moment où Sahl enregistre le résultat sur le dossier, et la première interrogation qui le voit envoie le [webhook](/fr/guides/webhooks) `kyc.eid_completed`. Les interrogations suivantes restent silencieuses.

### Réponse une fois terminé

```json theme={null}
{
  "key": 123456,
  "complete": true,
  "passed": true,
  "identity": {
    "documentType": "PASSPORT",
    "documentNumber": "P1234567",
    "expiryDate": "2030-05-01",
    "birthDate": "1988-04-12",
    "firstName": "Test",
    "lastName": "Client"
  },
  "checks": [
    { "id": "eid:liveness", "label": "Selfie passed the liveness check", "severity": "critical", "passed": true, "detail": "" },
    { "id": "eid:face_match", "label": "Face on the ID matches the selfie (score 3 or more)", "severity": "critical", "passed": true, "detail": "score 4 of 4, confidence 97%" },
    { "id": "eid:name_match", "label": "Name on the ID matches the name on the request", "severity": "critical", "passed": true, "detail": "" }
  ],
  "completed_date": "2026-10-07T12:00:00Z"
}
```

Les valeurs sont fictives, produites par la même fonction que celle de l'API.

| Clé | Signification |
| - | - |
| `key` | L'identifiant de la requête. |
| `complete` | Vrai dès que le client a scanné un document. |
| `passed` | Vrai quand `complete` et qu'aucun contrôle de sévérité `critical` n'a échoué. |
| `identity` | Ce que le contrôle a prouvé. Clés possibles : `documentType`, `documentNumber`, `expiryDate`, `birthDate`, `firstName`, `lastName`, `address`. Présentes seulement pour les valeurs que le fournisseur détient. Vide tant que ce n'est pas terminé. |
| `checks` | Les contrôles eID, dans la même forme que les contrôles de vérification. |
| `completed_date` | Heure de fin telle que le fournisseur la rapporte, ou null. |

### Les contrôles

| Id | Sévérité | Réussi quand |
| - | - | - |
| `eid:completed` | critical | Présent seulement jusqu'à ce que le client termine. Toujours échoué. |
| `eid:liveness` | critical | Le selfie a passé le contrôle de vivacité. |
| `eid:face_match` | critical | Le score de correspondance du visage est de 3 ou plus (le détail montre `score N of 4` et la confiance). |
| `eid:name_match` | critical | Le nom sur la pièce d'identité correspond au nom de votre requête. C'est pourquoi le prénom et le nom que vous envoyez doivent être exacts. |
| `eid:message:N` | critical ou warning | Le fournisseur a renvoyé un message. Toujours échoué. Voir ci-dessous. |

Messages du fournisseur et leur sévérité :

| Message | Sévérité |
| - | - |
| `The machine readable values of one or more fields do not match.` | critical |
| `Document is past expiry date.` | critical |
| `Name entered on request does not match name on document.` | critical |
| `Low face match score.` | critical |
| `No machine readable data found on document.` | warning |
| tout autre message | warning |

## Rapport

`GET /v1/kyc/eid/{key}/report` renvoie le rapport du fournisseur en `application/pdf` avec `Content-Disposition: attachment; filename="eid-<key>.pdf"`. Il est destiné au dossier du client.

```bash theme={null}
curl -o eid-123456.pdf https://app.sahlfinancial.com/api/v1/kyc/eid/123456/report \
  -H "Authorization: Bearer $SAHL_API_KEY"
```

## Conserver le résultat

Récupérez le résultat et le PDF dans les sept jours environ qui suivent le contrôle. Passé ce délai, le fournisseur supprime les données personnelles. Sahl enregistre le résultat (statut, heure de fin) sur votre dossier quand une interrogation voit pour la première fois l'état final, mais le bloc `identity` et le PDF viennent du fournisseur, donc conservez ce dont vous avez besoin.

## Satisfaire l'exigence eID d'une politique

Une politique d'espace de travail peut exiger un contrôle eID à distance pour une personne non rencontrée en face à face (`eid_required_non_face_to_face`). `/verify` et `/assess` ajoutent alors un contrôle critical `policy:eid_non_face_to_face` :

| Situation | Contrôle |
| - | - |
| Une requête avec cette `reference` et cet `environment` a été faite via `POST /v1/kyc/eid` et son statut enregistré est `passed` | réussi : `eID request N passed` |
| Aucune requête enregistrée | échoue : `the client was not met in person and no eID request made through Sahl (POST /v1/kyc/eid) is on file for this reference and environment` |
| Requête en attente | échoue : `eID request N has not been seen completed; poll GET /v1/kyc/eid/{key} once the client has finished` |
| Requête échouée ou archivée | échoue : `eID request N ended failed` (ou `archived`) |
| `values.verified_in_person` vaut true | non appliqué. Un contrôle info `policy:met_in_person_declared` consigne que c'est votre déclaration et que Sahl ne l'a pas vérifiée. |
| `purpose` vaut `periodic_review` | non appliqué |

Seul l'enregistrement de Sahl satisfait l'exigence. Un contrôle que vous envoyez dans `extra_checks` avec un id commençant par `eid:` est renommé `partner:eid:...` et ne compte jamais. Utilisez la même `reference` et le même `environment` pour la requête eID et pour l'appel `/verify`. Interrogez jusqu'à la fin du contrôle avant d'appeler `/verify`, car le résultat est enregistré par l'interrogation.

## Erreurs

| Statut | Corps | Cause |
| - | - | - |
| 401, 403 | Voir [erreurs](/fr/errors) | Problèmes de clé. |
| 404 | `identity verification is not set up for this tenant` | Aucun compte fournisseur sur l'espace de travail. |
| 404 | `Not Found` | `key` inconnue, ou clé démarrée par un autre espace de travail. |
| 422 | `identity verification is available for Canadian clients only` | `country` n'est ni `CA` ni `CAN`. |
| 422 | liste `detail` | Un champ ne respecte pas le schéma, par exemple `documents` ne vaut ni 1 ni 2. |
| 502 | `the identity verification service did not answer` | Le fournisseur est indisponible ou a refusé. Réessayez plus tard. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.