Documentation développeur

Les règles locales de la location, en machine : verdicts sourcés à l'adresse, table des plafonds L. 324-2-1, contrôle de numéros d'enregistrement, flux de changements. Chaque fait est restitué avec sa source, sa citation et sa date de vérification — information documentaire, jamais une consultation juridique. Trois états contractuels par volet : `etabli`, `absence_etablie` (toujours fondée sur une source), `non_couvert` (la collecte est alors déclenchée). Répondre « aucune règle » sans source est structurellement impossible dans ce contrat.

Contrat OpenAPI 1.0.0 — cette page est engendrée depuis ce fichier. Serveur : https://api.locaclear.fr/v1

Authentification

Chaque appel porte la clé de l'organisation dans l'en-tête Authorization, selon le schéma Bearer. Les clés se créent et se révoquent dans l'onglet API de l'espace client, bloc « Clés » ; la clé complète n'y apparaît qu'une fois, à la création. Seul son préfixe est conservé côté serveur, avec une empreinte — la clé elle-même n'est stockée nulle part en clair, et ne peut donc pas être réaffichée.

Authorization: Bearer lck_live_…

Clé d'API de l'organisation (préfixe lck_live_ ou lck_test_). Les clés lck_test_ servent le bac à sable : mêmes contrats, corpus figé, aucune consommation de quota, aucune collecte déclenchée. Chaque palier borne le volume d'appels ET le nombre de communes distinctes interrogées par mois (verdicts, communes, plafond à l'unité confondus) ; les en-têtes X-Quota-Limite, X-Quota-Restant, X-Quota-Reinitialisation (appels) et X-Quota-Communes-Limite, X-Quota-Communes-Restant (communes distinctes) détaillent les deux. Au-delà du quota d'appels de VERDICT, une souscription qui porte la facturation au dépassement est servie et l'appel est facturé à l'unité : X-Quota-Restant reste à 0, et X-Quota-Depassement compte les appels du mois servis au-delà du quota. Sans cette facturation, l'appel reçoit 429 quota_atteint. Les contrôles de numéro et les communes distinctes n'ont pas de dépassement : leur plafond rend toujours 429.

Bac à sable

Une clé de préfixe lck_test_ sert un corpus figé : mêmes points d'accès, mêmes schémas, mêmes codes de réponse. Aucun quota n'est consommé, aucune collecte n'est déclenchée. La commune fictive de Portneuve (99999) y figure — c'est elle qui sert d'exemple dans toute cette page, et c'est la seule commune dont les valeurs locales sont publiées ici. Les règles d'une commune réelle se lisent sur sa fiche publique ou s'obtiennent par l'API.

Une clé de bac à sable se crée au même endroit qu'une clé de production — l'onglet API de l'espace client, bloc « Clés », en choisissant « Clé de bac à sable ». Comme une clé de production, elle n'ouvre l'API que tant qu'un palier est en cours.

Les trois états, par volet

Chaque réponse de verdict porte deux volets — courte_duree et permis_de_louer — et chacun porte son propre état. Ils ne sont jamais fusionnés : un régime peut être établi pendant que l'autre n'est pas couvert.

etabli Le corpus documente le régime pour cette commune.: Le volet rend ses faits, chacun avec sa source, sa citation verbatim, sa date de vérification et son statut. Le statut « à confirmer » est exposé tel quel : un fait relevé mais non recoupé, ou un régime institué par un acte dont le règlement n'est pas publié, se dit, il ne se tait pas. Le tableau `faits_non_documentes` liste les clés restées inconnues sur cette commune.
absence_etablie Une source établit qu'aucun régime ne s'applique.: Le fondement est un fait comme un autre : une source, une citation, une date. Cet état ne se rend jamais sans lui.
non_couvert La commune n'est pas au corpus.: La réponse le dit et enregistre la demande de collecte, horodatée. Aucun délai n'est promis : un appel machine n'attend pas. Le socle national, lui, figure toujours dans la réponse.

Une asymétrie, dite plutôt que masquée

En v1, absence_etablie ne se rend que sur le volet permis_de_louer. Les fiches portent, pour ce régime, un fait d'absence unique et sourcé : un régime relevé comme « aucun », avec l'acte ou les registres d'actes qui l'établissent. Sur le volet courte durée, l'absence de règle locale est portée par les faits de la fiche eux-mêmes : quand les registres d'actes de la commune et de son intercommunalité ont été parcourus sans y trouver de règle, le volet rend un changement d'usage « non », le plafond légal (article L. 324-1-1, IV du code du tourisme) et des restrictions datées — « Aucune restriction locale propre aux meublés de tourisme dans les actes publiés par la commune et son intercommunalité au … » —, chacun avec sa source et sa date. L'état absence_etablie n'est pas encore exposé pour ce volet : il rend etabli ou non_couvert, et le contrat l'écrit plutôt que de simuler une symétrie qu'il n'expose pas encore.

Le secteur : quatre constats, jamais un booléen

Un volet établi porte un objet secteur dont le champ constat distingue quatre situations. « Le point est-il dans un secteur ? » n'a pas de réponse par oui ou non : ne pas être dans un secteur numérisé et n'avoir aucun secteur documenté sont deux faits différents, et les confondre reviendrait à affirmer une couverture qu'on n'a pas.

dans-secteur: Le point tombe dans un périmètre numérisé du volet. Le zonage et la précision de la numérisation sont rendus.
hors-secteur: Des périmètres sont numérisés pour ce volet, et le point n'y tombe pas.
zonage-textuel: Des secteurs existent — la délibération les décrit — mais ils ne sont pas numérisés : aucun point ne peut être situé.
sans-zonage: Aucun secteur n'est documenté pour ce volet sur cette commune : la règle, si elle existe, vaut sur tout le territoire communal.

Quotas et en-têtes

Chaque palier borne deux volumes : les appels de verdict, et le nombre de communes distinctes interrogées dans le mois — verdicts, lecture de commune et plafond à l'unité confondus. Au-delà du quota d'appels, l'appel de verdict reste servi et se facture 0,05 € l'unité lorsque votre abonnement porte la facturation au dépassement — le bloc « Facturation » de l'espace client indique si c'est le cas ; sans elle, il reçoit un refus 429. Les contrôles de numéro et les communes distinctes n'ont pas de dépassement : leur plafond est ferme. Les paliers publics vont de 2 000 à 50 000 appels par mois.

Le contrat fixe la famille d'en-têtes X-Quota-*, portée par chaque réponse. Y sont exposés, pour la fenêtre mensuelle en cours : la limite et le restant du quota d'appels de verdict, la limite et le restant du quota de communes distinctes, la fin de la fenêtre et, pour un appel de verdict servi au-delà du quota, le nombre d'appels du mois facturés au dépassement. Les suffixes exacts sont ceux que la réponse porte — lisez-les, ne les devinez pas : le contrat 1.0.0 nomme la famille, pas chaque en-tête.

Un quota atteint sans dépassement facturable répond 429, les mêmes en-têtes détaillant la fenêtre. Le plafond de débit par clé, lui, répond aussi 429 avec une erreur distincte : il borne la cadence, jamais le volume, et ne se facture pas. La table des plafonds et le flux de changements restent servis en entier, sous plafond de débit : c'est la donnée d'appel, elle n'est pas rationnée.

Points d'accès

Tout ce qui suit est engendré depuis le contrat committé : si un champ change là-bas, il change ici. Les chemins sont relatifs au serveur https://api.locaclear.fr/v1.

`POST` `/verdicts`

Les règles des deux régimes à une adresse

Le volet courte_duree rend `etabli` ou `non_couvert` ; le volet permis_de_louer rend les trois états. Cette asymétrie est celle du corpus, dite plutôt que masquée (voir VoletAbsenceEtablie).

Corps de la requête — forme 1 sur 2

adresse chaîne · requis

                    curl -X POST https://api.locaclear.fr/v1/verdicts \
  -H "Authorization: Bearer lck_live_…" \
  -H "content-type: application/json" \
  -d '{"adresse":"14 rue du Sémaphore, 99999 Portneuve"}'

Corps de la requête — forme 2 sur 2

lon nombre · requis
lat nombre · requis
insee chaîne (Insee) · requis

                    curl -X POST https://api.locaclear.fr/v1/verdicts \
  -H "Authorization: Bearer lck_live_…" \
  -H "content-type: application/json" \
  -d '{"lon":-1.234567,"lat":46.987654,"insee":"99999"}'

Réponses

200 Verdict par volet, aux trois états.
400 Corps ou paramètres invalides.
401 Clé absente, inconnue ou révoquée.
429 Quota atteint. Trois cas, distingués par le champ `erreur` : `quota_atteint` (appels du mois — pour les verdicts, seulement quand la souscription ne porte pas la facturation au dépassement : avec elle, l'appel est servi et facturé), `quota_communes_atteint` (communes distinctes du mois — les communes déjà interrogées ce mois-ci restent servies), `debit_depasse` (cadence de la clé, indépendante du volume). Les en-têtes X-Quota-* détaillent la fenêtre.

Schéma de la réponse 200

version « v1 » · requis
date_corpus chaîne (date) · requis
adresse objet · requis
libelle chaîne
insee chaîne (Insee) · requis
commune chaîne · requis
lon nombre
lat nombre
volets objet · requis
courte_duree Volet · requis
VoletEtabli objet VoletEtabli
etat « etabli » · requis
faits tableau d'objets Fait · requis
secteur objet — Résolution du point dans les périmètres numérisés du volet. Quatre constats, jamais fusionnés : `dans-secteur`, `hors-secteur`, `zonage-textuel` (des secteurs existent mais ne sont pas numérisés), `sans-zonage` (aucun secteur documenté pour ce volet).
faits_non_documentes tableau de chaînes · requis — Clés des faits du volet restés « inconnu » sur cette commune (ex. limiteResidencePrincipaleJours). Un volet établi ne cache jamais ce qu'il ne sait pas.
VoletAbsenceEtablie objet VoletAbsenceEtablie — En v1, cet état n'existe que sur le volet permis_de_louer : le corpus porte un fait d'absence pour ce régime (regime = « aucun », sourcé). Le volet courte_duree n'a aujourd'hui aucun fait capable d'établir une absence d'ensemble — il ne rend donc jamais cet état, plutôt que de le simuler.
etat « absence_etablie » · requis
fondement objet Fait · requis
VoletNonCouvert objet VoletNonCouvert — Le volet n'est pas établi par le corpus. Sans `constat`, une demande de collecte est ouverte (`collecte.demandee_le`). Avec `constat`, la collecte a déjà eu lieu : les registres officiels lus n'ont rien rendu à la date dite, et ceux qui n'ont pas pu être consultés sont nommés (`non_consultes`) — le volet reste non couvert, aucune nouvelle demande n'est ouverte (`collecte.demandee_le` vaut `null`), et le cadre national s'applique en l'absence de règle locale publiée.
etat « non_couvert » · requis
collecte objet · requis
constat objet ConstatRegistre — Constat de registre : ce qui a été interrogé — les registres officiels des actes réellement lus, les termes, la portée de la recherche, la période —, ce qui n'a pas pu être consulté, et rien sur l'existence d'une règle. `phrase` est la formulation publiée, composée une seule fois par le moteur ; elle n'affirme jamais l'absence de règle locale.
permis_de_louer Volet · requis
VoletEtabli objet VoletEtabli
etat « etabli » · requis
faits tableau d'objets Fait · requis
secteur objet — Résolution du point dans les périmètres numérisés du volet. Quatre constats, jamais fusionnés : `dans-secteur`, `hors-secteur`, `zonage-textuel` (des secteurs existent mais ne sont pas numérisés), `sans-zonage` (aucun secteur documenté pour ce volet).
faits_non_documentes tableau de chaînes · requis — Clés des faits du volet restés « inconnu » sur cette commune (ex. limiteResidencePrincipaleJours). Un volet établi ne cache jamais ce qu'il ne sait pas.
VoletAbsenceEtablie objet VoletAbsenceEtablie — En v1, cet état n'existe que sur le volet permis_de_louer : le corpus porte un fait d'absence pour ce régime (regime = « aucun », sourcé). Le volet courte_duree n'a aujourd'hui aucun fait capable d'établir une absence d'ensemble — il ne rend donc jamais cet état, plutôt que de le simuler.
etat « absence_etablie » · requis
fondement objet Fait · requis
VoletNonCouvert objet VoletNonCouvert — Le volet n'est pas établi par le corpus. Sans `constat`, une demande de collecte est ouverte (`collecte.demandee_le`). Avec `constat`, la collecte a déjà eu lieu : les registres officiels lus n'ont rien rendu à la date dite, et ceux qui n'ont pas pu être consultés sont nommés (`non_consultes`) — le volet reste non couvert, aucune nouvelle demande n'est ouverte (`collecte.demandee_le` vaut `null`), et le cadre national s'applique en l'absence de règle locale publiée.
etat « non_couvert » · requis
collecte objet · requis
constat objet ConstatRegistre — Constat de registre : ce qui a été interrogé — les registres officiels des actes réellement lus, les termes, la portée de la recherche, la période —, ce qui n'a pas pu être consulté, et rien sur l'existence d'une règle. `phrase` est la formulation publiée, composée une seule fois par le moteur ; elle n'affirme jamais l'absence de règle locale.
socle_national objet SocleNational · requis
faits tableau d'objets Fait · requis
cle chaîne · requis
valeur objet · requis
source objet Source · requis — La source telle que la fiche la porte : `reference` est la chaîne brute (URL, ou référence d'un échange officiel sans URL), `url` n'est présente que quand la référence en est une, `libelle` vient de la bibliographie de la commune quand la jointure existe.
reference chaîne · requis
url chaîne ou null (uri)
libelle chaîne ou null
type chaîne · requis
citation chaîne
verifie_le chaîne (date) · requis
statut « verifie » | « a_confirmer » · requis
avertissement chaîne · requis

Schéma de la réponse 400

erreur chaîne · requis
detail chaîne

Schéma de la réponse 401

erreur chaîne · requis
detail chaîne

Schéma de la réponse 429

erreur chaîne · requis
detail chaîne

`GET` `/communes/{insee}`

L'état d'une commune, par volet, sans résolution de secteur

Paramètres

insee chemin · requis


                curl -X GET https://api.locaclear.fr/v1/communes/99999 \
  -H "Authorization: Bearer lck_live_…"

Réponses

200 Couverture et régimes établis de la commune.
401 Clé absente, inconnue ou révoquée.
404 Le paramètre n'est pas un code INSEE bien formé (cinq caractères, le second pouvant être A ou B pour la Corse). Un code BIEN FORMÉ ne rend jamais 404, même inconnu de nous : aucun référentiel des ~34 800 communes françaises n'est embarqué, et répondre « ce code n'existe pas » à propos d'une commune réelle jamais rencontrée affirmerait un fait que rien n'établit. Une commune absente du corpus répond donc 200, à l'état non_couvert — c'est exactement ce que cet état veut dire.
429 Quota atteint. Trois cas, distingués par le champ `erreur` : `quota_atteint` (appels du mois — pour les verdicts, seulement quand la souscription ne porte pas la facturation au dépassement : avec elle, l'appel est servi et facturé), `quota_communes_atteint` (communes distinctes du mois — les communes déjà interrogées ce mois-ci restent servies), `debit_depasse` (cadence de la clé, indépendante du volume). Les en-têtes X-Quota-* détaillent la fenêtre.

Schéma de la réponse 200

version « v1 » · requis
date_corpus chaîne (date) · requis
insee chaîne (Insee) · requis
commune chaîne · requis
volets objet · requis
courte_duree Volet · requis
VoletEtabli objet VoletEtabli
etat « etabli » · requis
faits tableau d'objets Fait · requis
secteur objet — Résolution du point dans les périmètres numérisés du volet. Quatre constats, jamais fusionnés : `dans-secteur`, `hors-secteur`, `zonage-textuel` (des secteurs existent mais ne sont pas numérisés), `sans-zonage` (aucun secteur documenté pour ce volet).
faits_non_documentes tableau de chaînes · requis — Clés des faits du volet restés « inconnu » sur cette commune (ex. limiteResidencePrincipaleJours). Un volet établi ne cache jamais ce qu'il ne sait pas.
VoletAbsenceEtablie objet VoletAbsenceEtablie — En v1, cet état n'existe que sur le volet permis_de_louer : le corpus porte un fait d'absence pour ce régime (regime = « aucun », sourcé). Le volet courte_duree n'a aujourd'hui aucun fait capable d'établir une absence d'ensemble — il ne rend donc jamais cet état, plutôt que de le simuler.
etat « absence_etablie » · requis
fondement objet Fait · requis
VoletNonCouvert objet VoletNonCouvert — Le volet n'est pas établi par le corpus. Sans `constat`, une demande de collecte est ouverte (`collecte.demandee_le`). Avec `constat`, la collecte a déjà eu lieu : les registres officiels lus n'ont rien rendu à la date dite, et ceux qui n'ont pas pu être consultés sont nommés (`non_consultes`) — le volet reste non couvert, aucune nouvelle demande n'est ouverte (`collecte.demandee_le` vaut `null`), et le cadre national s'applique en l'absence de règle locale publiée.
etat « non_couvert » · requis
collecte objet · requis
constat objet ConstatRegistre — Constat de registre : ce qui a été interrogé — les registres officiels des actes réellement lus, les termes, la portée de la recherche, la période —, ce qui n'a pas pu être consulté, et rien sur l'existence d'une règle. `phrase` est la formulation publiée, composée une seule fois par le moteur ; elle n'affirme jamais l'absence de règle locale.
permis_de_louer Volet · requis
VoletEtabli objet VoletEtabli
etat « etabli » · requis
faits tableau d'objets Fait · requis
secteur objet — Résolution du point dans les périmètres numérisés du volet. Quatre constats, jamais fusionnés : `dans-secteur`, `hors-secteur`, `zonage-textuel` (des secteurs existent mais ne sont pas numérisés), `sans-zonage` (aucun secteur documenté pour ce volet).
faits_non_documentes tableau de chaînes · requis — Clés des faits du volet restés « inconnu » sur cette commune (ex. limiteResidencePrincipaleJours). Un volet établi ne cache jamais ce qu'il ne sait pas.
VoletAbsenceEtablie objet VoletAbsenceEtablie — En v1, cet état n'existe que sur le volet permis_de_louer : le corpus porte un fait d'absence pour ce régime (regime = « aucun », sourcé). Le volet courte_duree n'a aujourd'hui aucun fait capable d'établir une absence d'ensemble — il ne rend donc jamais cet état, plutôt que de le simuler.
etat « absence_etablie » · requis
fondement objet Fait · requis
VoletNonCouvert objet VoletNonCouvert — Le volet n'est pas établi par le corpus. Sans `constat`, une demande de collecte est ouverte (`collecte.demandee_le`). Avec `constat`, la collecte a déjà eu lieu : les registres officiels lus n'ont rien rendu à la date dite, et ceux qui n'ont pas pu être consultés sont nommés (`non_consultes`) — le volet reste non couvert, aucune nouvelle demande n'est ouverte (`collecte.demandee_le` vaut `null`), et le cadre national s'applique en l'absence de règle locale publiée.
etat « non_couvert » · requis
collecte objet · requis
constat objet ConstatRegistre — Constat de registre : ce qui a été interrogé — les registres officiels des actes réellement lus, les termes, la portée de la recherche, la période —, ce qui n'a pas pu être consulté, et rien sur l'existence d'une règle. `phrase` est la formulation publiée, composée une seule fois par le moteur ; elle n'affirme jamais l'absence de règle locale.

Schéma de la réponse 401

erreur chaîne · requis
detail chaîne

Schéma de la réponse 404

erreur chaîne · requis
detail chaîne

Schéma de la réponse 429

erreur chaîne · requis
detail chaîne

`GET` `/plafonds`

La table des plafonds de location de la résidence principale (art. L. 324-2-1)

Chaque ligne établie porte sa délibération source et sa date de vérification. Une commune couverte dont le plafond n'est pas documenté est rendue à l'état `non_renseigne` — jamais convertie en 120 jours par défaut : le socle national (120 jours, art. L. 324-1-1) figure séparément dans `socle_national`.

Paramètres

curseur requête · facultatif
limite requête · facultatif Lignes par page. Chaque ligne exige la lecture d'une fiche : la borne protège le budget de sous-requêtes d'une invocation, sur la route dont on attend justement qu'elle soit parcourue en entier et régulièrement.


                curl -X GET https://api.locaclear.fr/v1/plafonds \
  -H "Authorization: Bearer lck_live_…"

Réponses

200 Page de la table des plafonds.
401 Clé absente, inconnue ou révoquée.
429 Quota atteint. Trois cas, distingués par le champ `erreur` : `quota_atteint` (appels du mois — pour les verdicts, seulement quand la souscription ne porte pas la facturation au dépassement : avec elle, l'appel est servi et facturé), `quota_communes_atteint` (communes distinctes du mois — les communes déjà interrogées ce mois-ci restent servies), `debit_depasse` (cadence de la clé, indépendante du volume). Les en-têtes X-Quota-* détaillent la fenêtre.

Schéma de la réponse 200

version « v1 » · requis
date_corpus chaîne (date) · requis
socle_national objet SocleNational · requis
faits tableau d'objets Fait · requis
cle chaîne · requis
valeur objet · requis
source objet Source · requis — La source telle que la fiche la porte : `reference` est la chaîne brute (URL, ou référence d'un échange officiel sans URL), `url` n'est présente que quand la référence en est une, `libelle` vient de la bibliographie de la commune quand la jointure existe.
reference chaîne · requis
url chaîne ou null (uri)
libelle chaîne ou null
type chaîne · requis
citation chaîne
verifie_le chaîne (date) · requis
statut « verifie » | « a_confirmer » · requis
plafonds tableau d'objets Plafond · requis
insee chaîne (Insee) · requis
commune chaîne · requis
etat « etabli » | « non_renseigne » | « non_couvert » · requis
jours « 90 » | « 120 »
source objet Source — La source telle que la fiche la porte : `reference` est la chaîne brute (URL, ou référence d'un échange officiel sans URL), `url` n'est présente que quand la référence en est une, `libelle` vient de la bibliographie de la commune quand la jointure existe.
reference chaîne · requis
url chaîne ou null (uri)
libelle chaîne ou null
type chaîne · requis
citation chaîne
verifie_le chaîne (date)
curseur_suivant chaîne ou null

Schéma de la réponse 401

erreur chaîne · requis
detail chaîne

Schéma de la réponse 429

erreur chaîne · requis
detail chaîne

`GET` `/plafonds/{insee}`

Le plafond d'une commune

Paramètres

insee chemin · requis


                curl -X GET https://api.locaclear.fr/v1/plafonds/99999 \
  -H "Authorization: Bearer lck_live_…"

Réponses

200 La ligne de la commune.
401 Clé absente, inconnue ou révoquée.
404 Le paramètre n'est pas un code INSEE bien formé (cinq caractères, le second pouvant être A ou B pour la Corse). Un code BIEN FORMÉ ne rend jamais 404, même inconnu de nous : aucun référentiel des ~34 800 communes françaises n'est embarqué, et répondre « ce code n'existe pas » à propos d'une commune réelle jamais rencontrée affirmerait un fait que rien n'établit. Une commune absente du corpus répond donc 200, à l'état non_couvert — c'est exactement ce que cet état veut dire.
429 Quota atteint. Trois cas, distingués par le champ `erreur` : `quota_atteint` (appels du mois — pour les verdicts, seulement quand la souscription ne porte pas la facturation au dépassement : avec elle, l'appel est servi et facturé), `quota_communes_atteint` (communes distinctes du mois — les communes déjà interrogées ce mois-ci restent servies), `debit_depasse` (cadence de la clé, indépendante du volume). Les en-têtes X-Quota-* détaillent la fenêtre.

Schéma de la réponse 200

insee chaîne (Insee) · requis
commune chaîne · requis
etat « etabli » | « non_renseigne » | « non_couvert » · requis
jours « 90 » | « 120 »
source objet Source — La source telle que la fiche la porte : `reference` est la chaîne brute (URL, ou référence d'un échange officiel sans URL), `url` n'est présente que quand la référence en est une, `libelle` vient de la bibliographie de la commune quand la jointure existe.
reference chaîne · requis
url chaîne ou null (uri)
libelle chaîne ou null
type chaîne · requis
citation chaîne
verifie_le chaîne (date)

Schéma de la réponse 401

erreur chaîne · requis
detail chaîne

Schéma de la réponse 404

erreur chaîne · requis
detail chaîne

Schéma de la réponse 429

erreur chaîne · requis
detail chaîne

`POST` `/numeros-enregistrement/verifications`

Contrôle documentaire d'un numéro d'enregistrement

Contrôle de forme fondé sur l'article D. 324-1-1 II du code du tourisme (13 caractères : code INSEE sur 5 chiffres, numéro d'ordre sur 6 chiffres, clé de contrôle sur 2 caractères déterminée par la commune). La clé de contrôle est communale, donc invérifiable de l'extérieur : le contrôle `cle_communale` rend toujours `non_verifiable`. Aucun registre d'État n'est consulté — un numéro bien formé n'est pas un numéro délivré, et la réponse le dit.

Corps de la requête

numero chaîne · requis
insee chaîne (Insee) · requis

                    curl -X POST https://api.locaclear.fr/v1/numeros-enregistrement/verifications \
  -H "Authorization: Bearer lck_live_…" \
  -H "content-type: application/json" \
  -d '{"numero":"99999012345AB","insee":"99999"}'

Réponses

200 Résultat des contrôles, contrôle par contrôle.
400 Corps ou paramètres invalides.
401 Clé absente, inconnue ou révoquée.
429 Quota atteint. Trois cas, distingués par le champ `erreur` : `quota_atteint` (appels du mois — pour les verdicts, seulement quand la souscription ne porte pas la facturation au dépassement : avec elle, l'appel est servi et facturé), `quota_communes_atteint` (communes distinctes du mois — les communes déjà interrogées ce mois-ci restent servies), `debit_depasse` (cadence de la clé, indépendante du volume). Les en-têtes X-Quota-* détaillent la fenêtre.

Schéma de la réponse 200

version « v1 » · requis
numero chaîne · requis
controles tableau d'objets · requis
nom « longueur » | « structure » | « prefixe_insee » | « cle_communale » · requis
resultat « forme_attendue » | « ecart » | « non_verifiable » · requis
detail chaîne
avertissement chaîne · requis

Schéma de la réponse 400

erreur chaîne · requis
detail chaîne

Schéma de la réponse 401

erreur chaîne · requis
detail chaîne

Schéma de la réponse 429

erreur chaîne · requis
detail chaîne

`GET` `/changements`

Le flux des communes dont la fiche a changé

Curseur opaque, ordre stable, rejouable : le même curseur redonne la même page. Un client qui suit ce flux n'a jamais besoin de re-balayer la base.

Paramètres

curseur requête · facultatif
limite requête · facultatif


                curl -X GET https://api.locaclear.fr/v1/changements \
  -H "Authorization: Bearer lck_live_…"

Réponses

200 Page de changements et curseur suivant.
401 Clé absente, inconnue ou révoquée.
429 Quota atteint. Trois cas, distingués par le champ `erreur` : `quota_atteint` (appels du mois — pour les verdicts, seulement quand la souscription ne porte pas la facturation au dépassement : avec elle, l'appel est servi et facturé), `quota_communes_atteint` (communes distinctes du mois — les communes déjà interrogées ce mois-ci restent servies), `debit_depasse` (cadence de la clé, indépendante du volume). Les en-têtes X-Quota-* détaillent la fenêtre.

Schéma de la réponse 200

version « v1 » · requis
changements tableau d'objets Changement · requis
insee chaîne (Insee) · requis
commune chaîne · requis
constate_le chaîne (date-time) · requis — Instant du passage de balayage qui a CONSTATÉ le changement — pas la date d'entrée en vigueur de la règle, que le corpus porte sur le fait lui-même (`verifie_le`). Horodatage complet et non simple date : le balayage peut tourner plusieurs fois par jour, et un client qui suit le flux doit pouvoir ordonner deux constats du même jour.
empreinte chaîne · requis
volets_touches tableau de chaînes
curseur_suivant chaîne ou null · requis

Schéma de la réponse 401

erreur chaîne · requis
detail chaîne

Schéma de la réponse 429

erreur chaîne · requis
detail chaîne

`GET` `/collectes`

Les demandes de collecte de l'organisation et leur issue

Une commune hors corpus interrogée par l'organisation (réponse `non_couvert` sans `constat`) ouvre une demande de collecte. Cette liste en rend l'état, les plus récentes d'abord (100 au plus) : `ouverte`, ou `couverte` (chaque volet visé est désormais établi, ou porte un constat de registre daté de 30 jours au plus avant la demande, ou d'après — la réponse le rend alors sous `constat`). `sans_conclusion` n'est plus écrit depuis le 31 octobre 2026 : une demande sans issue est relancée, jamais close ; la valeur reste lisible sur les demandes closes avant cette date. L'issue est aussi POSTée aux webhooks actifs de la seule organisation demandeuse, avec `type: "collecte"` et la même signature que les changements. Ce flux est privé : il n'apparaît pas dans `/changements`.


                curl -X GET https://api.locaclear.fr/v1/collectes \
  -H "Authorization: Bearer lck_live_…"

Réponses

200 Demandes de collecte de l'organisation.
401 Clé absente, inconnue ou révoquée.
429 Quota atteint. Trois cas, distingués par le champ `erreur` : `quota_atteint` (appels du mois — pour les verdicts, seulement quand la souscription ne porte pas la facturation au dépassement : avec elle, l'appel est servi et facturé), `quota_communes_atteint` (communes distinctes du mois — les communes déjà interrogées ce mois-ci restent servies), `debit_depasse` (cadence de la clé, indépendante du volume). Les en-têtes X-Quota-* détaillent la fenêtre.

Schéma de la réponse 200

version « v1 » · requis
collectes tableau d'objets Collecte · requis
insee chaîne (Insee) · requis
commune chaîne · requis
statut « ouverte » | « couverte » | « sans_conclusion » · requis
demandee_le chaîne (date-time) · requis
close_le chaîne ou null (date-time) · requis — Instant de l'issue (couverte ou close sans conclusion) ; `null` tant que la demande est ouverte.

Schéma de la réponse 401

erreur chaîne · requis
detail chaîne

Schéma de la réponse 429

erreur chaîne · requis
detail chaîne

`GET` `/webhooks`

Les abonnements de rappel de l'organisation


                curl -X GET https://api.locaclear.fr/v1/webhooks \
  -H "Authorization: Bearer lck_live_…"

Réponses

200 Liste des abonnements.
401 Clé absente, inconnue ou révoquée.
429 Quota atteint. Trois cas, distingués par le champ `erreur` : `quota_atteint` (appels du mois — pour les verdicts, seulement quand la souscription ne porte pas la facturation au dépassement : avec elle, l'appel est servi et facturé), `quota_communes_atteint` (communes distinctes du mois — les communes déjà interrogées ce mois-ci restent servies), `debit_depasse` (cadence de la clé, indépendante du volume). Les en-têtes X-Quota-* détaillent la fenêtre.

Schéma de la réponse 200

webhooks tableau d'objets Webhook · requis
id chaîne · requis
url chaîne (uri) · requis
cree_le chaîne (date-time) · requis
actif booléen · requis
coupe_le chaîne ou null (date-time)

Schéma de la réponse 401

erreur chaîne · requis
detail chaîne

Schéma de la réponse 429

erreur chaîne · requis
detail chaîne

`POST` `/webhooks`

S'abonner aux changements par URL de rappel

Chaque livraison est un POST JSON signé : l'en-tête X-Locaclear-Signature porte sha256=HMAC-SHA256(corps, secret), le secret étant celui rendu à la création de l'abonnement. Relivraison en cas d'échec avec recul (5 min, 15 min, 1 h, 6 h, 24 h), coupure de l'abonnement après 8 échecs consécutifs.

Corps de la requête

url chaîne (uri) · requis

                    curl -X POST https://api.locaclear.fr/v1/webhooks \
  -H "Authorization: Bearer lck_live_…" \
  -H "content-type: application/json" \
  -d '{"url":"https://exemple.test/rappels-reglementation"}'

Réponses

201 Abonnement créé ; le secret de signature n'est montré qu'une fois.
400 Corps ou paramètres invalides.
401 Clé absente, inconnue ou révoquée.
429 Quota atteint. Trois cas, distingués par le champ `erreur` : `quota_atteint` (appels du mois — pour les verdicts, seulement quand la souscription ne porte pas la facturation au dépassement : avec elle, l'appel est servi et facturé), `quota_communes_atteint` (communes distinctes du mois — les communes déjà interrogées ce mois-ci restent servies), `debit_depasse` (cadence de la clé, indépendante du volume). Les en-têtes X-Quota-* détaillent la fenêtre.

Schéma de la réponse 201

id chaîne · requis
url chaîne (uri) · requis
cree_le chaîne (date-time) · requis
actif booléen · requis
coupe_le chaîne ou null (date-time)
secret chaîne · requis

Schéma de la réponse 400

erreur chaîne · requis
detail chaîne

Schéma de la réponse 401

erreur chaîne · requis
detail chaîne

Schéma de la réponse 429

erreur chaîne · requis
detail chaîne

`DELETE` `/webhooks/{id}`

Résilier un abonnement de rappel

Paramètres

id chemin · requis


                curl -X DELETE https://api.locaclear.fr/v1/webhooks/wh_2f7a91c4 \
  -H "Authorization: Bearer lck_live_…"

Réponses

204 Abonnement supprimé.
401 Clé absente, inconnue ou révoquée.
404 Ressource inconnue pour cette organisation.
429 Quota atteint. Trois cas, distingués par le champ `erreur` : `quota_atteint` (appels du mois — pour les verdicts, seulement quand la souscription ne porte pas la facturation au dépassement : avec elle, l'appel est servi et facturé), `quota_communes_atteint` (communes distinctes du mois — les communes déjà interrogées ce mois-ci restent servies), `debit_depasse` (cadence de la clé, indépendante du volume). Les en-têtes X-Quota-* détaillent la fenêtre.

Schéma de la réponse 401

erreur chaîne · requis
detail chaîne

Schéma de la réponse 404

erreur chaîne · requis
detail chaîne

Schéma de la réponse 429

erreur chaîne · requis
detail chaîne

`GET` `/moi`

L'organisation, le palier et la consommation du mois


                curl -X GET https://api.locaclear.fr/v1/moi \
  -H "Authorization: Bearer lck_live_…"

Réponses

200 Situation du compte API.
401 Clé absente, inconnue ou révoquée.
429 Quota atteint. Trois cas, distingués par le champ `erreur` : `quota_atteint` (appels du mois — pour les verdicts, seulement quand la souscription ne porte pas la facturation au dépassement : avec elle, l'appel est servi et facturé), `quota_communes_atteint` (communes distinctes du mois — les communes déjà interrogées ce mois-ci restent servies), `debit_depasse` (cadence de la clé, indépendante du volume). Les en-têtes X-Quota-* détaillent la fenêtre.

Schéma de la réponse 200

organisation objet · requis
id chaîne · requis
nom chaîne · requis
palier objet · requis
nom chaîne · requis
quotas objet · requis — Une clé ABSENTE signifie « négocié au contrat » (palier entreprise) ; une clé à `null` signifie « non borné » (numéros du palier échelle). Aucun plafond n'est inventé pour combler une absence : un chiffre écrit ici deviendrait opposable à un client qui a signé autre chose.
verdicts_mois entier
numeros_mois entier ou null
communes_distinctes_mois entier
consommation objet · requis
mois chaîne · requis
verdicts entier · requis
numeros entier · requis
communes_distinctes entier

Schéma de la réponse 401

erreur chaîne · requis
detail chaîne

Schéma de la réponse 429

erreur chaîne · requis
detail chaîne

Une réponse complète, sur la commune fictive de Portneuve

{
  "version": "v1",
  "date_corpus": "2026-06-12",
  "adresse": {
    "libelle": "14 rue du Sémaphore, 99999 Portneuve",
    "insee": "99999",
    "commune": "Portneuve"
  },
  "volets": {
    "courte_duree": {
      "etat": "etabli",
      "faits": [
        {
          "cle": "changementUsageRequis",
          "valeur": "oui",
          "source": {
            "reference": "délibération n° 2024-087 du 12 septembre 2024",
            "url": null,
            "libelle": "Commune de Portneuve — délibération n° 2024-087 du 12 septembre 2024",
            "type": "acte-officiel"
          },
          "citation": "Le changement d'usage d'un local d'habitation loué en meublé de tourisme est soumis à autorisation préalable du maire.",
          "verifie_le": "2026-06-12",
          "statut": "verifie"
        },
        {
          "cle": "limiteResidencePrincipaleJours",
          "valeur": 90,
          "source": {
            "reference": "délibération n° 2025-012 du 3 février 2025",
            "url": null,
            "libelle": "Commune de Portneuve — délibération n° 2025-012 du 3 février 2025",
            "type": "acte-officiel"
          },
          "citation": "La durée annuelle de location d'un meublé déclaré comme résidence principale est abaissée à quatre-vingt-dix jours par année civile.",
          "verifie_le": "2026-06-12",
          "statut": "verifie"
        }
      ],
      "secteur": {
        "constat": "dans-secteur",
        "zonage": "secteur « Front de mer »",
        "precision": "parcellaire"
      },
      "faits_non_documentes": [
        "reglesResidenceSecondaire"
      ]
    },
    "permis_de_louer": {
      "etat": "etabli",
      "faits": [
        {
          "cle": "regime",
          "valeur": "autorisation",
          "source": {
            "reference": "délibération communautaire n° 2023-054 du 16 novembre 2023",
            "url": null,
            "libelle": "Communauté d'agglomération de Portneuve — délibération communautaire n° 2023-054 du 16 novembre 2023",
            "type": "acte-officiel"
          },
          "citation": "La mise en location d'un logement situé dans les secteurs délimités par la présente délibération est soumise à autorisation préalable.",
          "verifie_le": "2026-06-12",
          "statut": "a_confirmer"
        }
      ],
      "secteur": {
        "constat": "hors-secteur",
        "zonage": null,
        "precision": "parcellaire"
      },
      "faits_non_documentes": []
    }
  },
  "socle_national": {
    "faits": [
      {
        "cle": "enregistrementObligatoire",
        "valeur": "oui",
        "source": {
          "reference": "https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000050649989/",
          "url": "https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000050649989/",
          "libelle": "Code du tourisme, article L. 324-1-1",
          "type": "texte-national"
        },
        "citation": "La déclaration donne lieu à la délivrance sans délai d'un numéro par le téléservice national.",
        "verifie_le": "2026-06-12",
        "statut": "verifie"
      }
    ]
  },
  "avertissement": "Restitution documentaire des règles publiées, source et date à l'appui. Ne porte aucune appréciation sur une situation individuelle."
}

Rappels signés

Un abonnement de rappel reçoit, sans interrogation, une requête POST au corps JSON par événement. Le champ type les distingue : changement (une fiche communale modifiée, mêmes champs qu'une ligne du flux, pour toutes les communes du corpus — filtrez sur le code INSEE) et collecte (l'issue d'une de vos demandes de collecte). Seuls les changements constatés après la création de l'abonnement lui sont envoyés, et seulement tant qu'un palier est en cours.

À la création, un secret propre à l'abonnement est rendu une seule fois : il n'est pas réaffichable. Chaque livraison porte UN en-tête de signature, X-Locaclear-Signature, dont la valeur est sha256= suivi du HMAC-SHA256, en hexadécimal, du corps brut de la requête calculé avec ce secret. Aucun horodatage n'entre dans le calcul.

attendu = "sha256=" + hex( hmac_sha256( secret, corps_brut ) )

Vérifiez la signature sur le corps brut, avant toute analyse syntaxique, et comparez en temps constant. Une livraison en échec est rejouée avec un recul croissant ; après une série d'échecs, l'abonnement est coupé et le champ coupe_le le date. Le flux /changements reste alors la voie de rattrapage : son curseur est rejouable, aucun changement n'est perdu.

Journal des versions

Le contrat est versionné par préfixe d'URL. Un champ ajouté ou une valeur d'énumération ajoutée restent dans /v1/ : traitez les champs inconnus sans échouer. Un champ retiré, ou dont le sens change, ouvre un /v2/ servi en parallèle.

1.0.0 5 septembre 2026

Première version publiée du contrat : verdicts aux trois états, table des plafonds, contrôle de numéro d'enregistrement, flux de changements et rappels signés.

Les paliers, les quotas et le cadre de licence sont décrits sur la page de l'offre. Les clés se gèrent dans l'onglet API de l'espace client.

Service d'information — ne constitue ni un conseil fiscal, ni un conseil juridique. Résultats indicatifs, hors régime réel et cas particuliers.

Documentation développeur

Authentification

Bac à sable

Les trois états, par volet

Le secteur : quatre constats, jamais un booléen

Quotas et en-têtes

Points d'accès

POST /verdicts

GET /communes/{insee}

GET /plafonds

GET /plafonds/{insee}

POST /numeros-enregistrement/verifications

GET /changements

GET /collectes

GET /webhooks

POST /webhooks

DELETE /webhooks/{id}

GET /moi

Rappels signés

Journal des versions

`POST` `/verdicts`

`GET` `/communes/{insee}`

`GET` `/plafonds`

`GET` `/plafonds/{insee}`

`POST` `/numeros-enregistrement/verifications`

`GET` `/changements`

`GET` `/collectes`

`GET` `/webhooks`

`POST` `/webhooks`

`DELETE` `/webhooks/{id}`

`GET` `/moi`