Documentation de l'API

Le site que vous consultez n'utilise aucune route en dehors de celles listées ci-dessous. C'est une contrainte d'architecture, pas une promesse : tout ce que fait l'interface, une intégration peut le faire.

Authentification

Deux modes. Un jeton de session pour les comptes (Authorization: Bearer …), obtenu par POST /auth/login ou par lien magique. Une clé API pour les intégrations (X-API-Key: aak_…), créée depuis l'espace organisation, avec ses portées et son quota.

Les clés ne sont stockées que hachées : la valeur en clair n'est affichée qu'une fois, à la création.

Lancer un audit et récupérer le résultat

curl -X POST https://exemple/api/audit \
  -H "X-API-Key: aak_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{"adresse": "12 rue de la Paix, 75002 Paris", "profil": "acheteur"}'

# 202 { "audit_id": "…", "statut": "en_cours", "quota": { … } }

curl https://exemple/api/audit/AUDIT_ID       -H "X-API-Key: aak_votre_cle"
curl https://exemple/api/audit/AUDIT_ID/data  -H "X-API-Key: aak_votre_cle"
curl https://exemple/api/audit/AUDIT_ID/pdf   -H "X-API-Key: aak_votre_cle" -o rapport.pdf

POST /audit répond 202 : le calcul est asynchrone (15 à 35 secondes). Le quota est vérifié avant lancement — un refus arrive en 402 ou 429 sans qu'aucune requête n'ait été émise vers une source externe, donc sans facturation surprise.

Toutes les routes

Les routes publiques de la plateforme.
Route	Ce qu'elle fait
`POST /auth/register`	Crée un compte particulier.
`POST /auth/login`	Jeton de session par mot de passe.
`POST /auth/magic-link`	Envoie un lien de connexion (15 min, usage unique).
`POST /auth/magic-link/verify`	Échange le lien contre un jeton de session.
`GET /me`	Compte courant et consommation du mois.
`POST /audit`	Lance un audit. 202 + identifiant.
`GET /audit/{id}`	Statut, progression, liens.
`GET /audit/{id}/data`	L'audit complet en JSON.
`GET /audit/{id}/pdf`	Le rapport imprimé.
`DELETE /audit/{id}`	Supprime un audit et ses données.
`GET /audits`	Historique. `q=`, `tri=`, `format=json\|csv`.
`GET /audits/compare?ids=a,b`	2 à 5 audits côte à côte.
`POST /audits/batch`	Lot d'adresses (organisations).
`GET /org/members`	Membres et quota de l'organisation.
`POST /org/members`	Ajoute un membre (org_admin).
`DELETE /org/members/{id}`	Retire un membre (org_admin).
`GET /org/api-keys`	Liste les clés (org_admin).
`POST /org/api-keys`	Crée une clé (org_admin).
`GET /admin/metrics`	Santé des sources (administrateur).
`GET /admin/audits`	Derniers audits (administrateur).
`GET /health`	Disponibilité du service.

Codes de retour et limites

202 — audit accepté, calcul en cours.
402 — paiement requis : audit à l'unité sans paiement confirmé.
429 — quota mensuel atteint, ou limitation par IP sur les routes publiques. Refus propre, jamais de dégradation silencieuse.
404 — audit inexistant ou n'appartenant pas à l'appelant : nous ne révélons pas l'existence de l'audit d'un tiers.
409 — audit encore en cours : les données ne sont pas disponibles.

Ce que renvoie un audit

GET /audit/{id}/data renvoie l'objet complet : adresse normalisée, fiche du bien, les 23 modules avec leur statut, leur source et leur date, les scores par pilier, les indices de mobilité, les alertes et la couverture des données.

Un module absent n'est jamais omis ni mis à zéro : il porte status: "no_data" et une raison en clair. C'est la même règle que dans le rapport et sur le site — une donnée manquante est une information, pas un vide.