> ## 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.

# Comment les appels s'articulent

> extract, verify, assess et eID : ce que prend chaque appel, ce qu'il renvoie et ce que vous transmettez.

L'API Partner a quatre fonctions et six endpoints. Chaque appel est une fonction de ce que vous envoyez. Sahl ne classe rien dans votre espace de travail si l'appel ne porte pas de `reference`.

| Fonction | Endpoint | Scope | Compte une lecture |
| - | - | - | - |
| Lire des documents en champs | `POST /v1/kyc/extract` | `kyc:extract` | Oui, une par fichier |
| Vérifier un profil et ses documents | `POST /v1/kyc/verify` | `kyc:verify` | Non |
| Vérifier, puis évaluer le risque | `POST /v1/kyc/assess` | `kyc:verify` | Non |
| Contrôler un client canadien à distance | `POST /v1/kyc/eid`, `GET /v1/kyc/eid/{key}`, `GET /v1/kyc/eid/{key}/report` | `kyc:eid` | Non |

Seul `/extract` appelle le modèle de vision, donc seul `/extract` est décompté. Le quota est contrôlé avant la lecture du moindre fichier.

## Le parcours principal

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant App as Votre serveur
    participant API as API Partner Sahl
    participant Console as Console Sahl
    App->>API: POST /v1/kyc/extract (files, doc_type, reference)
    API-->>App: fields, documents[], checks[], case_id
    App->>API: POST /v1/kyc/extract (document suivant)
    API-->>App: fields, documents[], checks[]
    Note over App: Fusionnez les champs que vous détenez dans values.<br/>Gardez les entrées de documents[] telles quelles.
    App->>API: POST /v1/kyc/verify (reference, values, documents[])
    API-->>App: passed, checks[], flags[], completeness, case_id
    App->>API: POST /v1/kyc/assess (même corps)
    API-->>App: verification, assessment, case_id
    API-->>Console: dossier, documents et verdict classés sous reference
```

Ce que vous transmettez d'un appel au suivant :

| De | Vers | Quoi |
| - | - | - |
| `documents[]` de la réponse `/extract` | `documents` de la requête `/verify` et `/assess` | Chaque entrée telle quelle, y compris `step_key` et `document_id`. |
| `fields` de la réponse `/extract` | Votre propre formulaire ou base de données | Pré-remplissage. Vous décidez quelles valeurs vont dans `values`. |
| Vos propres données | `values` de la requête `/verify` et `/assess` | Noms, dates, adresse, revenus, réponses d'adéquation. |
| La même `reference` | Chaque appel | Elle relie les appels à un même dossier. |

`/assess` prend le même corps que `/verify` et exécute d'abord la même vérification. Si vous voulez les deux réponses, appelez uniquement `/assess` : sa clé `verification` contient le verdict complet.

## Pourquoi renvoyer les entrées

`/verify` ne lit pas de fichiers. Il contrôle les entrées `documents[]` que vous envoyez, donc il a besoin de ce que `/extract` a vu : le type de document, les champs, les dates du fichier et le `step_key`. Sans le `step_key`, un même document pourrait passer le contrôle de type à `/extract` et l'échouer à `/verify`. L'API place le `step_key` sur chaque entrée pour cette raison.

Si vous modifiez une entrée, vous vérifiez votre modification, pas le document.

## Le parcours eID

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant App as Votre serveur
    participant API as API Partner Sahl
    participant Provider as Fournisseur eID
    participant Client as Votre client
    App->>API: POST /v1/kyc/eid (reference, name, email, country=CA)
    API->>Provider: créer la demande
    Provider-->>Client: courriel avec PIN et lien
    API-->>App: 201 key, reference
    Client->>Provider: scanne la pièce d'identité, prend un selfie
    loop jusqu'à ce que complete soit true
        App->>API: GET /v1/kyc/eid/{key}
        API->>Provider: lire la demande
        API-->>App: complete, passed, checks[]
    end
    App->>API: GET /v1/kyc/eid/{key}/report
    API-->>App: PDF
    App->>API: POST /v1/kyc/verify (même reference et environment)
    API-->>App: verdict qui satisfait l'exigence eID de la politique
```

Le fournisseur n'envoie aucun rappel. Vous interrogez l'API, et Sahl envoie le webhook `kyc.eid_completed` la première fois qu'une interrogation voit l'état final. Les détails sont dans [Contrôle eID](/fr/guides/eid). Dans cette version, l'eID est réservé aux clients canadiens, donc la requête d'exemple utilise `country=CA` ; tous les autres appels de cette page acceptent n'importe quel pays, par exemple `MA`.

## Cycle de vie d'un dossier

Un dossier existe une fois par espace de travail, environnement et `reference`. Chaque appel avec cette référence le met à jour.

```mermaid theme={null}
flowchart LR
    A[Premier appel avec une reference] --> B[Dossier créé]
    B --> C[extract : documents classés]
    C --> D[verify ou assess : verdict classé]
    D --> E[eID : résultat enregistré à l'interrogation]
    D --> F[Revue par le personnel dans la console]
    F --> G[approved ou refused]
```

Une nouvelle vérification n'écrase jamais un statut fixé par une personne : `approved` et `refused` restent.

## Choisir les appels

| Vous voulez | Appel |
| - | - |
| Seulement le texte et les champs d'un document | `/extract` |
| Un oui ou un non sur un dossier dont vous détenez déjà les données | `/verify` avec `documents: []` et `require_documents: false` (fonctionne quand votre politique ne verrouille pas la vérification d'identité) |
| Contrôles par document et contrôles entre documents | `/extract` par document, puis `/verify` |
| Une note de risque pour le dossier | `/assess` |
| La preuve qu'un client à distance est bien la personne sur la pièce d'identité | `/eid` |

<Note>
  L'API n'a ni clé d'idempotence ni endpoint par lot. Envoyer deux fois le même appel lit les fichiers deux fois, compte deux lectures et classe un second jeu de documents sur le dossier. Voir [Erreurs et nouvelles tentatives](/fr/errors).
</Note>


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