API publique

Cette page documente uniquement les points d'entrée réellement ouverts à un appelant extérieur. Les autres routes sous /api/ — compte, facturation, tableau de bord, webhooks, administration — sont internes à l'application, exigent une session authentifiée et ne sont pas destinées à un usage tiers.

La description lisible par machine est la spécification OpenAPI 3.1, recensée dans notre catalogue d'API (RFC 9727).

Le diagnostic exige un jeton invité, lié à l'adresse IP qui l'a demandé. Il s'obtient sans compte :

curl https://verdiseo.fr/api/auth/token
# → {"guestToken":"..."}

Le jeton se transmet ensuite dans l'en-tête x-guest-token. Il n'est valable que depuis la même adresse IP : un jeton obtenu ici et rejoué ailleurs est refusé.

POST /api/audit/scan analyse un site de commerce et rend deux scores : geoScore (visibilité auprès des moteurs génératifs) et seoScore (référencement local).

curl -X POST https://verdiseo.fr/api/audit/scan \
  -H "Content-Type: application/json" \
  -H "x-guest-token: $JETON" \
  -d '{"domain":"boulangerie-exemple.fr","ville":"Nantes","secteur":"Boulangerie / Pâtisserie"}'

Réponse : success, auditId, domain et report. Un diagnostic déjà produit pour le même domaine dans les 24 heures est renvoyé depuis le cache, signalé par fromCache: true.

La réponse est la version gratuite du rapport. Les livrables de l'audit payant en sont retirés côté serveur, jamais côté client.

Codes d'erreur : 400 domaine absent ou invalide, 401 jeton absent ou invalide, 429 limite d'appels atteinte (le corps porte alors limitReached), 500 erreur serveur.

GET /api/communes?q=nant&limit=5 — aide à la saisie sur le référentiel des communes françaises. Aucune authentification.

⚠️ Ce point rend un tableau vide, et non une erreur, lorsque la requête fait moins de 2 ou plus de 60 caractères, ou qu'aucune commune ne correspond. limit est borné entre 1 et 10.

GET /api/health rend {"status":"pass"} lorsque le service web répond. Il n'interroge pas la base de données : un point d'état qui échoue quand la base tombe ne renseigne plus sur ce qu'il est censé mesurer.

L'usage de cette API est soumis aux conditions générales d'utilisation et à la politique de confidentialité. Les appels sont limités en débit ; le diagnostic déclenche des traitements coûteux et n'est pas destiné à un usage massif automatisé.