API Bienalys

Commandez vos états des risques et pollutions (ERP) directement depuis votre logiciel : un appel, et vous recevez le PDF conforme à l'article R.125-24 du code de l'environnement, avec le résumé des risques en JSON. Même document que sur le site, en 20 secondes à 1 minute.

Clé de test gratuite pour tout compte : elle vérifie réellement l'adresse ou les parcelles, puis renvoie un ERP d'exemple. Rien n'est fabriqué ni décompté. Créer un compte, puis Espace client → Accès API.

1. Authentification

Chaque appel porte la clé dans l'en-tête Authorization. Les clés se créent et se révoquent dans l'espace client (page Accès API, réservée au responsable du compte). Une clé n'est affichée qu'une fois : conservez-la comme un mot de passe.

Authorization: Bearer bnl_live_xxxxxxxxxxxxxxxxxxxxxxxx

Clés bnl_test_… : mode test. Clés bnl_live_… : production (formule API). Adresse de base : https://bienalys.fr/api/v1. Corps et réponses en JSON (UTF-8).

2. Créer un ERP — POST /api/v1/erp

Indiquez le bien d'une des trois façons suivantes :

Champ	Description
parcelles (recommandé)	Liste de 1 à 20 parcelles du bien : {"code_insee": "13212", "section": "AB", "numero": "123", "prefixe": "000"} (prefixe facultatif, pour les communes associées ; pour Paris, Lyon et Marseille, le code INSEE de l'arrondissement).
lat, lon ou points	Coordonnées WGS84 d'un point de la parcelle, ou points: [[lat, lon], …] pour plusieurs parcelles.
adresse	Adresse complète avec numéro (ou lieu-dit). Une adresse sans numéro est refusée (422) : elle ne permet pas de désigner une parcelle.

Champs facultatifs : type ("vente" par défaut, ou "location"), vendeur_ou_bailleur, acquereur_ou_locataire, ref_interne (votre référence de dossier, 80 caractères maximum).

Anti-doublon : si la même ref_interne est renvoyée dans les 24 heures, l'API renvoie l'ERP déjà fabriqué ("deja_fabrique": true, code 200) sans rien décompter.

curl -X POST https://bienalys.fr/api/v1/erp \
  -H "Authorization: Bearer $BIENALYS_CLE" -H "Content-Type: application/json" \
  -d '{"parcelles": [{"code_insee": "13212", "section": "AB", "numero": "123"}],
       "type": "vente", "vendeur_ou_bailleur": "M. Martin", "ref_interne": "DOSSIER-2026-0451"}'

Réponse 201 :

{
  "ref": "BNL-2026-000512", "cree_le": "2026-10-13 12:04:31", "valide_jusqu_au": "14/04/2027", "statut": "valide",
  "type": "vente", "adresse": "12 Rue Exemple, 13012 Marseille", "parcelles": "…", "idu": ["132120000AB0123"],
  "ref_interne": "DOSSIER-2026-0451", "decompte": "forfait", "renouvellements_offerts_restants": 1,
  "parcelle_devinee": false,
  "resume_risques": {"ppr": […], "sismicite": 2, "radon": 1, "argiles": …, "peb": null, "catnat": 4, …},
  "resume_texte": "Plans de Prévention des Risques :\n  - Naturels : inondation (zone bleue)\n  …\nRadon de niveau 1, Séisme de niveau 2\n…",
  "pdf": "https://bienalys.fr/api/v1/erp/BNL-2026-000512/pdf",
  "annexes": "https://bienalys.fr/api/v1/erp/BNL-2026-000512/annexes"
}

parcelle_devinee: true signale que le point indiqué tombait hors de toute parcelle (sur la voirie) : la parcelle la plus proche a été retenue, vérifiez-la avant de remettre l'ERP. resume_texte est le résumé rédigé des risques, prêt à coller dans une annonce, un mail ou un compromis (le même que le bouton « Copier » du site). decompte vaut forfait, credit (pack ou ERP à l'unité) ou offert (renouvellement gratuit).

L'ERP est fabriqué pendant l'appel (20 s à 1 min) : prévoyez un délai d'attente d'au moins 3 minutes.

3. Autres appels

GET /api/v1/erp/<ref>	Relire un ERP (même réponse que la création).
GET /api/v1/erp/<ref>/pdf	Le PDF de l'ERP (410 s'il a été supprimé, après 6 mois).
GET /api/v1/erp/<ref>/annexes	Les annexes (règlements PPR, fiches officielles), quand il y en a.
POST /api/v1/erp/<ref>/renouveler	Nouvel ERP à jour des données du jour, mêmes parcelles. Le premier renouvellement dans les 12 mois est offert.
GET /api/v1/compte	Formule, ERP faits et restants ce mois-ci, ERP de packs ou à l'unité disponibles.

curl -H "Authorization: Bearer $BIENALYS_CLE" -o ERP.pdf https://bienalys.fr/api/v1/erp/BNL-2026-000512/pdf

4. Exemple PHP

$ch = curl_init('https://bienalys.fr/api/v1/erp');
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 180,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('BIENALYS_CLE'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'parcelles' => [['code_insee' => '13212', 'section' => 'AB', 'numero' => '123']],
    'type' => 'vente', 'ref_interne' => 'DOSSIER-2026-0451',
  ]),
]);
$erp = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) { throw new Exception($erp['erreur']); }
file_put_contents($erp['ref'] . '.pdf', file_get_contents($erp['pdf'], false,
  stream_context_create(['http' => ['header' => 'Authorization: Bearer ' . getenv('BIENALYS_CLE')]])));

5. Erreurs

Toute erreur renvoie {"erreur": "message lisible", "code": "…"}. Une erreur ne décompte jamais d'ERP.

HTTP	code	Signification
400	json	Corps JSON absent ou invalide.
401	cle_absente, cle_invalide	Clé absente, invalide ou révoquée.
402	quota_epuise	Forfait du mois, packs et ERP à l'unité épuisés.
403	formule_requise	Clé live sans formule API.
404 / 410	introuvable, pdf_purge	ERP inconnu pour ce compte / PDF supprimé après 6 mois.
422	localisation	Adresse imprécise, parcelle introuvable, coordonnées hors France métropolitaine.
429	debit, trop_d_echecs	Plus de 120 appels ou 40 ERP par 10 minutes et par clé : réessayez après reessayer_dans_s secondes.
502	fabrication, service_public	Un service de l'État (Géorisques, IGN) n'a pas répondu : réessayez dans un instant.
503	occupe	Serveur occupé : réessayez dans une minute.

6. Responsabilité

L'ERP est établi à partir des données publiques de l'État à la date de l'appel (obligation de moyens, voir les CGV). Il appartient au professionnel de le vérifier, de le compléter et de le faire signer. La clé est réservée à la société titulaire du compte : toute revente ou mise à disposition à des tiers est interdite.

Une question technique ? contact@apzidigital.com