Règles générales

Ces règles valent pour tous les points d’accès de l’API.

Format des requêtes

Les appels utilisent HTTPS et la méthode POST, avec un corps JSON. Seule la lecture des activations (/enrollments) utilise GET.
Le corps est du JSON en UTF-8. Envoyez l’en-tête Content-Type: application/json sans paramètre charset.
Les textes affichés à l’utilisateur (userVisibleData) et les données privées (userNonVisibleData) sont du texte encodé en Base64.
Le service ne prend en charge que HTTP/1.1 et exige TLS 1.2 ou 1.3.

Authentification

Vous vous authentifiez avec votre certificat client (voir Demander un certificat). En test, l’en-tête X-Api-Key peut le remplacer.
Vérifiez le certificat du serveur ExcelID : l’émetteur doit être dans votre magasin de confiance.
Une demande ne peut être consultée ou annulée qu’avec le certificat qui l’a créée. Sinon, 400 invalidParameters.

Durées de vie

Élément	Durée
Demande en attente d’une confirmation	180 secondes
Résultat disponible avec `/collect`	Terminée : 3 minutes ; échouée : 5 minutes
Code d’activation	10 minutes, usage unique
Contenu du code QR animé	Tolérance : 2 secondes d’avance, 10 secondes de retard

Évolutions de l’API

La version est dans le chemin : /v1/. Les changements incompatibles donnent une nouvelle version, annoncée à l’avance dans les actualités.
Nous pouvons ajouter des champs, des hintCode et des errorCode sans préavis. Votre implémentation doit ignorer les champs inconnus et traiter proprement les codes inconnus.

Bonnes pratiques de sécurité

Gardez la clé privée et le fichier PKCS#12 sur vos serveurs, dans un gestionnaire de secrets. Jamais dans du code de navigateur, une application mobile ou un dépôt public.
Ne transmettez qrStartSecret ni à votre frontend ni à un tiers.
Envoyez dans endUserIp l’adresse de la personne, pas celle de votre proxy.
Interrogez /collect depuis votre backend, jamais depuis le navigateur.
Vérifiez la preuve et conservez-la (voir Vérifier les signatures).
Ne demandez jamais à une personne son code de sécurité ni son empreinte.

Données personnelles

Le numéro d’identité et le nom qui vous sont renvoyés sont des données personnelles. Ne les conservez que si votre traitement le justifie, protégez-les en conséquence et respectez la réglementation applicable à votre secteur.