Intégrer votre back-end

La checklist pour appeler Human Plugin depuis un service côté serveur.

Markdown

Human Plugin est conçu pour être appelé uniquement par votre back-end. Ne l'exposez pas aux navigateurs ni aux applications mobiles : il n'a pas d'authentification entrante.

1. Créer

curl

curl -X POST "$HUMAN_PLUGIN_URL/v1/processes" \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "api+humantoken",
    "clientId": "client-a",
    "correlationId": "onboarding-001",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "imageBase64": "<base64 selfie>"
  }'

Node.js

const response = await fetch(`${process.env.HUMAN_PLUGIN_URL}/v1/processes`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    flow: 'api+humantoken',
    clientId: 'client-a',
    correlationId: 'onboarding-001',
    credential: { type: 'DUI_TYPE_NG_BVN', value: documentNumber },
    imageBase64,
  }),
  signal: AbortSignal.timeout(60_000),
});

const body = await response.json();
if (response.status !== 201) {
  // body vaut { message, details }
  throw new Error(`Human Plugin ${response.status} ${body.message}`);
}
const { id, state, data } = body;

Définissez le timeout de votre client à au moins 60 secondes : une création peut prendre jusqu'à 30 secondes de traitement, auxquelles s'ajoutent les étapes de base de données. L'id n'est renvoyé que dans la réponse de création : un client qui abandonne trop tôt peut perdre un processus qui se termine.

2. Conserver ce dont vous aurez besoin plus tard

À conserver	Pourquoi
id	L'identifiant à utiliser pour le GET
token et link du Journey, le cas échéant	Renvoyés uniquement dans la réponse de création, jamais stockés par Human Plugin
Votre correlationId	Il doit être unique. Générez-en un nouveau à chaque tentative, nouvelles tentatives comprises, sauf après un 503

3. Lire le résultat

1. Si state vaut PROCESS_STATE_FINISHED, lisez le résultat dans data : humanToken (ou humanTokenMatch dans une revalidation), liveness et ndocs. Terminé ne signifie pas approuvé.
2. Si state vaut PROCESS_STATE_CREATED, interrogez GET /v1/processes/{id} avec un backoff jusqu'à ce qu'il change. Rien d'autre ne fait avancer le processus.
3. Si state vaut PROCESS_STATE_FAILED, le processus s'est terminé sans résultat. Démarrez-en un nouveau si votre flux le permet.

4. Exploiter l'intelligence

data.ndocs indique ce que la personne a fait chez vous : avec combien de vos clients et de documents elle a été vue, et quand. Utilisez-le dans votre décision avec le Human Token, en gardant à l'esprit qu'il peut être absent. Voir Intelligence.

5. Gestion des échecs

• Ne relancez pas automatiquement un 500 ou un 502 à la création. Voir Erreurs et nouvelles tentatives.
• Relancez un 503 à la création avec le même correlationId, ainsi que toute défaillance sur GET, avec un backoff.
• 409 signifie que le correlationId est déjà utilisé. Ne le réutilisez jamais.
• Déclenchez une alerte en cas de 503 répétés : cela signifie que Human Plugin ne peut pas joindre sa base de données.

Attentes opérationnelles

• Appelez Human Plugin depuis le même réseau que le conteneur. Terminez TLS en amont si le trajet traverse des réseaux non fiables.
• Une installation de Human Plugin constitue une frontière d'isolation. Les clients, marques ou environnements différents qui ne doivent pas partager d'intelligence ont besoin d'installations et de bases de données distinctes, chacune avec sa propre intelligence.