API — KYC (public embed)

Préfixe : /api/kyc

Le module KYC expose un flux public destiné à être intégré (embed / registration).

Créer une session (public)

POST /api/kyc/public/sessions

Auth : Platform API key via authenticateApiKey.

Headers :

x-api-key: <dlk_...>

Body :

instanceKey (string) ou instanceId (string) — requis
externalReference (optionnel)
expiresInSeconds (optionnel, défaut 3600)
successRedirectUrl / failureRedirectUrl (optionnels)
metadata (optionnel)

API — KYC (public embed)

Préfixe: /api/kyc

Ce module expose un flux public destiné à être intégré dans un parcours (embed / onboarding). Les opérations “session” se font via un sessionToken transmis côté client.

Base URL

API backend: https://<your-backend-host>
Préfixe KYC: https://<your-backend-host>/api/kyc

Authentification

Créer une session

La création de session requiert une Platform API key (préfixe dlk_...) via header:

x-api-key: <dlk_...>

Appels publics de la session

Une fois la session créée, les routes publiques utilisent le sessionToken (kyc_sess_...) fourni par l’API:

GET /public/sessions/:sessionId?token=<sessionToken>
POST ... avec token dans le body JSON

Créer une session

Method	Path
POST	`/api/kyc/public/sessions`

Headers

Header	Required	Example
`Content-Type`	yes	`application/json`
`x-api-key`	yes	`dlk_<...>`

Body (JSON)

Field	Type	Required	Description
`instanceKey`	string	yes*	Clé publique d’instance.
`instanceId`	string	yes*	ID d’instance.
`externalReference`	string	no	Référence externe.
`expiresInSeconds`	number	no	TTL session, défaut `3600`.
`successRedirectUrl`	string	no	URL de redirection succès.
`failureRedirectUrl`	string	no	URL de redirection échec.
`metadata`	object \| null	no	Métadonnées stockées en JSONB.
`mode`	`prod \| dev`	no	Mode demandé. `dev` peut être refusé selon environnement.

* instanceKey ou instanceId est requis.

Response (201)

{
	"session": {
		"id": "<sessionId>",
		"instance_id": "<instanceId>",
		"company_id": "<companyId>",
		"mode": "prod",
		"status": "created",
		"external_reference": null,
		"expires_at": "2026-01-10T13:00:00.000Z",
		"created_at": "2026-01-10T12:00:00.000Z"
	},
	"verificationUrl": "https://<your-app-host>/kyc/session/<sessionId>?token=<sessionToken>",
	"sessionToken": "kyc_sess_<...>"
}

Errors

Status	Body	When
400	`{ error: "instanceKey or instanceId is required" }`	Paramètres manquants.
400	`{ error: "dev mode is not allowed on this environment" }`	`mode=dev` refusé.
401	`{ error: "Invalid API key" }`	Clé absente/invalide.
403	`{ error: "API key is not allowed for this instance" }`	Clé d’une autre company.
404	`{ error: "Instance not found" }`	Instance inconnue.
500	`{ error: "Failed to create session" }`	Erreur serveur.

Lire une session (embed)

Method	Path
GET	`/api/kyc/public/sessions/:sessionId`

Query

Param	Type	Required	Description
`token`	string	yes	`sessionToken` (hashé côté DB).

Response (200)

Retourne session avec configuration d’instance (ex: instance_config, instance_workflow).

{ "session": { "id": "<sessionId>", "instance_config": {}, "instance_workflow": {} } }

Errors

Status	Body	When
400	`{ error: "token is required" }`	Token absent.
404	`{ error: "Session not found" }`	Session ou token invalide.
410	`{ error: "Session expired" }`	Session expirée.
500	`{ error: "Failed to get session" }`	Erreur serveur.

Vérifier un captcha (dans une session KYC)

Method	Path
POST	`/api/kyc/public/sessions/:sessionId/captcha/verify`

Body (JSON)

Field	Type	Required	Description
`token`	string	yes	`sessionToken`.
`captchaToken`	string	yes	JWT renvoyé par Captcha (`captchaToken`).
`siteKey`	string	yes	`CAPTCHA_SITE_...` attendu par le token.

Response (200)

Ce endpoint renvoie:

succès: { ok: true, success: true, score }
rejet fonctionnel: { ok: true, success: false, error }

{ "ok": true, "success": true, "score": 90 }

{ "ok": true, "success": false, "error": "SITE_MISMATCH" }

Errors

Status	Body	When
400	`{ ok:false, error:"Missing token" }`	Champs manquants.
404	`{ ok:false, error:"Session not found" }`	Session/token invalide.
409	`{ ok:false, error:"Session already completed" }`	Session terminée/expirée.
410	`{ ok:false, error:"Session expired" }`	Session expirée.
500	`{ ok:false, error:"Failed to verify captcha token" }`	Erreur serveur.

Publier la progression

Method	Path
POST	`/api/kyc/public/sessions/:sessionId/progress`

Body (JSON)

Field	Type	Required	Description
`token`	string	yes	`sessionToken`.
`progress`	object	no	Fusionné en JSONB (`progress = progress
`status`	`created \| running \| failed \| cancelled`	no	Statut session (si fourni).

Response (200)

{ "ok": true, "session": { "id": "<sessionId>", "status": "running", "started_at": "...", "updated_at": "..." } }

Errors

Status	Body	When
400	`{ error: "token is required" }`	Token absent.
400	`{ error: "progress must be an object" }`	`progress` n’est pas un objet JSON.
404	`{ error: "Session not found" }`	Session/token invalide.
409	`{ error: "Session is not updatable" }`	Session `completed`/`expired`.
410	`{ error: "Session expired" }`	Session expirée.
500	`{ error: "Failed to update progress" }`	Erreur serveur.

Compléter une session

Method	Path
POST	`/api/kyc/public/sessions/:sessionId/complete`

Body (JSON)

Field	Type	Required	Description
`token`	string	yes	`sessionToken`.
`result`	any \| null	no	Résultat JSON stocké dans `result`.
`status`	`completed \| failed \| cancelled`	no	Défaut: `completed`.

Response (200)

{ "ok": true, "session": { "id": "<sessionId>", "status": "completed" }, "redirectUrl": "https://..." }

Errors

Status	Body	When
400	`{ error: "token is required" }`	Token absent.
404	`{ error: "Session not found" }`	Session/token invalide.
500	`{ error: "Failed to complete session" }`	Erreur serveur.

Déduplication (anti-replay / anti-duplicate)

Method	Path
POST	`/api/kyc/public/sessions/:sessionId/dedup-check`

Body (JSON)

Field	Type	Required	Description
`token`	string	yes	`sessionToken`.
`keyHash`	string	yes	SHA-256 hex (64 chars), stocké/agrégé côté serveur.

Response (200)

{
	"ok": true,
	"matchFound": false,
	"firstSessionId": "<sessionId>",
	"lastSessionId": "<sessionId>",
	"seenCount": 1,
	"firstSeenAt": "2026-01-10T12:00:00.000Z",
	"lastSeenAt": "2026-01-10T12:00:00.000Z"
}

Errors

Status	Body	When
400	`{ error: "keyHash must be a sha256 hex string" }`	Format invalide.
404	`{ error: "Session not found" }`	Session/token invalide.
410	`{ error: "Session expired" }`	Session expirée.
500	`{ error: "Failed to check dedup" }`	Erreur serveur.