API ERP Risqéo : générer un état des risques depuis votre logiciel

L'API Risqéo produit un état des risques et pollutions depuis votre propre application : logiciel de diagnostic, logiciel de transaction, extranet d'agence ou d'étude notariale. Une requête HTTP suffit à créer le rapport à partir d'une adresse, puis à en récupérer le PDF. Elle s'adresse aux éditeurs et aux intégrateurs qui veulent supprimer la ressaisie sur un autre site.

La base est https://risqeo.fr/api/v1. Les réponses sont en JSON UTF-8, sauf le PDF, et une erreur renvoie toujours du JSON, jamais une page HTML du site. Cette page résume le contrat ; la spécification OpenAPI en donne la version complète et exploitable par un générateur de client.

Ce que fait l'API

Quatre gestes couvrent le parcours complet d'un dossier :

• Créer un ERP à partir d'une adresse, d'un code INSEE et, si vous les avez, de références cadastrales et de coordonnées.
• Télécharger le rapport en PDF, autant de fois que nécessaire et sans nouveau débit.
• Consulter le solde du compte, crédits à l'unité comme forfait mensuel.
• Consulter l'historique : la liste des ERP du compte et le détail de chacun.

Chaque rapport est conforme au modèle d'état des risques en vigueur (articles L125-5 et R125-23 à R125-27 du Code de l'environnement), établi à partir des sources officielles Géorisques, actualisées chaque jour, et annexable à tout acte de vente ou bail. L'état des nuisances sonores aériennes (ENSA) est inclus sans supplément quand la commune est couverte par un plan d'exposition au bruit. Sur le fond du document, voir ce qu'est le diagnostic ERP.

Aucune visite du bien n'est nécessaire : l'ERP est une recherche documentaire. C'est ce qui rend l'automatisation possible, et ce qui explique que le même parcours existe aussi en ligne, sans API, pour les dossiers ponctuels.

Le cycle de vie d'un ERP, à connaître avant d'intégrer

Le PDF se télécharge après la création. La création enregistre le diagnostic et débite le crédit ; le rapport s'obtient ensuite par GET /erp/{id}/pdf, toujours à jour des données officielles du jour, et se retélécharge gratuitement. Trois conséquences pratiques :

• juste après la création, le champ conclusions est nul : il est renseigné après le premier téléchargement ;
• comptez quelques secondes par téléchargement, davantage sur une commune très exposée : prévoyez un délai d'attente d'au moins 120 secondes côté client ;
• stockez le PDF chez vous plutôt que de rappeler l'API à chaque affichage.

Démarrage en quatre étapes

1. Créez une clé

Dans votre espace client, page « Mes clés d'API », avec 2 clés actives au maximum. La clé complète, rsq_ suivi de 40 caractères hexadécimaux, n'est affichée qu'une seule fois : mettez-la à l'abri. Nous ne la conservons pas en clair et ne pouvons pas vous la rappeler. La révocation est immédiate.

Deux formes d'authentification sont équivalentes : Authorization: Bearer rsq_…, recommandée, et X-Api-Key: rsq_… pour les clients HTTP ou les hébergements qui ne laissent pas passer l'en-tête Authorization.

2. Vérifiez la clé et le solde

curl -s https://risqeo.fr/api/v1/solde \
  -H "Authorization: Bearer rsq_VOTRE_CLE"

3. Créez un ERP

curl -s -X POST https://risqeo.fr/api/v1/erp \
  -H "Authorization: Bearer rsq_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dossier-4812-essai-1" \
  -d '{
        "diagnostic": {
          "adresse": "12 rue de la Paix",
          "code_postal": "75002",
          "ville": "Paris",
          "code_insee": "75102",
          "latitude": "48.8687",
          "longitude": "2.3312",
          "section_cadastre": "AB",
          "numero_parcelle_cadastre": "0012",
          "bailleur_vendeur": "SCI Exemple",
          "reference": "DOSSIER-4812"
        }
      }'

La réponse 201 porte l'identifiant de l'ERP, l'URL du PDF, ce qui a été débité et le solde restant :

{
  "success": true,
  "id": "3f2c9a…",
  "pdf_url": "https://risqeo.fr/api/v1/erp/3f2c9a…/pdf",
  "debite": "credits",
  "solde_restant": 12,
  "mode_solde": "credit"
}

Un tableau avertissements peut s'y ajouter : le rapport est produit et facturé, mais appauvri. Deux cas aujourd'hui, les coordonnées absentes et les références cadastrales incomplètes. Traitez-les comme des remarques à corriger au prochain appel, pas comme des erreurs.

4. Téléchargez le PDF

curl -s https://risqeo.fr/api/v1/erp/VOTRE_ID/pdf \
  -H "Authorization: Bearer rsq_VOTRE_CLE" \
  -o erp.pdf

Les cinq opérations

Seul POST /erp débite un crédit, au moment de la création. Le forfait mensuel est consommé en priorité s'il est actif et non expiré, les crédits à l'unité sinon. Sans solde, la réponse est un 402 solde_insuffisant. Consulter le solde, lister, lire un détail et surtout télécharger le PDF autant de fois que nécessaire ne coûte rien.

Deux précisions utiles au moment du câblage. Sur la liste, une valeur de limit hors bornes est ramenée dans les bornes, sans erreur, et le champ count donne la taille de la page, pas le total du compte. Sur le solde, solde est le chiffre à surveiller : le total réellement utilisable. Enfin, le rechargement se fait sur le site, page « Mon crédit » : l'API ne vend pas de packs.

Le cloisonnement est strict : l'ERP d'un autre compte répond 404, jamais 403. Une clé ne voit que les ERP de son compte.

Bac à sable : développer et recetter sans payer

Une clé de test se reconnaît à son seul préfixe : rsqtest_ au lieu de rsq_. Elle se crée dans votre espace client, sur la même page que les clés de production, en cochant la case prévue à cet effet. Vous voyez ainsi d'un coup d'œil laquelle de vos clés vous manipulez.

Les cinq opérations fonctionnent avec une clé de test : créer, relire, lister, consulter le solde et télécharger. Le parcours complet de votre intégration se déroule donc de bout en bout avant le premier euro dépensé. Quand tout est vert, il ne reste qu'à remplacer la clé par une clé rsq_ pour obtenir un document réel.

Deux détails à connaître pour ne pas être surpris : le solde renvoyé est fictif, 9 999 en mode bac_a_sable, et les ERP de test sont effacés au bout de 30 jours. Les deux univers sont étanches : une clé de test ne voit jamais vos ERP réels, une clé de production ne voit jamais vos ERP de test.

Les champs de la création

Chaque champ a un effet mesurable sur le rapport produit. Deux d'entre eux gouvernent la précision de l'analyse : le code INSEE, qui détermine la commune, et le couple latitude / longitude, qui autorise les analyses au droit du bien.

Pour obtenir ces champs à partir d'une adresse saisie au clavier, adressez-vous aux services publics nationaux, conçus pour cet usage : la base adresse nationale (api-adresse.data.gouv.fr) rend le code INSEE et les coordonnées, et l'API Carto de l'IGN rend la parcelle située sous un point. Nous prévoyons d'exposer ces recherches directement dans l'API, authentifiées et sans débit.

Erreurs : un format unique, un code stable

Toute erreur suit la même forme, quelle que soit l'opération appelée :

{ "success": false, "error": { "code": "solde_insuffisant", "message": "Crédits insuffisants." } }

Testez le code : il est stable, c'est lui qui doit piloter votre logique de reprise. Le message est destiné à un humain et peut évoluer d'une version à l'autre : ne l'analysez pas, affichez-le ou journalisez-le.

Toute réponse est en JSON, y compris sur une adresse inconnue ou en cas d'erreur de notre côté (erreur_interne) : l'API ne renvoie jamais la page HTML du site.

Des refus d'authentification répétés depuis une même adresse IP sont freinés par un 429 trop_d_essais.

Côté réessais : sur 429 et 500, réessayez avec un délai croissant, en respectant l'en-tête Retry-After. Sur les autres 4xx, corrigez la requête, car réessayer à l'identique donnera le même refus. Les données refusées ne sont jamais facturées : commune inconnue, adresse manquante, JSON illisible et solde vide sont tous contrôlés avant le débit.

Idempotence et limites de débit

Répéter un appel sans facturer deux fois

Envoyez Idempotency-Key: <votre identifiant unique> sur chaque POST /erp, 64 caractères au plus, parmi A-Z a-z 0-9 . _ : -.

• Rejouée, la même clé renvoie la réponse d'origine avec l'en-tête Idempotency-Replayed: true, sans second débit.
• Une clé encore en cours de traitement répond 409 idempotence_en_cours.
• Une tentative qui a échoué libère la clé : vous pouvez réessayer.

C'est la protection à activer sur toute création automatisée : une coupure réseau après l'envoi ne vous fera pas payer deux fois. Une bonne clé est dérivée de votre propre dossier, par exemple dossier-4812-essai-1.

Limites de débit

Par clé, sur une fenêtre glissante de 60 secondes :

Le téléchargement a ses propres limites parce que c'est l'appel le plus lourd : comptez quelques secondes par rapport. Le plafond qui compte vraiment est celui des deux téléchargements simultanés : attendez la réponse d'un téléchargement avant d'en lancer un autre, ou n'en lancez pas plus de deux en parallèle.

Un appel en cours compte dans ces plafonds : une rafale de requêtes parallèles est freinée dès la troisième.

En cas de dépassement, l'API répond 429 limite_debit avec un en-tête Retry-After en secondes. Respectez-le plutôt que de réessayer immédiatement. Les refus apparaissent dans l'historique de la clé, dans votre espace client.

Tarifs

Le crédit est la seule unité de facturation, et un ERP vaut un crédit. Les mêmes prix s'appliquent que vous passiez par l'API ou par le site.

L'assurance responsabilité civile professionnelle est incluse, et la réédition est gratuite et illimitée pendant 18 mois à compter de la commande : un ERP créé pour la mise en annonce se retélécharge pour le compromis, puis pour l'acte, sans repayer. Le détail des formules et le rechargement sont sur la page tarifs.

Rappel utile pour dimensionner votre intégration : un état des risques doit avoir moins de six mois à la signature de la promesse, de l'acte ou du bail, et être actualisé si les informations ont changé entre-temps. C'est ce qui fait de la réédition un appel courant, et non un cas limite. Voir ce qu'en attendent les études notariales.

Spécification OpenAPI : générez votre client

La spécification OpenAPI 3.0 de l'API est publiée et tenue à jour : télécharger /api/v1/openapi.yaml. Toute route absente du fichier n'existe pas.

Concrètement, ce fichier vous évite d'écrire la couche de transport à la main. Donnez-le à un générateur de code et vous obtenez un client typé dans le langage de votre application, PHP, Java, C#, Python, TypeScript ou autre, avec les modèles de requête, les modèles de réponse et les codes d'erreur déjà en place. Il alimente aussi votre propre portail de documentation interne et les collections de vos outils de test HTTP.

Conseils d'intégration

• Délais : au moins 120 secondes sur le téléchargement, 30 suffisent ailleurs.
• Stockage : gardez l'id de chaque ERP dans votre base, c'est la seule clé de rattachement.
• Litige : donnez-nous l'id de l'ERP et l'horodatage de l'appel.
• Sécurité : la clé donne accès au solde du compte. Stockez-la hors du code source, révoquez-la au moindre doute, créez-en une par application plutôt qu'une pour tout.
• Compatibilité : l'URL porte la version, /api/v1/. Les ajouts compatibles, nouveau champ dans une réponse, nouvel endpoint, nouveau code d'erreur, se font sans préavis dans la v1 : votre client doit ignorer les champs qu'il ne connaît pas. Une rupture de contrat passerait par /api/v2/, l'ancienne version restant servie.

Certaines briques n'existent pas encore, et nous préférons le dire : synthèse structurée des risques en JSON, commande groupée, notification par webhook, endpoint de renouvellement et jetons délégués pour les éditeurs de logiciels. Si l'une d'elles conditionne votre projet, parlons-en : la file de priorité se construit avec les intégrateurs.

FAQ : intégrer l'API Risqéo