EN
Copied
Modules

Données légales FR

Le module legal_data enrichit une liste de POI avec les données officielles des sources légales publiques françaises. Pour chaque ligne d'entrée, le module interroge api.gouv.fr (SIRENE, INPI, RNCS) et complète la réponse avec les annonces légales BODACC et les extraits publics Infogreffe. Le résultat est un profil structuré rattaché à chaque entreprise : forme juridique, capital, dirigeants enregistrés, code NAF, tranche d'effectif, finances clés, et un statut de lead consolidé.

Le module est en lecture seule : aucun identifiant requis, aucune facturation par les sources amont, aucune entreprise contactée dans le cadre de la recherche.

Aucun site web requis. Contrairement à legal_ids qui lit les identifiants sur un site web, ce module recherche chaque ligne par nom + adresse dans SIRENE et renvoie aussi le SIRET/SIREN. C'est le bon choix quand votre liste n'a pas de colonne site web — par exemple un scrap Google Maps avec seulement des noms et des liens Maps.

Objectif

Les listes de prospection B2B françaises démarrent généralement avec un nom, une adresse, parfois un site. legal_data transforme chaque ligne en fiche entreprise qualifiée à partir des seuls registres publics.

Cas d'usage typiques :

Entrées

legal_data est un module d'enrichissement : il consomme une liste de POI existante, il n'en produit pas. L'entrée attendue est un poi_list, typiquement la sortie d'un job de découverte.

Champ Requis Notes
nom oui Raison sociale, utilisée pour le rapprochement fuzzy.
siren non Si présent, utilisé pour un match exact (préféré).
code_postal non Désambiguïse les rapprochements fuzzy.
lat, lon non Repli géographique quand nom et SIREN échouent.

La résolution suit trois niveaux, dans l'ordre :

  1. Recherche exacte par SIREN quand l'identifiant est fourni.
  2. Rapprochement fuzzy sur nom + code_postal.
  3. Repli géographique sur coordonnées dans un petit rayon.

Une ligne qui ne se résout à aucun niveau est renvoyée avec des colonnes d'enrichissement vides et un code d'erreur (voir Erreurs).

Sorties

Chaque ligne d'entrée est augmentée des colonnes suivantes. Les valeurs vides sont préservées en chaînes vides — le module ne fabrique jamais de valeur.

Colonne Type Description
legal_form string Forme juridique (SAS, SARL, SA, EI, association, etc.).
capital number Capital social enregistré en EUR.
founding_date date Date d'immatriculation au registre.
executives list Dirigeants nommés avec rôle (Président, Gérant, DG).
financials object Dernier CA et résultat net disponibles, avec l'exercice fiscal.
naf_code string Code d'activité NAF/APE à cinq caractères.
employees_range string Tranche d'effectif INSEE (ex. 10-19, 100-199).

Un lead_status consolidé est également renvoyé, prenant une des quatre valeurs : mort, alerte, opportunite, actif. Il encode la combinaison de l'état administratif, des signaux BODACC et de la récence des événements légaux.

Cycle de vie

Cycle de job standard — voir Cycle de vie des jobs. La progression est reportée par établissement traité. Le job est idempotent à l'échelle d'une session : ré-exécuter sur la même liste d'entrée donne les mêmes colonnes enrichies, aux mises à jour amont près.

Pipeline

needs:     poi_list
produces:  enriched_list

legal_data consomme un poi_list et émet un enriched_list portant les lignes d'origine plus les colonnes décrites dans Sorties. La liste enrichie peut elle-même être consommée par des modules d'enrichissement en aval (legal_mentions, legal_ids, etc.).

Endpoints

Créer un job

POST /api/jobs/legal-data

Corps de requête :

{
  "items": [
    { "nom": "Boulangerie Martin", "code_postal": "75011" },
    { "siren": "552120222" }
  ],
  "source_job_id": "job_01HXYZ..."
}

Soit items, soit source_job_id doit être fourni. Quand source_job_id référence un job de découverte terminé, ses lignes sont utilisées comme entrée directement.

Réponse : une ressource Job avec id, type, status, et champs de progression.

Récupérer un job

GET /api/jobs/{job_id}

Renvoie l'état courant, les compteurs de progression et — quand done — l'URL de téléchargement du CSV enrichi.

Lister les jobs

GET /api/jobs?type=legal_data

Maximum 5 000 lignes par job. Les listes plus grandes doivent être découpées côté client. Quotas globaux et limites de débit : voir Limites.

Les chiffres financiers dépendent du dépôt de comptes par la société (environ 60 % des PME françaises). Les noms de dirigeants reflètent le dernier dépôt ; les changements récents peuvent mettre quelques semaines à se propager.

Erreurs

Les erreurs ligne sont reportées dans une colonne error sur la sortie enrichie. Les erreurs job font passer le job en failed.

Code Portée Signification
not_found ligne Aucun match SIRENE pour le nom et le code postal fournis.
foreign_business ligne Établissement non immatriculé en France.
ambiguous_match ligne Plusieurs candidats à score égal ; aucun sélectionné.
source_unavailable job Une ou plusieurs sources publiques amont sont injoignables.
quota_exceeded job Quota d'usage équitable journalier atteint ; réessayer demain.
invalid_input job Liste d'entrée vide ou champs requis manquants.

Un échec source_unavailable préserve toutes les lignes déjà enrichies avant la coupure. Le job peut être resoumis avec les lignes restantes une fois la source amont rétablie.

Et après