---
title: Créer un processus
description: POST /v1/processes — les champs communs, les limites de validation, les champs des flux et la réponse 201 avec le Human Token et l'intelligence.
canonical: https://developer.unico.io/fr/human-plugin/api-reference/create-process
locale: fr
generated_by: markdown-export
---

# Créer un processus

Démarrez un processus et obtenez le Human Token et l'intelligence de la personne.

`POST /v1/processes`

Démarre un processus avec l'un des [flux](#flows) et répond avec `id`, `state` et le résultat dans `data` : le Human Token et l'[intelligence](/fr/human-plugin/get-started/intelligence) de la personne, `data.ndocs`.

## Avant d'appeler

- Human Plugin est en cours d'exécution et `GET /health/ready` répond `200`.
- Votre clé d'accès est activée pour le [flux](#flows) que vous utilisez.
- Si vous envoyez un document, son `type` figure dans le [catalogue d'attributs](/fr/human-plugin/additional-resources/attribute-catalog).

<a id="flows"></a>

## Flux

Le champ `flow` choisit ce que fait le processus. Human Plugin exécute ces flux, selon deux modèles d'intégration :

- **API Only** : votre back-end envoie le selfie dans `imageBase64`, et la création répond avec le résultat.
- **Human Token Journey** : la personne prend le selfie dans le parcours de capture et revient vers votre `callbackUri`. La création répond avec un `token` et un `link`, et vous lisez le résultat avec [Obtenir un processus](/fr/human-plugin/api-reference/get-process).

| Flow | Description | Possible result | Integration components required |
| --- | --- | --- | --- |
| `api+humantoken` | Reçoit un selfie via votre back-end et génère le Human Token, un identifiant facial unique. La réponse est définitive : pas de capture, pas de second appel. | `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API |
| `humantoken` | Capture un selfie dans le parcours de capture, avec une vérification de détection de vie, et génère le Human Token. La création renvoie le `token` et le `link` ; lisez le résultat à la fin de la capture. | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |
| `humantoken+revalidation` | Capture un selfie et compare le visage avec le Human Token attendu. Indique s'il s'agit de la même personne ou non, par exemple avant une action sensible. | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web |

`clientId`, `correlationId` et `credential` sont identiques dans tous les flux.

## Requête

```json
{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<base64 selfie>"
}
```

### Champs communs

| Champ | Obligatoire | Limite (octets) | Remarques |
| --- | --- | --- | --- |
| `flow` | Oui | 64 | L'un des [flux](#flows) |
| `clientId` | Oui | 128 | Votre identifiant du client. L'intelligence compte les valeurs distinctes |
| `correlationId` | Oui | 128 | Votre référence pour ce processus. **Unique** : une valeur déjà utilisée par un autre processus, quel que soit son état, est refusée avec `409` |
| `credential` | Oui, mais peut être vide | | La clé doit être présente. Voir ci-dessous |
| `credential.type` | Avec un document | | Un code du catalogue d'attributs, exact et sensible à la casse |
| `credential.value` | Avec un document | 64 | Le numéro du document |

`flow`, `clientId` et `correlationId` doivent être des chaînes, sans caractères de contrôle et sans espaces au début ni à la fin. Les valeurs invalides sont rejetées, jamais réécrites.

### Le champ `credential`

- **Avec un document :** un objet contenant exactement `type` et `value`, deux chaînes, envoyées ensemble.
- **Sans document :** `null` ou `{}`. Le processus compte quand même comme une transaction et comme un client dans l'intelligence.
- **Omis, ou objet avec des chaînes vides :** rejeté avec `400 MISSING_CREDENTIAL_TYPE`. Cela permet de détecter une clé mal orthographiée avant tout traitement.
- Toute autre clé dans `credential` est rejetée.

### Champs des flux

Ce que chaque flux ajoute aux champs communs :

| Champ | Flux | Obligatoire | Valeur |
| --- | --- | --- | --- |
| `imageBase64` | `api+humantoken` | Oui | Le selfie en base64. PNG, JPEG ou WebP, jusqu'à 800 Ko |
| `callbackUri` | `humantoken`, `humantoken+revalidation` | Oui | L'endroit où la personne revient à la fin de la capture : une de vos pages, ou le schéma d'URL de votre application |
| `references` | `humantoken+revalidation` | Oui | Un élément avec le Human Token attendu, comme dans l'exemple ci-dessus |

Human Plugin ne stocke pas ces champs, et un champ facultatif mal orthographié peut être ignoré sans erreur.

Avec `api+humantoken`, utilisez un selfie de face, bien éclairé, montrant un seul visage. Une valeur qui n'est pas une image est refusée, et le processus est enregistré comme échoué : voir [Refus des flux](#flow-refusals).

Avec `humantoken+revalidation`, le résultat contient `humanTokenMatch` au lieu de `humanToken` :

- `"true"` : il s'agit de la même personne. Le processus compte pour cette personne, et `ndocs` la décrit.
- Toute autre valeur, ou une capture non vivante : ce n'est pas confirmé. Le processus ne compte pour personne, et il n'y a pas de `ndocs`.

`PROCESS_STATE_FINISHED` est renvoyé dans les deux cas : lisez `humanTokenMatch`. Voir [Obtenir un processus](/fr/human-plugin/api-reference/get-process#finished-and-failed-processes).

Quelques noms sont réservés par Human Plugin et refusés avec `400 INVALID_REQUEST`, comme `clientReference`. Il en va de même pour une autre orthographe des champs propres à Human Plugin, comme `client_id`, `correlation_id` ou `Flow` : seuls `flow`, `clientId`, `correlationId` et `credential` sont lus, avec exactement cette orthographe.

### Règles du corps

- Un seul objet JSON, de **2 MiB** au maximum (à peu près suffisant pour un selfie en base64). Un corps plus volumineux est refusé avec `400 REQUEST_TOO_LARGE`.
- Rien ne doit suivre l'objet JSON.

## Réponse

`201 Created`, avec `Location: /v1/processes/<id>`.

```json
{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}
```

- `id` est l'UUID de Human Plugin. Chaque requête acceptée en crée un nouveau.
- `state` est le statut local. Voir [cycle de vie](/fr/human-plugin/api-reference/process-lifecycle).
- `humantoken` et `humantoken+revalidation` répondent `PROCESS_STATE_CREATED` avec un `token` et un `link`. Ils sont renvoyés **une seule fois** et ne sont jamais stockés : conservez-les. Voir [Human Token Journey](/fr/human-plugin/integrations/human-token-journey) et le guide de capture de votre plateforme.
- `data.ndocs` est l'intelligence de la personne. Il peut être absent : voir [Intelligence](/fr/human-plugin/get-started/intelligence).

<a id="result"></a>

### Le résultat dans `data`

Un processus terminé a ces champs dans `data`. Les flux Journey les renvoient lorsque vous [lisez le processus](/fr/human-plugin/api-reference/get-process) après la capture.

| Champ | Quand | Valeur |
| --- | --- | --- |
| `humanToken` | `api+humantoken`, `humantoken` | Qui est la personne : `value` est le Human Token, et `status` vaut `validated` lorsqu'il a été généré |
| `humanTokenMatch` | `humantoken+revalidation` | `"true"` lorsqu'il s'agit de la même personne que le Human Token de `references` |
| `liveness` | Flux qui vérifient la détection de vie, comme les flux Journey | `value` vaut `live` lorsque la capture provient d'une personne vivante, ou `not_live` dans le cas contraire ; `status` vaut `validated` lorsque la vérification a été effectuée |
| `ndocs` | Lorsqu'il existe de l'intelligence pour la personne | L'[intelligence](/fr/human-plugin/get-started/intelligence) de la personne |

Un résultat Journey ressemble à ceci :

```json
{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}
```

Vérifiez `liveness` avant de faire confiance au résultat : avec `not_live`, considérez la capture comme échouée et demandez à la personne de réessayer. Un processus avec `not_live` ne compte pour l'intelligence de personne.

## Erreurs

| Statut | `message` | Signification |
| --- | --- | --- |
| 400 | `INVALID_REQUEST`, `REQUEST_TOO_LARGE` | Pas un seul objet JSON, un champ réservé, un type incorrect, ou un corps supérieur à 2 MiB |
| 400 | `MISSING_<FIELD>`, `INVALID_<FIELD>` | Un champ obligatoire est absent ou mal formé, comme `MISSING_CLIENT_ID` |
| 401 | Vide (`""`) | Unico a refusé votre clé d'accès : elle est absente, incorrecte ou n'est plus valide. Le processus est enregistré comme échoué. Vérifiez `HUMAN_API_ACCESS_KEY` |
| 409 | `CORRELATION_ID_ALREADY_USED` | Un autre processus a déjà ce `correlationId`. Rien n'est stocké ni envoyé |
| 422 | `ATTRIBUTE_TYPE_NOT_SUPPORTED` | `credential.type` ne figure pas dans le catalogue. Rien n'est stocké ni envoyé |
| 4xx | Le `message` du flux | Le flux a refusé la requête, par exemple à cause d'une image invalide. Voir [Refus des flux](#flow-refusals) |
| 502 | `UPSTREAM_UNAVAILABLE` | Le processus n'a pas pu être confirmé à temps |
| 503 | `DATABASE_UNAVAILABLE` | La base de données a échoué. Rien n'a été traité |
| 500 | `INTERNAL` | Erreur inattendue |

<a id="flow-refusals"></a>

### Refus des flux

Lorsqu'un flux refuse la requête, la création répond `4xx` avec la raison dans `message`, dans l'[enveloppe](/fr/human-plugin/api-reference/errors-and-retries) habituelle. Les plus courants :

| `message` | Cause |
| --- | --- |
| `invalid flow` | `flow` n'est pas un flux activé pour votre compte |
| `INVALID_IMAGE` (`400`) | `api+humantoken` sans `imageBase64` |
| `INVALID_REQUEST` (`400`) | `imageBase64` n'est pas une image en base64 |
| `IMAGE_TOO_LARGE` | L'image dépasse 800 Ko |
| `UNSUPPORTED_IMAGE_FORMAT` | L'image n'est pas au format PNG, JPEG ou WebP |
| `PERMISSION_DENIED` (`403`) | Votre clé d'accès n'est pas activée pour ce flux |

Un processus refusé est enregistré comme échoué. Corrigez la requête et créez un nouveau processus avec un nouveau `correlationId`.

Lisez [Erreurs et nouvelles tentatives](/fr/human-plugin/api-reference/errors-and-retries) avant d'ajouter une logique de nouvelle tentative : une nouvelle tentative nécessite un nouveau `correlationId`.

## Suite

[Obtenir un processus](/fr/human-plugin/api-reference/get-process)