Table des matières

Documentation API PVID Cloud

Documentation API PVID Cloud

L'API PVID Cloud vous permet de,

générer les liens PVID à transmettre à vos utilisateurs pour qu'ils puissent effectuer le parcours de vérification d'identité,
récupérer les informations des PVID effectués par vos utilisateurs,
configurer le parcours de vérification d'identité pour qu'il s'intègre au mieux dans votre parcours métier
tester l'appareil mobile de votre utilisateur avant qu'il ne démarre son parcours

Cette documentation a pour but de vous guider dans l'intégration et la consommation de l'API PVID Cloud.

Ressources

Swagger PVID Cloud

Getting Started

Pour utiliser l'API PVID Cloud vous devez posséder des identifiants. Vous pouvez demander vos identifiants directement au support PVID Cloud.

1. Authentification

Pour l'ensemble des routes de l'API PVID Cloud il faut être en capacité de,

soumettre une authentification valide
déchiffrer le retour de l'API PVID Cloud

L'API PVID Cloud utilise OAuth 2.0 avec des tokens JWT. Toutes les requêtes API authentifiées nécessitent un token JWT valide 5 minutes.

1.1 Se connecter à l'API (POST /api/login)

Voir dans le Swagger

Route permettant d'obtenir un token JWT pour pouvoir requêter les autres endpoints.

Paramètres

Paramètre	Type	Description	Requis
—	—	—	—
`username`	string	Identifiant de votre application	✅
`password`	string	Mot de passe associé	✅

Réponse | Succès

Code	Status
——–	—–
200	OK

Exemple de réponse

snippet.json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "123e4567-e89b-12d3-a456-426614174000",
  "scope": "email profile"
}

Réponse | Erreurs

Code	Status	Valeur
—	—	—
400	Bad Request	`Missing credentials`
401	Unauthorized	`Invalid credentials or Keycloak error`

1.2 Headers d'authentification

Pour vous authentifier, il faut ajouter ce header à toutes vos requêtes.

Header	Valeur
—	—
`Authorization`	Bearer `ACCESS_TOKEN`

1.3 Rafraîchir le token (POST /api/refresh_token)

Voir dans le Swagger

Route pour obtenir un nouveau token d'accès sans vous reconnecter.

Paramètres

Paramètre	Type	Description	Requis
—	—	—	—
`refresh_token`	string	Token de rafraîchissement obtenu lors du login	✅

Réponse | Succès

Code	Status
—	—
200	OK

Exemple de réponse

snippet.json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "123e4567-e89b-12d3-a456-426614174000",
  "scope": "email profile"
}

Réponse | Erreurs

Code	Status	Message
—	—	—
400	Bad Request	`Missing refresh token`
400	Bad Request	`Invalid refresh token`
401	Unauthorized	`Invalid credentials or Keycloak error`

1.4 Infos complémentaires

Le token d'accès est valide 300 secondes (5 minutes).
Le refresh token est valide 1800 secondes (30 minutes).
Utilisez le token via le header : Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Si vous utilisez un token expiré, vous recevrez une erreur 401 Unauthorized

2. Signature et déchiffrement des requêtes

Pour des raisons de sécurité, vos requêtes vers PVID Cloud doivent être signées et les réponses de notre API devront être déchiffrées.

2.1 Mécanisme de chiffrement

Pour toutes les routes sécurisées (sauf /api/login et /api/refresh_token), un header signature est obligatoire. Ce header permet de valider l'authenticité de la requête.

Header requis

Header	Type	Description	Requis
—	—	—	—
`signature`	string	Signature générée à partir du paramètre `date`	✅

Algorithme de génération de la signature

Élément	Valeur
—	—
Algorithme	AES-256-CBC avec padding PKCS7
Clé	32 premiers caractères de SHA256(`tokenSecret`) en hexadécimal
IV	16 premiers caractères de SHA256(SHA256(`tokenSecret`)) en hexadécimal
Valeur à chiffrer	Le paramètre `date` (format `YYYY-MM-DD HH:mm:ss`)
Sortie	Base64

Réponse | Erreurs

Code	Status	Slug	Message
—	—	—	—
400	Bad Request	`invalid_date`	`Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)`
400	Bad Request	`empty_date`	`No date parameter found in your request`
400	Bad Request	`expired_date`	`Given datetime is older than current datetime`
400	Bad Request	`date_in_future`	`Given datetime must be set between call submission and +10 minutes`
400	Bad Request	`validation_error`	`Signature verification failed`
400	Bad Request	`failed_signature`	`Signature verification failed`
401	Unauthorized	N/A	`JWT Token not found`
401	Unauthorized	N/A	`Expired JWT Token`
401	Unauthorized	`user_not_exist`	`Unknown user`
500	Bad Request	`internal_server_error`	`Internal server error`

2.1.1 Génération de la signature en PHP

snippet.php

<?php
 
function generateSignature(string $date, string $tokenSecret): string
{
    $key = substr(hash('sha256', $tokenSecret), 0, 32);
    $iv = substr(hash('sha256', hash('sha256', $tokenSecret)), 0, 16);
    return openssl_encrypt($date, 'aes-256-cbc', $key, 0, $iv);
}
 
$date = "2026-05-20 14:30:00";
$tokenSecret = "votre-token-secret";
$signature = generateSignature($date, $tokenSecret);
echo $signature;

2.1.2 Génération de la signature en Python

snippet.python

import hashlib
from Crypto.Cipher import AES
import base64
 
def generate_signature(date: str, token_secret: str) -> str:
    key = hashlib.sha256(token_secret.encode()).hexdigest()[:32]
    iv = hashlib.sha256(hashlib.sha256(token_secret.encode()).hexdigest().encode()).hexdigest()[:16]
 
    cipher = AES.new(key.encode(), AES.MODE_CBC, iv.encode())
    pad_len = 16 - (len(date) % 16)
    padded_date = date + chr(pad_len) * pad_len
    encrypted = cipher.encrypt(padded_date.encode())
 
    return base64.b64encode(encrypted).decode()
 
date = "2026-05-20 14:30:00"
token_secret = "votre-token-secret"
signature = generate_signature(date, token_secret)
print(signature)

2.1.3 Génération de la signature en JavaScript

snippet.javascript

const crypto = require('crypto');
 
function generateSignature(date, tokenSecret) {
    const key = crypto.createHash('sha256').update(tokenSecret).digest('hex').slice(0, 32);
    const fullHash = crypto.createHash('sha256').update(tokenSecret).digest('hex');
    const iv = crypto.createHash('sha256').update(fullHash).digest('hex').slice(0, 16);
 
    const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
    let encrypted = cipher.update(date, 'utf8', 'base64');
    encrypted += cipher.final('base64');
 
    return encrypted;
}
 
const date = "2026-05-20 14:30:00";
const tokenSecret = "votre-token-secret";
const signature = generateSignature(date, tokenSecret);
console.log(signature);

2.1.4 Génération de la signature en Java

snippet.java

import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Base64;
 
public class SignatureGenerator {
    private static String bytesToHex(byte[] bytes) {
        StringBuilder sb = new StringBuilder();
        for (byte b : bytes) sb.append(String.format("%02x", b));
        return sb.toString();
    }
 
    public static String generateSignature(String date, String tokenSecret) throws Exception {
        MessageDigest sha256 = MessageDigest.getInstance("SHA-256");
        String fullHash = bytesToHex(sha256.digest(tokenSecret.getBytes(StandardCharsets.UTF_8)));
        String key = fullHash.substring(0, 32);
        sha256.reset();
        String iv = bytesToHex(sha256.digest(fullHash.getBytes(StandardCharsets.UTF_8))).substring(0, 16);
 
        Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
        cipher.init(Cipher.ENCRYPT_MODE,
                new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "AES"),
                new IvParameterSpec(iv.getBytes(StandardCharsets.UTF_8)));
        byte[] encrypted = cipher.doFinal(date.getBytes(StandardCharsets.UTF_8));
 
        return Base64.getEncoder().encodeToString(encrypted);
    }
}

2.2 Déchiffrement des réponses

En dehors des routes d'authentification (/api/login et /api/refresh_token), toutes les réponses de l'API sont chiffrées. Il faut donc les déchiffrer pour pouvoir lire la réponse.

Le paramètre date est obligatoire.

Algorithme de chiffrement des réponses

Élément	Valeur
—	—
Algorithme	AES-256-CBC
Clé	SHA256(`date` + `tokenSecret`)
IV	16 premiers octets du SHA256 de la clé
Encodage Base64

2.2.1 Déchiffrement des réponses en PHP

snippet.php

<?php
 
function decryptResponse(string $encryptedData, string $date, string $tokenSecret): array
{
    // Décodage Base64
    $encrypted = base64_decode($encryptedData);
 
    // Génération de la clé (SHA256 de date + tokenSecret)
    $key = hash('sha256', $date . $tokenSecret, true);
 
    // Génération de l'IV (16 premiers octets du SHA256 de la clé)
    $iv = substr(hash('sha256', $key, true), 0, 16);
 
    // Déchiffrement AES-256-CBC
    $decrypted = openssl_decrypt($encrypted, 'aes-256-cbc', $key, OPENSSL_RAW_DATA, $iv);
 
    // Conversion JSON en tableau
    return json_decode($decrypted, true);
}
 
$encryptedResponse = "U2FsdGVkX1+abc123...";
$date = "2026-05-20 14:30:00";
$tokenSecret = "votre-token-secret";
 
$data = decryptResponse($encryptedResponse, $date, $tokenSecret);
print_r($data);

2.2.2 Déchiffrement en Python

snippet.python

import base64
import hashlib
import json
from Crypto.Cipher import AES
 
def decrypt_response(encrypted_data: str, date: str, token_secret: str) -> dict:
    # Décodage Base64
    encrypted = base64.b64decode(encrypted_data)
 
    # Génération de la clé
    key = hashlib.sha256((date + token_secret).encode()).digest()
 
    # Génération de l'IV
    iv = hashlib.sha256(key).digest()[:16]
 
    # Déchiffrement AES-256-CBC
    cipher = AES.new(key, AES.MODE_CBC, iv)
    decrypted = cipher.decrypt(encrypted)
 
    # Suppression du padding PKCS7
    padding_len = decrypted[-1]
    decrypted = decrypted[:-padding_len]
 
    return json.loads(decrypted.decode('utf-8'))
 
# Exemple d'utilisation
# pip install pycryptodome
encrypted_response = "U2FsdGVkX1+abc123..."  # Réponse chiffrée de l'API
date = "2026-05-20 14:30:00"                  # Date envoyée dans la requête
token_secret = "votre-token-secret"           # Votre clé secrète API
 
data = decrypt_response(encrypted_response, date, token_secret)
print(data)

2.2.3 Déchiffrement en JavaScript

snippet.javascript

const crypto = require('crypto');
 
function decryptResponse(encryptedData, date, tokenSecret) {
    // Décodage Base64
    const encrypted = Buffer.from(encryptedData, 'base64');
 
    // Génération de la clé
    const key = crypto.createHash('sha256').update(date + tokenSecret).digest();
 
    // Génération de l'IV
    const iv = crypto.createHash('sha256').update(key).digest().slice(0, 16);
 
    // Déchiffrement AES-256-CBC
    const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
    let decrypted = decipher.update(encrypted);
    decrypted = Buffer.concat([decrypted, decipher.final()]);
 
    return JSON.parse(decrypted.toString('utf-8'));
}
 
// Exemple d'utilisation
const encryptedResponse = "U2FsdGVkX1+abc123..."; // Réponse chiffrée de l'API
const date = "2026-05-20 14:30:00";                // Date envoyée dans la requête
const tokenSecret = "votre-token-secret";          // Votre clé secrète API
 
const data = decryptResponse(encryptedResponse, date, tokenSecret);
console.log(data);

2.2.4 Déchiffrement en Java

snippet.java

import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Arrays;
import java.util.Base64;
 
public class ApiDecrypter {
 
    public static String decryptResponse(String encryptedData, String date, String tokenSecret) throws Exception {
        // Décodage Base64
        byte[] encrypted = Base64.getDecoder().decode(encryptedData);
 
        // Génération de la clé (SHA256 de date + tokenSecret)
        MessageDigest sha256 = MessageDigest.getInstance("SHA-256");
        byte[] key = sha256.digest((date + tokenSecret).getBytes(StandardCharsets.UTF_8));
 
        // Génération de l'IV (16 premiers octets du SHA256 de la clé)
        byte[] iv = Arrays.copyOf(sha256.digest(key), 16);
 
        // Déchiffrement AES-256-CBC
        Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
        cipher.init(Cipher.DECRYPT_MODE, new SecretKeySpec(key, "AES"), new IvParameterSpec(iv));
        byte[] decrypted = cipher.doFinal(encrypted);
 
        return new String(decrypted, StandardCharsets.UTF_8);
    }
}
 
    // Exemple d'utilisation
    public static void main(String[] args) throws Exception {
        String encryptedResponse = "U2FsdGVkX1+abc123..."; // Réponse chiffrée de l'API
        String date = "2026-05-20 14:30:00";                // Date envoyée dans la requête
        String tokenSecret = "votre-token-secret";          // Votre clé secrète API
 
        String json = decryptResponse(encryptedResponse, date, tokenSecret);
        System.out.println(json);
    }

3. Endpoints API

3.1 Vérification d'identité PVID

Cette section concerne les 2 méthodes permettant de générer un lien PVID et de récupérer les résultats d'une vérification d'identité après verdict.

POST /api/pvid | Générer un lien PVID

Voir dans le Swagger

Générer un lien PVID à transmettre à un utilisateur pour qu'il puisse effectuer le parcours de vérification d'identité à distance.

Paramètres

Paramètre	Type	Description	Requis
—	—	—	—
`date`	string	Date pour chiffrement	✅
`customerEmail`	string	Email de l'utilisateur à vérifier	✅
`urlAfterSuccess`	string	URL de redirection après succès	✅
`urlAfterFailOrAbort`	string	URL de redirection en cas d'échec/abandon	✅
`isPriority`	integer	Traitement Express (0 ou 1). Surcoût applicable	❌
`linkValiditySharing`	integer	Durée de validité en minutes (max 60)	❌
`disableLinkSharing`	integer	Désactive le partage du lien via SMS/Qr-code (0 ou 1)	❌
`addUserAlertScreen`	integer	Afficher un écran d'alerte à l'utilisateur (0 ou 1)	❌
`addUserAlertText`	string	Ajouter un texte personnalisé sur l'écran d'alerte (5-120 caractères)	❌
`acceptedDocuments`	array	Documents acceptés (ex: `["FR-passport"]`)	❌
`webhook`	string	URL de webhook pour cette vérification (surcharge du webhook global, HTTPS obligatoire)	❌

Notes

Le paramètre webhook est optionnel : si non fourni, le webhook global de configuration sera utilisé
Conservez l'id de la vérification pour les requêtes ultérieures (récupération des résultats)
L'URL de la vérification expire après le délai spécifié (par défaut 60 minutes, max 60 minutes) ; passé ce délai il faut demander un nouveau lien PVID Cloud

Réponse | Succès

Code	Status
—	—
201	Created

Exemple de réponse

snippet.json

{
    "id": 987654,
    "isPriority": 0,
    "customerEmail": "jean.dupont@example.com",
    "date": "2026-05-20 14:25:00",
    "dateExpireLink": "2026-05-20 14:55:00",
    "url": "https://pvid-front.../verify/abc123xyz789",
    "urlAfterSuccess": "https://votre-site.com/verification/succes",
    "urlAfterFailOrAbort": "https://votre-site.com/verification/echec",
    "fullHashSha256": "a1b2c3d4e5f6..."
}

Réponse | Erreurs

Code	Status	Slug	Message
—	—	—	—
400	Bad Request	N/A	`Request payload contains invalid "form" data.`
400	Bad Request	`no_email`	`No email parameter found in your request`
400	Bad Request	`email_not_valid`	`This value is not a valid email address.`
400	Bad Request	`empty_url_after_success`	`No urlAfterSuccess found in your request`
400	Bad Request	`empty_url_after_fail_or_abort`	`No urlAfterFailOrAbort found in your request`
400	Bad Request	`alert_text_too_short`	`This value is too short. It should have 5 characters or more.`
400	Bad Request	`alert_text_too_long`	`This value is too long. It should have 120 characters or less.`

422	Unprocessable Entity	`webhook`	`The webhook URL must use HTTPS`
422	Unprocessable Entity	`linkValiditySharing`	`This value should be of type int.`
422	Unprocessable Entity	`linkValiditySharing`	`This value should be positive.`
422	Unprocessable Entity	`disableLinkSharing`	`This value should be of type int.`
422	Unprocessable Entity	`disableLinkSharing`	`Values accepted : 0, 1.`
422	Unprocessable Entity	`addUserAlertScreen`	`This value should be of type int.`
422	Unprocessable Entity	`addUserAlertScreen`	`Values accepted : 0, 1.`
422	Unprocessable Entity	`acceptedDocuments`	`This value is not valid.`
422	Unprocessable Entity	`isPriority`	`This value should be of type int.`
422	Unprocessable Entity	`isPriority`	`Values accepted : 0, 1.`

400	Bad Request	`invalid_date`	`Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)`
400	Bad Request	`empty_date`	`No date parameter found in your request`
400	Bad Request	`expired_date`	`Given datetime is older than current datetime`
400	Bad Request	`date_in_future`	`Given datetime must be set between call submission and +10 minutes`
400	Bad Request	`validation_error`	`Signature verification failed`
400	Bad Request	`failed_signature`	`Signature verification failed`
401	Unauthorized	N/A	`JWT Token not found`
401	Unauthorized	N/A	`Expired JWT Token`
401	Unauthorized	`user_not_exist`	`Unknown user`
500	Bad Request	`internal_server_error`	`Internal server error`

GET /api/pvid/{id} | Récupérer les résultats d'une vérification PVID

Voir dans le Swagger

Récupérer les informations d'un ID PVID donné.

Réponse | Vérification validée

Code	Status
—	—
200	OK

Exemple de réponse

snippet.json

{
    "id": 987654,
    "dateAdded": "2026-05-20 14:25:00",
    "verdictDate": "2026-05-20 15:30:00",
    "status": "done",
    "verdict": "validated",
    "document": {
        "type": "ID_CARD",
        "emitCountry": "FR",
        "documentNumber": "AB1234567",
        "documentNumberLast4": "4567",
        "emitDate": "2020-01-15",
        "expirationDate": "2030-01-15",
        "holderFirstname": "Jean",
        "holderLastname": "DUPONT",
        "birthdate": "1985-06-20",
        "holderNationality": "FR",
        "holderGender": "M",
        "holderBirthplace": "Paris",
        "mrz": "IDFRADUPONT<<JEAN..."
    },
    "files": {
        "availableUntil": "2026-06-20 15:30:00",
        "front": "https://storage.../front.jpg",
        "back": "https://storage.../back.jpg",
        "biometry": "https://storage.../bio.jpg"
    }
}

Réponse | Vérification refusée

Code	Status
—	—
200	OK

Exemple de réponse

snippet.json

{
    "id": 987654,
    "dateAdded": "2026-05-20 14:25:00",
    "verdictDate": "2026-05-20 15:30:00",
    "status": "done",
    "verdict": "refused",
    "abortedReason": null,
    "refusalReasons": [
        {
            "slug": "doc_is_expired",
            "text": "Les documents que vous nous avez présentés sont expirés. Il faut impérativement présenter une pièce d'identité en cours de validité"
        }
    ]
}

Voir la liste complète des motifs d'abandon

Réponse | Vérification expirée

Code	Status
—	—
200	OK

Exemple de réponse

snippet.json

{
    "id": 987654,
    "dateAdded": "2026-05-20 14:25:00",
    "verdictDate": "2026-05-20 15:25:00",
    "status": "expired",
    "verdict": null,
    "abortedReason": "expired_link",
    "refusalReasons": null
}

Réponse | Vérification abandonnée

Code	Status
—	—
200	OK

Exemple de réponse

snippet.json

{
    "id": 987654,
    "dateAdded": "2026-05-20 14:25:00",
    "verdictDate": "2026-05-20 14:35:00",
    "status": "aborted",
    "verdict": null,
    "abortedReason": "canceled",
    "refusalReasons": null
}

Voir la liste complète des motifs d'abandon

Réponse | Vérification en cours

Code	Status
—	—
200	OK

Exemple de réponse

snippet.json

{
    "id": 987654,
    "dateAdded": "2026-05-20 14:25:00",
    "verdictDate": null,
    "status": "currently_created",
    "verdict": null,
    "abortedReason": null,
    "refusalReasons": null
}

Réponse | Erreurs

Code	Status	Slug	Message
—	—	—	—
400	Bad Request	`invalid_date`	`Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)`
400	Bad Request	`empty_date`	`No date parameter found in your request`
400	Bad Request	`expired_date`	`Given datetime is older than current datetime`
400	Bad Request	`date_in_future`	`Given datetime must be set between call submission and +10 minutes`
400	Bad Request	`validation_error`	`Signature verification failed`
400	Bad Request	`failed_signature`	`Signature verification failed`
401	Unauthorized	N/A	`JWT Token not found`
401	Unauthorized	N/A	`Expired JWT Token`
401	Unauthorized	`user_not_exist`	`Unknown user`
500	Bad Request	`internal_server_error`	`Internal server error`

3.2 Configuration du parcours PVID

Cette section concerne les méthodes et les endpoints permettant de personnaliser votre parcours PVID.

La personnalisation du parcours concerne les éléments suivants,

graphique : logo, couleurs des textes/titres/boutons, favicon
technique : url de webhook
règlementaire : liste des titres acceptés
anti-fraude renforcé : écran d'alerte utilisateur, empêcher le partage du lien PVID

GET /api/configs | Obtenir la configuration PVID

Voir dans le Swagger

Récupérer les paramètres de la personnalisation actuelle.

Paramètres

Paramètre	Type	Description	Requis
—	—	—	—
`date`	string	Date pour le chiffrement (YYYY-MM-DD HH:mm:ss)	✅

Réponse | Succès

Code	Status
—	—
200	OK

Exemple de réponse

snippet.json

{
    "webhook": "https://api.votre-domaine.com/pvid/webhook",
    "linkValiditySharing": 60,
    "disableLinkSharing": 0,
    "addUserAlertScreen": 1,
    "addUserAlertText": "<b>Attention</b>",
    "titleColor": "#003366",
    "textColor": "#333333",
    "linkColorText": "#0066CC",
    "buttonColorText": "#FFFFFF",
    "buttonColorBackground": "#003366",
    "ghostButtonColor": "#003366",
    "acceptedDocuments": [...],
    "logo": "data:image/png;base64,...",
    "favicon": "data:image/x-icon;base64,..."
}

Réponse | Erreurs

Code	Status	Slug	Message
—	—	—	—
400	Bad Request	`invalid_date`	`Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)`
400	Bad Request	`empty_date`	`No date parameter found in your request`
400	Bad Request	`expired_date`	`Given datetime is older than current datetime`
400	Bad Request	`date_in_future`	`Given datetime must be set between call submission and +10 minutes`
400	Bad Request	`validation_error`	`Signature verification failed`
400	Bad Request	`failed_signature`	`Signature verification failed`
401	Unauthorized	N/A	`JWT Token not found`
401	Unauthorized	N/A	`Expired JWT Token`
401	Unauthorized	`user_not_exist`	`Unknown user`
500	Bad Request	`internal_server_error`	`Internal server error`

PUT /api/configs | Remplacer la configuration PVID

Voir dans le Swagger

Méthode permettant de remplacer entièrement la configuration actuelle de votre PVID.

Attention : cette méthode remplacera l'ensemble des données de configuration en place. Pour effectuer une modification partielle de la configuration utiliser la méthode “PATCH” de mise à jour de la configuration.

Paramètres

Paramètre	Type	Description	Requis
—	—	—	—
`webhook`	string	URL webhook (HTTPS obligatoire)	❌
`titleColor`	string	Couleur titres (#XXXXXX)	❌
`textColor`	string	Couleur textes (#XXXXXX)	❌
`linkColorText`	string	Couleur liens (#XXXXXX)	❌
`buttonColorText`	string	Couleur texte boutons (#XXXXXX)	❌
`buttonColorBackground`	string	Couleur fond boutons (#XXXXXX)	❌
`ghostButtonColor`	string	Couleur boutons fantômes (#XXXXXX)	❌
`linkValiditySharing`	integer	Validité du lien en minutes (max: 60)	❌
`disableLinkSharing`	integer	Désactiver partage (0 ou 1)	❌
`addUserAlertScreen`	integer	Écran d'alerte fraude (0 ou 1)	❌
`addUserAlertText`	string	Texte alerte (5-120 car.)	❌
`acceptedDocuments`	array	Documents acceptés	❌
`date`	string	Date chiffrement	✅

Réponse | Succès

Code	Status
—	—
201	OK

Même format que GET /api/configs

Réponse | Erreurs

Code	Status	Slug	Message
—	—	—	—
400	Bad Request	`alert_text_too_short`	`The alert's text you submitted is too short (less than 5 characters)`
400	Bad Request	`alert_text_too_long`	`The alert's text you submitted is too long (more than 120 characters)`
422	Unprocessable Entity	champ en erreur parmi `titleColor`, `textColor`, `linkColorText`, `buttonColorText`, `buttonColorBackground`, `ghostButtonColor`	`This value is not a valid CSS color`
422	Unprocessable Entity	`webhook`	`The webhook URL must use HTTPS`
422	Unprocessable Entity	`linkValiditySharing`	`This value should be of type int`
422	Unprocessable Entity	`linkValiditySharing`	`This value should be positive`
422	Unprocessable Entity	`disableLinkSharing`	`This value should be of type int`
422	Unprocessable Entity	`disableLinkSharing`	`Values accepted : 0, 1`
422	Unprocessable Entity	`addUserAlertScreen`	`This value should be of type int`
422	Unprocessable Entity	`addUserAlertScreen`	`Values accepted : 0, 1`

400	Bad Request	`invalid_date`	`Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)`
400	Bad Request	`empty_date`	`No date parameter found in your request`
400	Bad Request	`expired_date`	`Given datetime is older than current datetime`
400	Bad Request	`date_in_future`	`Given datetime must be set between call submission and +10 minutes`
400	Bad Request	`validation_error`	`Signature verification failed`
400	Bad Request	`failed_signature`	`Signature verification failed`
401	Unauthorized	N/A	`JWT Token not found`
401	Unauthorized	N/A	`Expired JWT Token`
401	Unauthorized	`user_not_exist`	`Unknown user`
500	Bad Request	`internal_server_error`	`Internal server error`

PATCH /api/configs | Mettre à jour la configuration PVID

Voir dans le Swagger

Méthode permettant de mettre à jour partiellement votre configuration PVID (seuls les champs fournis sont modifiés).

Paramètres

Champ	Type	Description	Requis
—	—	—	—
`webhook`	string	URL webhook (HTTPS obligatoire)	❌
`titleColor`	string	Couleur titres (#XXXXXX)	❌
`textColor`	string	Couleur textes (#XXXXXX)	❌
`linkColorText`	string	Couleur liens (#XXXXXX)	❌
`buttonColorText`	string	Couleur texte boutons (#XXXXXX)	❌
`buttonColorBackground`	string	Couleur fond boutons (#XXXXXX)	❌
`ghostButtonColor`	string	Couleur boutons fantômes (#XXXXXX)	❌
`linkValiditySharing`	integer	Validité du lien en minutes (max: 60)	❌
`disableLinkSharing`	integer	Désactiver partage (0 ou 1)	❌
`addUserAlertScreen`	integer	Écran d'alerte fraude (0 ou 1)	❌
`addUserAlertText`	string	Texte alerte (5-120 car.)	❌
`acceptedDocuments`	array	Documents acceptés	❌
`date`	string	Date chiffrement	✅

Réponse | Succès

Code	Status
—	—
201	OK

Même format que GET /api/configs

Réponse | Erreurs

Code	Status	Slug	Message
—	—	—	—
400	Bad Request	`alert_text_too_short`	`The alert's text you submitted is too short (less than 5 characters)`
400	Bad Request	`alert_text_too_long`	`The alert's text you submitted is too long (more than 120 characters)`
422	Unprocessable Entity	champ en erreur parmi `titleColor`, `textColor`, `linkColorText`, `buttonColorText`, `buttonColorBackground`, `ghostButtonColor`	`This value is not a valid CSS color`
422	Unprocessable Entity	`webhook`	`The webhook URL must use HTTPS`
422	Unprocessable Entity	`linkValiditySharing`	`This value should be of type int`
422	Unprocessable Entity	`linkValiditySharing`	`This value should be positive`
422	Unprocessable Entity	`disableLinkSharing`	`This value should be of type int`
422	Unprocessable Entity	`disableLinkSharing`	`Values accepted : 0, 1`
422	Unprocessable Entity	`addUserAlertScreen`	`This value should be of type int`
422	Unprocessable Entity	`addUserAlertScreen`	`Values accepted : 0, 1`

400	Bad Request	`invalid_date`	`Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)`
400	Bad Request	`empty_date`	`No date parameter found in your request`
400	Bad Request	`expired_date`	`Given datetime is older than current datetime`
400	Bad Request	`date_in_future`	`Given datetime must be set between call submission and +10 minutes`
400	Bad Request	`validation_error`	`Signature verification failed`
400	Bad Request	`failed_signature`	`Signature verification failed`
401	Unauthorized	N/A	`JWT Token not found`
401	Unauthorized	N/A	`Expired JWT Token`
401	Unauthorized	`user_not_exist`	`Unknown user`
500	Bad Request	`internal_server_error`	`Internal server error`

DELETE /api/configs | Réinitialiser la configuration

Voir dans le Swagger

Méthode permettant de réinitialiser la configuration de votre PVID pour revenir au paramètres par défaut.

Attention : cette requête supprime tous vos paramètres personnalisés

Paramètres

Paramètre	Type	Description	Requis
—	—	—	—
`date`	string	Date pour le chiffrement	✅

Réponse | Succès

Code	Status
—	—
204	No Content

Réponse | Erreurs

Code	Status	Slug	Message
—	—	—	—
400	Bad Request	`invalid_date`	`Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)`
400	Bad Request	`empty_date`	`No date parameter found in your request`
400	Bad Request	`expired_date`	`Given datetime is older than current datetime`
400	Bad Request	`date_in_future`	`Given datetime must be set between call submission and +10 minutes`
400	Bad Request	`validation_error`	`Signature verification failed`
400	Bad Request	`failed_signature`	`Signature verification failed`
401	Unauthorized	N/A	`JWT Token not found`
401	Unauthorized	N/A	`Expired JWT Token`
401	Unauthorized	`user_not_exist`	`Unknown user`
500	Bad Request	`internal_server_error`	`Internal server error`

GET /api/configs/documents | Liste des documents d'identité acceptés

Voir dans le Swagger

Endpoint permettant de récupérer la liste des documents d'identité acceptés par PVID.

Paramètres

Paramètre	Type	Description	Requis
—	—	—	—
`date`	string	Date pour le chiffrement	✅

Réponse | Succès

Code	Status
—	—
200	OK

Exemple de réponse

snippet.json

{
    "allowedDocuments": [
        { "code": "FR", "name": "France", "documents": ["passport", "id_card", "residence_permit"] },
        { "code": "BE", "name": "Belgium", "documents": ["passport", "id_card"] }
    ]
}

Réponse | Erreurs

Code	Status	Slug	Message
—	—	—	—
400	Bad Request	`invalid_date`	`Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)`
400	Bad Request	`empty_date`	`No date parameter found in your request`
400	Bad Request	`expired_date`	`Given datetime is older than current datetime`
400	Bad Request	`date_in_future`	`Given datetime must be set between call submission and +10 minutes`
400	Bad Request	`validation_error`	`Signature verification failed`
400	Bad Request	`failed_signature`	`Signature verification failed`
401	Unauthorized	N/A	`JWT Token not found`
401	Unauthorized	N/A	`Expired JWT Token`
401	Unauthorized	`user_not_exist`	`Unknown user`
500	Bad Request	`internal_server_error`	`Internal server error`

POST /api/configs/files | Mettre à jour les fichiers

Voir dans le Swagger

Méthode permettant de mettre à jour le logo et le favicon du parcours PVID.

Cette requête utilise le multipart/form-data pour l'upload des fichiers.

Paramètres

Champ	Type	Description	Requis
—	—	—	—
`logo`	file	Image PNG/JPEG (hauteur max: 64px)	❌
`favicon`	file	Image PNG/JPEG/ICO (hauteur max: 64px)	❌
`date`	string	Date pour chiffrement (YYYY-MM-DD HH:mm:ss)	✅

Réponse | Succès

Code	Status
—	—
201	OK

Même format que GET /api/configs

Réponse | Erreurs

Code	Status	Slug	Message
—	—	—	—
422	Unprocessable Entity	`logo.path`	`This value should be of type string`
422	Unprocessable Entity	`favicon.path`	`This value should be of type string`
400	Bad Request	`invalid_date`	`Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)`
400	Bad Request	`empty_date`	`No date parameter found in your request`
400	Bad Request	`expired_date`	`Given datetime is older than current datetime`
400	Bad Request	`date_in_future`	`Given datetime must be set between call submission and +10 minutes`
400	Bad Request	`validation_error`	`Signature verification failed`
400	Bad Request	`failed_signature`	`Signature verification failed`
401	Unauthorized	N/A	`JWT Token not found`
401	Unauthorized	N/A	`Expired JWT Token`
401	Unauthorized	`user_not_exist`	`Unknown user`
500	Bad Request	`internal_server_error`	`Internal server error`

DELETE /api/configs/files | Supprimer les fichiers

Voir dans le Swagger

Méthode permettant de supprimer vos logo/favicon du parcours PVID pour remettre les logo/favicon par défaut.

Attention : cette requête supprime votre logo et votre favicon.

Paramètres

Paramètre	Type	Description	Requis
—	—	—	—
`date`	string	Date pour le chiffrement (YYYY-MM-DD HH:mm:ss)	✅

Réponse | Succès

Code	Status
—	—
204	No Content

Réponse | Erreurs

Code	Status	Slug	Message
——–	—–	—–	——–
400	Bad Request	`invalid_date`	`Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)`
400	Bad Request	`empty_date`	`No date parameter found in your request`
400	Bad Request	`expired_date`	`Given datetime is older than current datetime`
400	Bad Request	`date_in_future`	`Given datetime must be set between call submission and +10 minutes`
400	Bad Request	`validation_error`	`Signature verification failed`
400	Bad Request	`failed_signature`	`Signature verification failed`
401	Unauthorized	N/A	`JWT Token not found`
401	Unauthorized	N/A	`Expired JWT Token`
401	Unauthorized	`user_not_exist`	`Unknown user`
500	Bad Request	`internal_server_error`	`Internal server error`

3.3 Tests de compatibilité de l'appareil de l'utilisateur

Cette section concerne les endpoints permettant de tester, en amont du parcours PVID, certains paramètres de compatibilité de l'appareil de l'utilisateur.

GET /api/browser/list | Navigateurs compatibles

Voir dans le Swagger

Méthode permettant de récupérer la liste des navigateurs, et leurs versions, pris en charge par le PVID.

Paramètres

Paramètre	Type	Description	Requis
—	—	—	—
`date`	string	Date pour le chiffrement (YYYY-MM-DD HH:mm:ss)	✅

Réponse | Succès

Code	Status
—	—
201	OK

Exemple de réponse

snippet.json

{
    "safari": "14",
    "chrome": "110",
    "firefox": "66",
    "samsung": "6",
    "opera": "73",
    "edge": "79",
    "miui": "13.21"
}

GET /api/browser/check | Vérifier un navigateur

Voir dans le Swagger

Méthode permettant de tester la compatibilité du navigateur de l'utilisateur.

Paramètres

Paramètre	Type	Description	Requis
—	—	—	—
`name`	string	Nom du navigateur	✅
`version`	string	Version du navigateur	✅

Réponse | Succès

Code	Status
—	—
201	OK

Exemple de réponse

snippet.json

{ "result": "The user's browser can be used for a PVID" }

Réponse | Erreurs

Code	Slug	Message
—	—	—
400	`missing_browser_name`	`The browser's name is missing`
400	`missing_browser_version`	`The browser's version is missing`
400	`unknown_browser_name`	`The browser's name is unknown`
400	`invalid_browser_version`	`The browser's version is invalid`
400	`empty_date`	`No date parameter found in your request`
400	`invalid_date`	`Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)`
400	`expired_date`	`Given datetime is older than current datetime`
400	`date_in_future`	`Given datetime must be set between call submission and +10 minutes`
401	`error`	`JWT Token not found`

GET /api/camera/resolution | Résolution de la caméra

Voir dans le Swagger

Méthode permettant de récupérer la résolution minimale requise pour la caméra de l'appareil de l'utilisateur.

Paramètres

Paramètre	Type	Description	Requis
—	—	—	—
`date`	string	Date pour le chiffrement (YYYY-MM-DD HH:mm:ss)	✅

Réponse | Succès

Code	Status
——–	—–
200	OK

Exemple de réponse

snippet.json

{ "height": 720, "width": 1280 }

Réponse | Erreurs

Code	Status	Slug	Message
—	—	—	—
400	Bad Request	`invalid_date`	`Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)`
400	Bad Request	`empty_date`	`No date parameter found in your request`
400	Bad Request	`expired_date`	`Given datetime is older than current datetime`
400	Bad Request	`date_in_future`	`Given datetime must be set between call submission and +10 minutes`
400	Bad Request	`validation_error`	`Signature verification failed`
400	Bad Request	`failed_signature`	`Signature verification failed`
401	Unauthorized	N/A	`JWT Token not found`
401	Unauthorized	N/A	`Expired JWT Token`
401	Unauthorized	`user_not_exist`	`Unknown user`
500	Bad Request	`internal_server_error`	`Internal server error`

4. Webhooks

Les événements webhook permettent au métier d'être informé en temps réel de chaque changement d'état d'un PVID.

4.1 Configuration

Pour recevoir des événements webhook il faut renseigner une URL en HTTPS dans le paramètre webhook des endpoints POST /api/pvid, PUT /api/configs ou PATCH /api/configs.

4.2 Réponse

Lors de la réception de l'événement vous devez nous retourner un code HTTP 200.

Si le code HTTP de réponse de votre part est différent, nous allons effectuer jusqu'à 48 tentatives. Nous augmenterons les timeout au fur et à mesure de ces tentatives selon le fonctionnement suivant,

1ère à 9ème tentative : 2.5s timeout
10ème à 19ème tentative : 4.5s timeout
20ème à 29ème tentative : 6.5s timeout
30ème à 39ème tentative : 8.5s timeout
40ème à 48ème tentative : 11s timeout

4.3 Evénements

Les événements transmis par PVID sont les suivants,

Événement	Description	Déclencheur
—	—	—
`validated`	PVID validé	L'identité a été vérifiée avec succès
`refused`	PVID refusé	L'identité n'a pas pu être vérifiée
`aborted`	PVID abandonné	L'utilisateur a abandonné le parcours
`expired`	PVID expiré	Le lien de vérification a expiré

4.4 Payload

Les informations des événements webhook sont transmises au format Json.

Exemple de payload

snippet.json

{
    "pvid_id": "987654",
    "event": "validated",
    "event_date": "2026-05-20T15:30:00+00:00"
}

Champ	Type	Description
—	—	—
`pvid_id`	string	Identifiant unique de la vérification PVID
`event`	string	Type d'événement (`validated`, `refused`, `aborted`, `expired`)
`event_date`	string	Date et heure de l'événement (format ISO 8601)

5. Annexes

5.1 Diagramme de séquence

Voici un diagramme de séquence simplifié de l'utilisation de PVID Cloud.

sequenceDiagram participant Client as Serveur Client participant API as API PVID Cloud participant Browser as Navigateur Utilisateur rect rgb(200, 220, 255) Note over Client,Browser: Phase 1 : Initialisation & Authentification Client->>API: 1. POST /api/login Note right of Client: Identifiants API-->>Client: 2. access_token + refresh_token end rect rgb(200, 250, 200) Note over Client,Browser: Phase 2 : Configuration (optionnel) Client->>API: 3. GET /api/configs Note right of Client: Bearer + date API-->>Client: 4. Configuration (chiffrée AES-256-CBC) end rect rgb(255, 240, 200) Note over Client,Browser: Phase 3 : Création Vérification Client->>API: 5. POST /api/pvid Note right of Client: idUser, email, URLs, docs, webhook, date API-->>Client: 6. ID vérification + URL PVID Client->>Browser: 7. Redirection vers URL PVID Note right of Client: Valide 30-60 minutes end rect rgb(255, 220, 220) Note over Browser: Phase 4 : Parcours Utilisateur Browser->>Browser: 8. Capture document + selfie Note over Browser: Hors API Browser-->>Client: 9. Callback (succès ou échec) end rect rgb(220, 240, 220) Note over Client,API: Phase 5 : Notifications & Résultats API->>Client: 10. Webhook : status, verdict, event_date Note right of API: Notification en temps réel Client-->>API: 11. HTTP 2xx (accusé de réception) Client->>API: 12. GET /api/pvid/{id} Note right of Client: Bearer + date API-->>Client: 13. Résultats (verdict, document, fichiers chiffrés) end

5.2 Documents d'identité

Format

La nomenclature des différents documents d'identité accepté par le PVID Docaposte est la suivante : {CODE_PAYS}-{TYPE_DOCUMENT}.

Ce format est à utiliser dans les endpoints permettant de personnaliser les titres acceptés par le PVID.

Il sera également utilisé dans l'ensemble des retours de l'API PVID Cloud.

Exemples

FR-passport — Passeport français
FR-id_card — Carte d'identité française
BE-residence_permit — Titre de séjour belge

La liste complète des documents acceptés par pays est disponible via l'endpoint GET /api/configs/documents.

5.3 Motifs d'abandon

Ajout d'un paramètre dans l'URL d'abandon

Lorsque l'utilisateur est redirigé vers l'URL url_after_fail_or_abort transmis dans la requête de génération d'un lien PVID PVID Cloud rajoute un paramètre dans l'URL contenant le motif d'abandon du parcours.

Les motifs retournés sont les suivants,

Slug	Description
—	—
`canceled`	L'utilisateur a quitté le parcours inopinément (fermeture du navigateur, rafraichissement de la page, …)
`expired_link`	Le lien du PVID est expiré et ne permet plus d'effectuer le parcours
`no_camera`	L'utilisateur n'a pas donné accès à sa caméra
`camera_resolution`	La résolution de la caméra n'est pas suffisante
`browser_not_supported`	Le navigateur utilisé n'est pas accepté pour le PVID
`browser_version`	La version du navigateur utilisé n'est pas acceptée pour le PVID
`network`	La connexion internet de l'utilisateur est insuffisante
`document_not_accepted`	L'utilisateur ne possède aucun titre d'identité accepté pour le PVID
`recording_error`	Nous avons rencontré une difficulté lors de la capture vidéo

Exemple

L'accès à la caméra n'est pas autorisé : url_after_fail_or_abort?error=no_camera

Transmission via API

En plus d'être transmis dans l'URL url_after_fail_or_abort les motifs d'abandon sont également retournés via le paramètre abortedReason de la route GET /api/pvid/{id}.

5.4 Motifs de refus

Voici la liste des motifs de refus pour lesquels une vérification PVID peut être refusée.

Slug	Description
—	—
`document_capture_bad_quality`	Votre document d'identité n'a pas pu être analysé. Assurez-vous que votre pièce d'identité soit entièrement visible, bien cadrée et que la qualité vidéo permette de lire clairement les informations
`biometry_capture_bad_quality`	La vérification n'a pas pu aboutir en raison de problèmes liés à la qualité de l'enregistrement ou à la reconnaissance du visage
`document_not_accepted`	Le document présenté n'est pas accepté par notre service de vérification d'identité à distance
`document_expired`	Le document présenté est expiré
`document_not_allowed`	Votre document d'identité ne peut être accepté par nos services. Assurez-vous de présenter l'original (passeport, titre de séjour ou carte d'identité), en bon état sans étui ni obstruction visuelle.
`document_not_complete`	Votre document n'a pas pu être entièrement analysé car une face est manquante ou mal cadrée
`action_not_complete`	Les actions effectuées lors de la capture vidéo du document ou du visage n'ont pas été correctement réalisées et n'ont pas pu permettre la vérification de l'identité. Assurez-vous de bien respecter les consignes affichées lors du parcours (inclinaison et positionnement dans le cadre).
`biometry_not_conform`	Les conditions dans lesquelles vous avez effectué votre vérification d'identité ne permettent pas de la traiter. Assurez-vous que votre visage soit entièrement visible, sans lunettes de soleil, verres teintés ou masque.
`fraud_is_suspected`	Les conditions dans lesquelles vous avez effectué votre vérification d'identité ne permettent pas à notre service de la traiter
`period_expired`	Un problème technique a empêché le traitement de votre vérification d'identité dans les delais impartis
`technical_error`	Un problème technique a empêché le traitement de votre vérification d'identité