API de vérification des pass sanitaires

Intégrez la vérification de passes sanitaires à votre application en 5 minutes de développement

J'aimerais bien passer des heures à implémenter base45, CBOR, COSE, et 3 algorithmes différents de signature numérique

Sanipasse.fr expose désormais une API HTTP pour vérifier les passes sanitaires. Elle permet de faire décoder et vérifier des passes par le serveur de sanipasse, tout en respectant les engagements de sécurité et de respect de la vie privée de sanipasse.

Comment utiliser l'API ?

Extraire la forme textuelle du passe sanitaire

L'API de sanipasse propose uniquement le décodage de la forme textuelle des passes sanitaires. Il vous faut donc d'abord utiliser une bibliothèque de détection et de lecture des QR codes. Vous pouvez utiliser pour cela n'importe laquelle des bibliothèques de lecture existante, comme par exemple la bibliothèque libre ZXing.

Lorsque vous décodez un passe sanitaire européen, vous obtenez une suite de lettres et de chiffres qui commence par HC1:. C'est cette chaîne de caractères que vous devrez fournir à sanipasse.

Attention: Avant d'utiliser l'API, assurez-vous d'avoir correctement décodé le QR code ou le DataMatrix. Les codes datamatrix contiennent notemment des caractères de contrôle, invisibles, que certains lecteurs physiques ne lisent pas correctement. Pour vous assurer que vous avez bien décodé un code, vous pouvez le réencoder en QR code ou en datamatrix, et vérifier que l'image résultante peut bien être scannée dans sanipasse ou dans TousAntiCovid-Verif.

Obtenir une clef d'API

L'API demande de s'authentifier pour vérifier les passes sanitaires. Pour vous authentifier, il vous faut fournir une clef unique, qui vous sera fournie si vous en faites la demande à contact@ophir.dev. Pour la suite, nous supposerons que vous avez une clef valide, que nous définirons pour cette démonstration à XXXX.

Envoyer une requête

Pour vérifier un passe, il faut envoyer une requête POST à l'adresse

https://sanipasse.fr/api/validate_pass

avec le Content-Type application/json et le corps de requête JSON suivant:

{
  "key": "XXXX",
  "code": "HC1:..."
}

Pour tester l'API en ligne de commande, on peut utiliser curl:

curl https://sanipasse.fr/api/validate_pass -H 'Content-Type: application/json' --data '{"key":"XXXX","code":"HC1:..."}' -v

ou python, avec la bibliothèque requests:

import requests

validation = requests.post(
	'https://sanipasse.fr/api/validate_pass',
	json={"key":"XXXX","code":"HC1:..."}
).json()
Interpréter le résultat

Si la vérification fonctionne, quel qu'en soit le résultat (code valide ou non), l'API retournera un code HTTP 200.

Pour un code valide

Si le passe est valide, l'API retourne les informations nécessaires à la vérification d'identité de son porteur au format JSON

{
    "validated": true,
    "person": {
        "first_name": "PIERRE",
        "last_name": "LEGENDRE",
        "date_of_birth": "1990-01-01T00:00:00.000Z"
    }
}
Pour un code invalide

Si le passe est invalide, l'API retourne un message expliquant pourquoi le passe est invalide

{
    "validated": false,
    "error":"Vous n'avez reçu que 1 dose sur les 2 que ce vaccin demande.",
    "person": {
        "first_name":"PIERRE",
        "last_name":"LEGENDRE",
        "date_of_birth":"1990-01-01T00:00:00.000Z"
    }
}

L'object person peut ne pas être présent si le passe présenté n'a pas un format correct.