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.

Lancement d'un audit et récupération du 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 (moins de deux minutes). 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 59 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.
`PATCH /me`	Modifie le compte : nom, mot de passe, préférences.
`DELETE /me`	Ferme le compte et efface ses audits.
`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 en PDF, fabriqué à la demande.
`PUT /audit/{id}/type`	Choisit le type de rapport professionnel : implantation, bail commercial ou achat de murs.
`POST /audit/{id}/rendement`	Calcule un rendement locatif sur vos hypothèses : loyer, charges, travaux, taux.
`PUT /audit/{id}/commentaire`	Enregistre le commentaire du professionnel affiché en tête du rapport.
`POST /audit/{id}/partage`	Ouvre un lien de partage en lecture seule.
`DELETE /audit/{id}/partage`	Ferme le lien de partage.
`GET /partage/{jeton}`	Le rapport derrière un lien de partage, sans compte.
`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 à 4 audits côte à côte.
`POST /audits/batch`	Lot d'adresses (organisations).
`POST /quartiers`	Cherche des quartiers par critères ou par profil.
`GET /carte/situer`	Situe une adresse ou une commune sur la carte.
`GET /carte.png`	Rend une tuile de la carte nationale, en image.
`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 /org/marque`	L'identité visuelle appliquée aux rapports.
`PUT /org/marque`	Modifie couleurs et mentions de l'organisation.
`PUT /org/logo`	Remplace le logo imprimé sur les rapports.
`GET /admin/metrics`	Santé des sources (administrateur).
`GET /admin/audits`	Derniers audits (administrateur).
`GET /adresses/completer`	Propose des adresses pour une saisie partielle, deja departagees.
`GET /adresses/parcelle`	La parcelle cadastrale au droit d'un point.
`GET /audit/{id}/rapport`	Le corps du rapport en HTML, cartes incorporees.
`POST /communes/rechercher`	Cherche des communes sur criteres : prix, equipements, population.
`GET /communes`	Tous les codes de commune connus.
`GET /communes/{code}`	La fiche d'une commune.
`GET /quartiers/modes`	Les modes de transport urbain qu'un perimetre a reellement.
`POST /demandes/espace-agence`	Transmet une demande d'ouverture d'espace professionnel.
`GET /demandes/code-invitation/{code}`	Ce qu'un code d'invitation offre : rapports et jours.
`GET /capacites`	Ce que le serveur peut faire : encaisser, envoyer un courriel.
`POST /paiement/ouvrir`	Ouvre un reglement pour un rapport a l'unite.
`POST /paiement/retour`	Le retour du prestataire : verifie la signature et debloque.
`GET /audit/{id}/acces`	Dit si ce rapport a ete regle. La base fait foi, pas la session.
`GET /vendeur`	L'identite qui figure sur les factures et les pages legales.
`GET /abonnement`	L'abonnement en cours et son historique.
`POST /abonnement/souscrire`	Ouvre le reglement d'une formule du catalogue.
`DELETE /abonnement`	Resilie. Le droit court jusqu'a son terme.
`GET /factures`	Vos factures, de la plus recente a la plus ancienne.
`GET /facture/{reference}`	Une facture et son PDF.
`GET /audit/{id}/apercu`	Les faits marquants d'un audit — ce qui se voit avant paiement.
`GET /demonstration`	L'extrait d'exemple, produit par le meme code que l'apercu reel.
`GET /audit/{id}/court`	Le rapport reduit a l'essentiel — ce qui tient sur un ecran.
`POST /abonnement/facturer`	Emet une facture a regler par virement — forfaits sur devis.
`GET /rapport.css`	La feuille de style du rapport, pour l'inserer dans vos pages.
`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.

Contenu de la réponse

GET /audit/{id}/data renvoie l'objet complet : adresse normalisée, fiche du bien, les 26 modules avec leur statut, leur source et leur date, les scores par critère (clé piliers), 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.