Documentation/Référence/API document

API document

Récupérer les documents partagés par l'utilisateur.

Les scopes private:doc.* ajoutent à l’id_token des claims dont la valeur est une URL. Un simple GET sur cette URL, avec l’access_token du résultat OIDC en jeton bearer, retourne le document.

Requête


Méthode	`GET`
URL	L’URL fournie dans le claim (par exemple `https://oidc-sandbox.a3bc.io/doc/id`)
En-tête	`Authorization: Bearer <access_token>`

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://oidc-sandbox.a3bc.io/doc/id

import base64, requests

r = requests.get(doc_url, headers={"Authorization": f"Bearer {access_token}"}, timeout=15)
r.raise_for_status()
body = r.json()
for d in body["document"]:
    open(d["name"], "wb").write(base64.b64decode(d["content"]))
print(body.get("metadata"))

Réponse

Statut	Objet	Commentaire
`200`	document	Document récupéré
`401`	erreur	Authentification échouée
`500`	erreur	Erreur interne

{
  "metadata": {
    "name": "passport",
    "identifier": "SPECI2014",
    "issued": "2014-04-05",
    "expired": "2024-04-04",
    "country": "nl",
    "issuedBy": "Burg van Stadt en Dorp"
  },
  "document": [
    { "name": "front.png", "content": "iVBORw0KGgoAAAANSUhEU..." },
    { "name": "back.png",  "content": "iVBORw0KGgoAAAANSUhEU..." }
  ]
}

document[].name : nom de fichier <nom>.<extension> (png, jpg, jpeg ou pdf).
document[].content : contenu encodé en base64.
metadata : informations sur le document lui-même (émetteur, dates, type). Présentes en général pour les documents vérifiés (private:doc.*).

Les claims *.hash donnent l’empreinte (sha256:…) de chaque document, pour contrôler son intégrité.

Erreur : {"code":"004013","message":"ingress auth: authentication failed"} (mauvais jeton).

Métadonnées par scope

`private:doc.id`

Nom	Type	Description
`name`	string	Type de pièce : `passport`, `resident permit` ou `identity card`.
`identifier`	string	Numéro de série ou identifiant unique.
`issued`	date	Date de délivrance.
`expired`	date	Date d’expiration.
`country`	string	Pays émetteur.
`issuedBy`	string	Organisme officiel émetteur.
`personalNumber`	string	Identifiant unique d’un étranger (titre de séjour).
`remarks`	string	Zone de texte libre du titre de séjour.
`receiptIdentifier`	string	Identifiant du récépissé de renouvellement présenté avec un titre de séjour français expiré.
`receiptIssued`	date	Émission du récépissé (optionnel).
`receiptExpired`	date	Expiration du récépissé (optionnel).

Quand les métadonnées de récépissé sont présentes, deux documents sont fournis, dans cet ordre : le titre de séjour expiré (PDF), puis le récépissé (png, jpeg, bmp ou pdf).

`private:doc.address`, `private:doc.ssn`, `private:doc.bankaccount`

Toutes les informations ne sont pas toujours présentes, selon le document analysé.

Nom	Type	Description
`name`	string	Type de justificatif.
`author`	string	Émetteur (souvent le fournisseur).
`issued`	date	Date d’émission.
`identifier`	string	Référence du document.