• ✅ Vérifications d'identité à distance conformes ANSSI.
• 📱 Capture biométrique et document via application web mobile sécurisée.
• 🔗 Intégration simple via API REST authentifiée.
• 📊 Suivi temps réel via webhooks événementiels.
• 🎨 Interface entièrement personnalisable à votre marque.
• 🔐 Chiffrement AES-256-CBC des données sensibles.

• Swagger API Intégration
• URL de base production :

  https://pvid-back.docaposte.fr/api

• URL de base intégration :

  https://pvid-back.pvid-integration.integration.idv-docaposte.com/api

1. Authentification : Authentification OAuth 2.0 avec tokens JWT (validité 5 min).
2. Configuration : Personnalisation couleurs, logo, favicon, documents acceptés.
3. Création vérification : Initiation d'un parcours PVID pour un utilisateur.
4. Résultats : Récupération statut et verdict (validé, refusé, expiré).
5. Chiffrement : Déchiffrement AES-256-CBC des réponses sensibles.
6. Tests compatibilité : Vérification navigateur, caméra et résolution.
7. Webhooks : Notifications asynchrones d'événements.

Cette section résume les 4 étapes obligatoires pour mettre en production votre intégration PVID Cloud. Une 5e étape (webhooks) est fortement recommandée pour optimiser votre architecture.

Objectif : Valider vos identifiants et générer un token JWT pour accéder à l'API.

Actions :

1. Obtenez vos identifiants (username/password) auprès du support technique 2. Testez l'endpoint de login en environnement d'intégration :

POST /api/login

3. Stockez le token d'accès et le refresh token de manière sécurisée (backend uniquement) 4. Implémentez la logique de rafraîchissement de token (validité 5 minutes) 5. Testez la gestion d'erreur d'authentification (401 Unauthorized)

Points de contrôle :

• ✅ Authentification réussie en intégration
• ✅ Token stocké côté serveur backend (jamais côté client)
• ✅ Logique de refresh_token en place
• ✅ Gestion des tokens expirés testée

Documentation complète : Section 1 — Authentification

Objectif : Être capable de déchiffrer les réponses sensibles de l'API.

Actions :

1. Choisissez votre langage de programmation (PHP, Python, JavaScript, Java, etc.) 2. Implémentez la fonction de déchiffrement AES-256-CBC selon votre stack 3. Testez le déchiffrement avec des réponses chiffrées en intégration 4. Validez que la clé de chiffrement est générée correctement : SHA256(date + tokenSecret) 5. Gérez les erreurs de déchiffrement (mauvaise clé, padding invalide, etc.)

Points de contrôle :

• ✅ Fonction de déchiffrement implémentée et testée
• ✅ Gestion des erreurs de déchiffrement
• ✅ Clé générée correctement avec votre tokenSecret
• ✅ Validation sur un exemple réel en intégration

Documentation complète : Section 4 — Chiffrement des réponses

Code d'exemple : Disponible en PHP, Python, JavaScript et Java

Objectif : Créer une vérification et obtenir l'URL à rediriger vers votre utilisateur.

Actions :

1. Collectez les informations utilisateur requises (idUser, email) 2. Définissez les URLs de redirection post-succès et post-échec 3. Créez une vérification :

POST /api/pvid

4. Stockez l'ID de la vérification (crucial pour récupérer les résultats plus tard) 5. Redirigez l'utilisateur vers l'URL fournie (valide 30-60 minutes) 6. Testez le flux complet sur 5 vérifications fictives en intégration

Paramètres obligatoires :

• idUser : Identifiant unique utilisateur (> 0)
• customerEmail : Email de l'utilisateur
• urlAfterSuccess : URL de redirection après succès
• urlAfterFailOrAbort : URL de redirection après échec/abandon
• date : Date actuelle (YYYY-MM-DD HH:mm:ss)

Points de contrôle :

• ✅ Vérification créée avec succès (statut 201)
• ✅ URL retournée ouverte correctement dans le navigateur
• ✅ ID de la vérification stocké de manière persistante
• ✅ Lien expirant après 60 minutes
• ✅ 5 vérifications de test réussies

Documentation complète : Section 5 — Initier une vérification

Objectif : Récupérer le verdict final et les données personnelles après vérification utilisateur.

Actions :

1. Attendez que l'utilisateur complète le parcours PVID 2. Récupérez l'ID de la vérification stocké à l'étape précédente 3. Appelez l'endpoint de résultats :

GET /api/pvid/{id}

4. Déchiffrez la réponse avec votre fonction AES-256-CBC (étape 2) 5. Traitez les 4 statuts possibles : done, expired, aborted, currently_created 6. Testez les 3 verdicts finaux : validated, refused, null

Statuts et verdicts possibles :

• Status = done + Verdict = validated → Identité vérifiée ✅
• Status = done + Verdict = refused → Identité rejetée ❌
• Status = expired → Lien expiré (rejouer depuis l'étape 3)
• Status = aborted → Utilisateur a quitté le parcours
• Status = currently_created → En attente (pas encore commencé)

Données retournées en cas de succès :

• Informations du document (type, numéro, dates, MRZ)
• Données de l'utilisateur (nom, prénom, date de naissance, nationalité)
• URLs des fichiers (front du titre, verso, biométrie/visage)
• Date d'expiration des fichiers (72 heures pour biométrie, 30 jours pour documents)

Points de contrôle :

• ✅ Récupération du verdict réussie pour les 3 cas (validated, refused, other)
• ✅ Déchiffrement des données sensibles fonctionnel
• ✅ Gestion des statuts intermédiaires testée
• ✅ Erreurs gérées (404, 403, 401)
• ✅ 5 tests de flux complet réussis (création → vérif → résultats)

Documentation complète : Section 6 — Récupérer les résultats

Objectif : Recevoir les notifications immédiatement au lieu de faire du polling sur l'API.

Pourquoi c'est recommandé :

• Réduit drastiquement la charge sur votre infrastructure (pas de polling)
• Vous recevez le verdict en temps réel (< 1 seconde après la décision)
• Évite les appels API inutiles et réduit vos coûts
• Permet une meilleure expérience utilisateur (pas d'attente)

Actions :

1. Implémentez un endpoint HTTP POST capable de recevoir les webhooks 2. Parsez le payload webhook (pvid_id, status, verdict, event_date) 3. Vérifiez l'authenticité du webhook (origine, signature si disponible) 4. Traitez l'événement de manière asynchrone (ne bloquez pas la réponse) 5. Retournez un code HTTP 2xx dans les 5 secondes 6. Testez l'endpoint webhook avec des appels manuels en intégration

Payload webhook reçu :

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

Points de contrôle :

• ✅ Endpoint webhook implémenté et accessible
• ✅ Réponse HTTP 2xx retournée dans les 5 secondes
• ✅ Payload parsé correctement
• ✅ Idempotence gérée (éviter les doublons)
• ✅ 10 webhooks de test reçus et traités

Documentation complète : Section 7 — Webhooks

Note importante : Sans webhooks, vous devrez implémenter du polling en appelant régulièrement

GET /api/pvid/{id}

pour vérifier si un verdict a été prononcé. Les webhooks éliminent cette nécessité.

Complétez cette checklist avant de demander l'accès production :

Légende : ✅ = Obligatoire | ⭐ = Fortement recommandé

Vous pouvez intégrer ces étapes après la mise en production :

Toutes les requêtes API authentifiées nécessitent un token JWT valide 5 minutes.

Voir dans le Swagger

Obtenez un token JWT pour accéder aux autres endpoints.

curl -X POST "https://pvid-back.docaposte.fr/api/login" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "votre-identifiant",
    "password": "votre-mot-de-passe"
  }'

curl -X POST "https://pvid-back.pvid-integration.integration.idv-docaposte.com/api/login" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "votre-identifiant",
    "password": "votre-mot-de-passe"
  }'

{
  "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"
}

• Cet appel doit être exécuté par votre serveur backend, jamais depuis le navigateur de l'utilisateur.
• 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.

Erreur (400) — Identifiants manquants :

{ "error": "Missing credentials" }

Erreur (401) — Identifiants invalides :

{ "error": "Invalid credentials or Keycloak error" }

Ajoutez cet header à toutes vos requêtes authentifiées :

ACCESS_TOKEN

Exemple complet :

curl -X GET "https://pvid-back.docaposte.fr/api/config?date=2026-05-20%2014:30:00" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "accept: application/json"

Obtenez un nouveau token d'accès sans vous reconnecter.

curl -X POST "https://pvid-back.docaposte.fr/api/refresh_token" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

{
  "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"
}

Erreur (400) — Refresh token manquant :

{ "error": "Missing refresh token" }

Erreur (400) — Refresh token invalide (configuration) :

{ "error": "Invalid refresh token" }

Erreur (401) — Refresh token invalide (Keycloak) :

{ "error": "Invalid credentials or Keycloak error" }

Avant de proposer PVID à vos utilisateurs, configurez votre branding et vos préférences.

Commencez par consulter quels documents vous pouvez accepter par pays.

curl -X GET "https://pvid-back.docaposte.fr/api/config/documents?date=2026-05-20%2014:30:00" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

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

Consultez votre configuration existante.

curl -X GET "https://pvid-back.docaposte.fr/api/config?date=2026-05-20%2014:30:00" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "accept: application/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": ["FR-passport", "FR-id_card"],
    "logo": "data:image/png;base64,...",
    "favicon": "data:image/x-icon;base64,..."
}

Erreur (400) — Date manquante :

{ "slug": "empty_date", "message": "No date parameter found in your request" }

Erreur (400) — Format de date invalide :

{ "slug": "invalid_date", "message": "Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)" }

Erreur (400) — Date expirée (date passée) :

{ "slug": "expired_date", "message": "Given datetime is older than current datetime" }

Erreur (400) — Date trop dans le futur (max +10 min) :

{ "slug": "date_too_far_in_future", "message": "The date parameter must not be more than 10 minutes in the future" }

Erreur (401) — Token invalide :

{ "error": "Invalid credentials or Keycloak error" }

Erreur (500) — Erreur serveur :

{ "slug": "internal_server_error", "message": "Internal server error" }

Configurez votre branding, vos documents acceptés et votre webhook global.

curl -X PUT "https://pvid-back.docaposte.fr/api/config" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": "https://api.votre-domaine.com/pvid/webhook",
    "titleColor": "#003366",
    "textColor": "#333333",
    "linkColorText": "#0066CC",
    "buttonColorText": "#FFFFFF",
    "buttonColorBackground": "#003366",
    "ghostButtonColor": "#003366",
    "linkValiditySharing": 60,
    "disableLinkSharing": 0,
    "addUserAlertScreen": 1,
    "addUserAlertText": "<b>Attention</b> vérification obligatoire",
    "acceptedDocuments": ["FR-passport", "FR-id_card"],
    "date": "2026-05-20 14:30:00"
  }'

Même format que GET

/api/config

Erreur (400) — Validation échouée :

{ "slug": "validation_error", "message": "Validation failed", "details": ["The webhook URL must use HTTPS"] }

Erreur (401) — Utilisateur inconnu :

{ "slug": "user_not_exist", "message": "Unknown user" }

Erreur (500) — Erreur serveur :

{ "slug": "internal_server_error", "message": "Internal server error" }

Modifie uniquement les champs fournis sans écraser la configuration existante.

curl -X PATCH "https://pvid-back.docaposte.fr/api/config" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "titleColor": "#FF6600",
    "buttonColorBackground": "#FF6600",
    "date": "2026-05-20 14:30:00"
  }'

Même format que GET

/api/config

Erreur (400) — Validation échouée :

{ "slug": "validation_error", "message": "Validation failed" }

Erreur (401) — Utilisateur inconnu :

{ "slug": "user_not_exist", "message": "Unknown user" }

Erreur (500) — Erreur serveur :

{ "slug": "internal_server_error", "message": "Internal server error" }

Téléchargez votre logo et favicon. Les fichiers doivent être convertis en base64.

curl -X POST "https://pvid-back.docaposte.fr/api/config/files" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg==",
    "favicon": "data:image/x-icon;base64,AAABAAEAEBAQAAEABAAoAQAAFgAAACgAAAAQAAAAIAAAAAEABAAAAAAAgAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAA/4QAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "date": "2026-05-20 14:30:00"
  }'

Même format que GET

/api/config

curl -X DELETE "https://pvid-back.docaposte.fr/api/config/files" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Aucun contenu retourné.

Supprime tous les paramètres personnalisés et restaure les valeurs par défaut.

curl -X DELETE "https://pvid-back.docaposte.fr/api/config?date=2026-05-20%2014:30:00" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Aucun contenu retourné.

Erreur (400) — Date invalide :

{ "slug": "invalid_date", "message": "Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)" }

Erreur (401) — Token invalide :

{ "error": "Invalid credentials or Keycloak error" }

Erreur (500) — Erreur serveur :

{ "slug": "internal_server_error", "message": "Internal server error" }

Avant de lancer vos utilisateurs en production, vérifiez la compatibilité de leurs navigateurs et caméras.

Consultez les versions minimales de navigateurs supportées.

curl -X GET "https://pvid-back.docaposte.fr/api/browser/list" \
  -H "accept: application/json"

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

Testez si la version du navigateur d'un utilisateur est compatible.

curl -X GET "https://pvid-back.docaposte.fr/api/browser/check?name=chrome&version=115.0.5790" \
  -H "accept: application/json"

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

{ "slug": "browser_not_supported", "message": "Le navigateur n'est pas supporté ou la version est trop ancienne" }

Erreur (400) — Paramètre manquant (name) :

{ "slug": "validation_error", "message": "Missing required parameter: name" }

Erreur (400) — Paramètre manquant (version) :

{ "slug": "validation_error", "message": "Missing required parameter: version" }

Erreur (400) — Navigateur invalide :

{ "slug": "validation_error", "message": "Invalid browser name" }

Récupère la résolution minimale requise pour la caméra.

curl -X GET "https://pvid-back.docaposte.fr/api/camera/resolution?date=2026-05-20%2014:30:00" \
  -H "accept: application/json"

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

Erreur (400) — Date invalide :

{ "slug": "invalid_date", "message": "Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)" }

Erreur (401) — Token invalide :

{ "error": "Invalid credentials or Keycloak error" }

Erreur (500) — Erreur serveur :

{ "slug": "internal_server_error", "message": "Internal server error" }

Certaines réponses de l'API sont chiffrées en AES-256-CBC pour protéger vos données personnelles.

date

tokenSecret

Paramètre obligatoire :

date

au format YYYY-MM-DD HH:mm:ss Validité : entre l'instant présent et 10 minutes plus tard (la date ne doit pas être antérieure à l'instant de l'appel).

<?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);
}
 
// Exemple d'utilisation
$encryptedResponse = "U2FsdGVkX1+abc123..."; // Réponse chiffrée de l'API
$date = "2026-05-20 14:30:00";                // Date envoyée dans la requête
$tokenSecret = "votre-token-secret";          // Votre clé secrète API
 
$data = decryptResponse($encryptedResponse, $date, $tokenSecret);
print_r($data);
?>

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)

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);

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);
    }
 
    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);
    }
}

Créez une vérification pour chaque utilisateur qui souhaite se faire vérifier.

Créez une nouvelle vérification et obtenez l'URL à rediriger vers l'utilisateur.

curl -X POST "https://pvid-back.docaposte.fr/api/pvid" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "idUser": 12345,
    "customerEmail": "jean.dupont@example.com",
    "isPriority": 0,
    "urlAfterSuccess": "https://votre-site.com/verification/succes",
    "urlAfterFailOrAbort": "https://votre-site.com/verification/echec",
    "linkValiditySharing": 30,
    "disableLinkSharing": 0,
    "addUserAlertScreen": 1,
    "addUserAlertText": "<b>Important</b>",
    "acceptedDocuments": ["FR-passport", "FR-id_card"],
    "webhook": "https://api.votre-domaine.com/pvid/webhook/session-123",
    "titleColor": "#003366",
    "textColor": "#333333",
    "linkColorText": "#0066CC",
    "buttonColorText": "#FFFFFF",
    "buttonColorBackground": "#003366",
    "ghostButtonColor": "#003366",
    "date": "2026-05-20 14:30:00"
  }'

• Le paramètre webhook est optionnel — si non fourni, le webhook global de configuration sera utilisé
• Cet appel doit être exécuté par votre serveur backend, jamais depuis le navigateur de l'utilisateur
• L'URL url retournée doit être ouverte dans le navigateur de l'utilisateur final
• ⚠️ Conservez l'id de la vérification pour les requêtes ultérieures (récupération des résultats)
• L'URL de vérification expire après le délai spécifié (par défaut 30 minutes, max 60 minutes)

{
    "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..."
}

Erreur (400) — Email invalide :

{ "slug": "email_not_valid", "message": "L'adresse email est invalide" }

Erreur (400) — Email manquant :

{ "slug": "no_email", "message": "No email parameter found in your request" }

Erreur (400) — URL succès manquante :

{ "slug": "empty_url_after_success", "message": "No url_after_success found in your request" }

Erreur (400) — URL échec manquante :

{ "slug": "empty_url_after_fail_or_abort", "message": "No url_after_fail_or_abort found in your request" }

Erreur (400) — Texte alerte trop court :

{ "slug": "alert_text_too_short", "message": "Le texte d'alerte doit contenir au moins 5 caractères" }

Erreur (400) — Texte alerte trop long :

{ "slug": "alert_text_too_long", "message": "Le texte d'alerte ne doit pas dépasser 120 caractères" }

Erreur (400) — Date invalide :

{ "slug": "invalid_date", "message": "Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)" }

Erreur (400) — Date expirée :

{ "slug": "expired_date", "message": "Given datetime is older than current datetime" }

Erreur (401) — Token invalide :

{ "error": "Invalid credentials or Keycloak error" }

Erreur (500) — Erreur serveur :

{ "slug": "internal_server_error", "message": "Internal server error" }

Une fois que l'utilisateur a complété son parcours, consultez le verdict et les données.

Récupérez l'état et le résultat d'une vérification.

curl -X GET "https://pvid-back.docaposte.fr/api/pvid/987654?date=2026-05-20%2014:30:00" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "accept: application/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"
    }
}

{
    "id": 987654,
    "dateAdded": "2026-05-20 14:25:00",
    "verdictDate": "2026-05-20 15:30:00",
    "status": "done",
    "verdict": "refused",
    "abortedReason": null,
    "refusalReasons": [
        { "slug": "document_expired", "text": "Document expiré" },
        { "slug": "manual_id_quality", "text": "Qualité insuffisante" }
    ]
}

{
    "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
}

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

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

Erreur (400) — Date invalide :

{ "slug": "invalid_date", "message": "Wrong date format (must be YYYY-MM-DD HH:mm:ss, eg: 2021-10-19 20:10:06)" }

Erreur (400) — Date manquante :

{ "slug": "empty_date", "message": "No date parameter found in your request" }

Erreur (400) — Date expirée :

{ "slug": "expired_date", "message": "Given datetime is older than current datetime" }

Erreur (401) — Token invalide :

{ "error": "Invalid credentials or Keycloak error" }

Erreur (403) — Accès refusé :

{ "slug": "access_denied", "message": "You do not have access to this PVID" }

Erreur (404) — Vérification introuvable :

{ "slug": "pvid_not_found", "message": "This PVID does not exist" }

Erreur (500) — Erreur serveur :

{ "slug": "internal_server_error", "message": "Internal server error" }

Configurez un webhook pour recevoir des notifications automatiques lors des changements de statut.

Les webhooks peuvent être configurés de deux manières :

Via l'endpoint PUT ou PATCH

/api/config

, vous définissez un webhook par défaut pour toutes vos vérifications.

Paramètre : webhook (string, HTTPS obligatoire)

Exemple :

{
  "webhook": "https://api.votre-domaine.com/pvid/webhook"
}

Lors de la création d'une vérification (POST

/api/pvid

), vous pouvez spécifier un webhook différent pour une vérification spécifique.

Paramètre : webhook (string, optionnel, HTTPS obligatoire)

Exemple :

{
  "webhook": "https://api.votre-domaine.com/pvid/webhook/session-123"
}

Priorité : Le webhook de vérification surcharge le webhook global si fourni.

PVID envoie une requête POST à votre URL avec le payload suivant :

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

• Répondez rapidement : Retournez un code HTTP 2xx dans les 5 secondes maximum.
• Traitez en asynchrone : Stockez l'événement et traitez-le en arrière-plan.
• Gérez les doublons : Les événements peuvent être envoyés plusieurs fois. Utilisez pvid_id pour l'idempotence.
• Vérifiez l'origine : Validez que la requête provient bien de nos serveurs (filtrage IP, hash de signature, etc.).
• Loggez les erreurs : Enregistrez les requêtes échouées pour débogage.
• Testez en intégration : Utilisez l'environnement d'intégration avant la production.

Les documents utilisent le format : {CODE_PAYS}-{TYPE_DOCUMENT}

Pour la liste complète, consultez

GET /api/config/documents

.

© Docaposte 2026 — Tous droits réservés