{
 "openapi": "3.1.0",
 "info": {
  "title": "OpenBase API",
  "version": "v1",
  "description": "API REST d'OpenBase (openbase.fr) sur les entreprises françaises, construite à partir des données publiques INSEE Sirene, INPI RNE, BODACC et des listes de sanctions ONU / DG Trésor. Sans clé : 30 requêtes par jour et par adresse IP (60 par minute au plus) ; clé gratuite (email seul, 100 000 requêtes par mois) sur https://openbase.fr/mcp/free ; l'historique des comptes annuels exige une clé (Authorization: Bearer opb_… ou ?key=opb_…). Offres : https://openbase.fr/api-pro. Un serveur MCP est aussi disponible : https://openbase.fr/mcp. Exemple d'appel : GET https://openbase.fr/api/v1/recherche?q=danone puis GET https://openbase.fr/api/v1/entreprise/{siren}.",
  "contact": {
   "name": "OpenBase",
   "email": "contact@openbase.fr",
   "url": "https://openbase.fr/api-docs"
  },
  "termsOfService": "https://openbase.fr/cgv"
 },
 "externalDocs": {
  "description": "Documentation",
  "url": "https://openbase.fr/api-docs"
 },
 "servers": [
  {
   "url": "https://openbase.fr"
  }
 ],
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "description": "Clé opb_…"
   },
   "cle": {
    "type": "apiKey",
    "in": "query",
    "name": "key"
   }
  }
 },
 "paths": {
  "/api/v1": {
   "get": {
    "operationId": "descripteur",
    "summary": "Descripteur de l'API",
    "description": "Liste des points d'accès, limites et contact.",
    "tags": [
     "API"
    ],
    "parameters": [],
    "responses": {
     "200": {
      "description": "Réponse JSON",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Paramètre invalide"
     },
     "404": {
      "description": "Entreprise introuvable"
     },
     "429": {
      "description": "Limite atteinte (sans clé : 30 requêtes par jour et par IP). La réponse indique comment créer une clé gratuite."
     }
    }
   }
  },
  "/api/v1/recherche": {
   "get": {
    "operationId": "rechercher",
    "summary": "Rechercher une entreprise",
    "description": "Recherche par nom, SIREN ou SIRET.",
    "tags": [
     "Entreprises"
    ],
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "description": "Nom, SIREN ou SIRET",
      "schema": {
       "type": "string"
      },
      "example": "danone"
     }
    ],
    "responses": {
     "200": {
      "description": "Réponse JSON",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        },
        "example": {
         "query": "danone",
         "results": [
          {
           "siren": "430474262",
           "raison_sociale": "DANONE DAIRY ASIA",
           "ville": null,
           "code_postal": "75009",
           "libelle_naf": "Fonds de placement et entités financières similaires",
           "forme_juridique": "SAS",
           "chiffre_affaires": 0,
           "chiffre_affaires_annee": "2024",
           "effectif": null,
           "statut": "active",
           "date_creation": "2000-04-04"
          },
          {
           "siren": "498044932",
           "raison_sociale": "DANONE. COMMUNITIES",
           "ville": null,
           "code_postal": "75015",
           "libelle_naf": "Gestion de fonds",
           "forme_juridique": "Fonds à forme sociétale à conseil d'administration",
           "chiffre_affaires": 0,
           "chiffre_affaires_annee": "2020",
           "effectif": null,
           "statut": "active",
           "date_creation": "2007-05-04"
          }
         ]
        }
       }
      }
     },
     "400": {
      "description": "Paramètre invalide"
     },
     "404": {
      "description": "Entreprise introuvable"
     },
     "429": {
      "description": "Limite atteinte (sans clé : 30 requêtes par jour et par IP). La réponse indique comment créer une clé gratuite."
     }
    }
   }
  },
  "/api/v1/entreprise/{siren}": {
   "get": {
    "operationId": "entreprise",
    "summary": "Fiche entreprise",
    "description": "Identité, dirigeants, dernier bilan disponible et annonces BODACC.",
    "tags": [
     "Entreprises"
    ],
    "parameters": [
     {
      "name": "siren",
      "in": "path",
      "required": true,
      "description": "Numéro SIREN à 9 chiffres",
      "schema": {
       "type": "string",
       "pattern": "^[0-9]{9}$"
      },
      "example": "552032534"
     }
    ],
    "responses": {
     "200": {
      "description": "Réponse JSON",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "description": "Fiche entreprise",
         "properties": {
          "entreprise": {
           "type": "object",
           "description": "Identité Sirene/RNE, siège, activité (NAF), forme juridique, effectif, derniers chiffres disponibles",
           "properties": {
            "siren": {
             "type": "string"
            },
            "siret_siege": {
             "type": "string"
            },
            "raison_sociale": {
             "type": "string"
            },
            "nom_commercial": {
             "type": "string"
            },
            "sigle": {
             "type": "string"
            },
            "enseigne": {
             "type": "string"
            },
            "forme_juridique": {
             "type": "string"
            },
            "forme_juridique_code": {
             "type": "string"
            },
            "categorie_entreprise": {
             "type": "string"
            },
            "date_creation": {
             "type": "string"
            },
            "date_creation_etablissement": {
             "type": "string"
            },
            "date_radiation": {
             "type": "string"
            },
            "date_derniere_maj": {
             "type": "string"
            },
            "date_derniers_comptes": {
             "type": "string"
            },
            "date_cloture_exercice": {
             "type": "string"
            },
            "adresse": {
             "type": "string"
            },
            "complement_adresse": {
             "type": "string"
            },
            "code_postal": {
             "type": "string"
            },
            "ville": {
             "type": "string"
            },
            "departement": {
             "type": "string"
            },
            "region": {
             "type": "string"
            },
            "pays": {
             "type": "string"
            },
            "latitude": {
             "type": "number"
            },
            "longitude": {
             "type": "number"
            },
            "code_naf": {
             "type": "string"
            },
            "libelle_naf": {
             "type": "string"
            },
            "secteur_activite": {
             "type": "string"
            },
            "description_activite": {
             "type": "string"
            },
            "activite_principale": {
             "type": "string"
            },
            "chiffre_affaires": {
             "type": "number"
            },
            "chiffre_affaires_annee": {
             "type": "string"
            },
            "resultat_net": {
             "type": "number"
            },
            "resultat_net_annee": {
             "type": "string"
            },
            "capital_social": {
             "type": "number"
            },
            "devise": {
             "type": "string"
            },
            "score_defaillance": {
             "type": "string"
            },
            "effectif": {
             "type": "string"
            },
            "tranche_effectif": {
             "type": "string"
            },
            "tranche_effectif_code": {
             "type": "string"
            },
            "rcs": {
             "type": "string"
            },
            "greffe": {
             "type": "string"
            },
            "numero_tva": {
             "type": "string"
            },
            "code_commune": {
             "type": "string"
            },
            "telephone": {
             "type": "string"
            },
            "telephone2": {
             "type": "string"
            },
            "fax": {
             "type": "string"
            },
            "email": {
             "type": "string"
            },
            "email2": {
             "type": "string"
            },
            "site_web": {
             "type": "string"
            },
            "reseaux_sociaux": {
             "type": "string"
            },
            "nombre_etablissements": {
             "type": "number"
            },
            "est_siege": {
             "type": "number"
            },
            "statut": {
             "type": "string"
            },
            "procedure_collective": {
             "type": "string"
            },
            "pappers_url": {
             "type": "string"
            },
            "pappers_score": {
             "type": "string"
            },
            "documents_count": {
             "type": "string"
            },
            "derniere_publication_bodacc": {
             "type": "string"
            },
            "societecom_url": {
             "type": "string"
            },
            "societecom_score": {
             "type": "string"
            },
            "avis_count": {
             "type": "string"
            },
            "epro_url": {
             "type": "string"
            },
            "epro_categorie": {
             "type": "string"
            },
            "sources": {
             "type": "string"
            },
            "date_premiere_collecte": {
             "type": "string"
            },
            "date_derniere_collecte": {
             "type": "string"
            },
            "enrichissement_complet": {
             "type": "number"
            },
            "data_quality_score": {
             "type": "number"
            },
            "score_digital": {
             "type": "string"
            },
            "score_b2b": {
             "type": "string"
            },
            "score_risque": {
             "type": "string"
            },
            "scores_date": {
             "type": "string"
            },
            "justice_count": {
             "type": "number"
            }
           }
          },
          "dirigeants": {
           "type": "array",
           "description": "Mandataires sociaux publiés au RNE (nom, fonction, date de début)",
           "items": {
            "type": "object"
           }
          },
          "bilans": {
           "type": "array",
           "description": "Dernier bilan disponible (chiffre d'affaires, résultat, ratios)",
           "items": {
            "type": "object"
           }
          },
          "bodacc": {
           "type": "array",
           "description": "Annonces légales BODACC (créations, modifications, procédures collectives, radiations)",
           "items": {
            "type": "object"
           }
          },
          "etablissements_couverture": {
           "type": "object",
           "description": "Nombre d'établissements et couverture des données"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Paramètre invalide"
     },
     "404": {
      "description": "Entreprise introuvable"
     },
     "429": {
      "description": "Limite atteinte (sans clé : 30 requêtes par jour et par IP). La réponse indique comment créer une clé gratuite."
     }
    }
   }
  },
  "/api/v1/entreprise/{siren}/kbis": {
   "get": {
    "operationId": "kbis",
    "summary": "Synthèse d'identité",
    "description": "Synthèse d'identité et des mandats ; ne remplace pas un Kbis officiel.",
    "tags": [
     "Entreprises"
    ],
    "parameters": [
     {
      "name": "siren",
      "in": "path",
      "required": true,
      "description": "Numéro SIREN à 9 chiffres",
      "schema": {
       "type": "string",
       "pattern": "^[0-9]{9}$"
      },
      "example": "552032534"
     }
    ],
    "responses": {
     "200": {
      "description": "Réponse JSON",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Paramètre invalide"
     },
     "404": {
      "description": "Entreprise introuvable"
     },
     "429": {
      "description": "Limite atteinte (sans clé : 30 requêtes par jour et par IP). La réponse indique comment créer une clé gratuite."
     }
    }
   }
  },
  "/api/v1/entreprise/{siren}/scoring": {
   "get": {
    "operationId": "scoring",
    "summary": "Score 360",
    "description": "Score sur 7 axes, transparent et auditable.",
    "tags": [
     "Entreprises"
    ],
    "parameters": [
     {
      "name": "siren",
      "in": "path",
      "required": true,
      "description": "Numéro SIREN à 9 chiffres",
      "schema": {
       "type": "string",
       "pattern": "^[0-9]{9}$"
      },
      "example": "552032534"
     }
    ],
    "responses": {
     "200": {
      "description": "Réponse JSON",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Paramètre invalide"
     },
     "404": {
      "description": "Entreprise introuvable"
     },
     "429": {
      "description": "Limite atteinte (sans clé : 30 requêtes par jour et par IP). La réponse indique comment créer une clé gratuite."
     }
    }
   }
  },
  "/api/v1/entreprise/{siren}/alerte-risque": {
   "get": {
    "operationId": "alerteRisque",
    "summary": "Alerte risque",
    "description": "Niveau de risque 0 à 3 (procédures collectives, radiations, sanctions), sans garantie de solvabilité.",
    "tags": [
     "Entreprises"
    ],
    "parameters": [
     {
      "name": "siren",
      "in": "path",
      "required": true,
      "description": "Numéro SIREN à 9 chiffres",
      "schema": {
       "type": "string",
       "pattern": "^[0-9]{9}$"
      },
      "example": "552032534"
     }
    ],
    "responses": {
     "200": {
      "description": "Réponse JSON",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        },
        "example": {
         "siren": "552032534",
         "raison_sociale": "DANONE",
         "risk_level": 0,
         "risk_label": "aucun_signal_retrouve",
         "limites": "Constat sur les données disponibles, sans garantie d’exhaustivité ni de solvabilité.",
         "reasons": [],
         "procedures_collectives_36mois": [],
         "risk_signals_snapshot": {
          "risk_level": null,
          "flags": null,
          "updated_at": null
         },
         "fiche_url": "https://openbase.fr/entreprise/552032534"
        }
       }
      }
     },
     "400": {
      "description": "Paramètre invalide"
     },
     "404": {
      "description": "Entreprise introuvable"
     },
     "429": {
      "description": "Limite atteinte (sans clé : 30 requêtes par jour et par IP). La réponse indique comment créer une clé gratuite."
     }
    }
   }
  },
  "/api/v1/entreprise/{siren}/comptes-annuels": {
   "get": {
    "operationId": "comptesAnnuels",
    "summary": "Comptes annuels",
    "description": "Bilans et ratios disponibles sur N années.",
    "tags": [
     "Entreprises"
    ],
    "parameters": [
     {
      "name": "siren",
      "in": "path",
      "required": true,
      "description": "Numéro SIREN à 9 chiffres",
      "schema": {
       "type": "string",
       "pattern": "^[0-9]{9}$"
      },
      "example": "552032534"
     },
     {
      "name": "annees",
      "in": "query",
      "required": false,
      "description": "Nombre d'années",
      "schema": {
       "type": "integer",
       "minimum": 1
      },
      "example": 3
     }
    ],
    "responses": {
     "200": {
      "description": "Réponse JSON",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Paramètre invalide"
     },
     "404": {
      "description": "Entreprise introuvable"
     },
     "429": {
      "description": "Limite atteinte (sans clé : 30 requêtes par jour et par IP). La réponse indique comment créer une clé gratuite."
     },
     "401": {
      "description": "Clé API requise"
     }
    },
    "security": [
     {
      "bearer": []
     },
     {
      "cle": []
     }
    ]
   }
  },
  "/api/v1/dirigeant": {
   "get": {
    "operationId": "dirigeant",
    "summary": "Rechercher un dirigeant",
    "description": "Recherche d'un dirigeant par nom.",
    "tags": [
     "Dirigeants"
    ],
    "parameters": [
     {
      "name": "nom",
      "in": "query",
      "required": true,
      "description": "Nom du dirigeant",
      "schema": {
       "type": "string"
      },
      "example": "dupont"
     }
    ],
    "responses": {
     "200": {
      "description": "Réponse JSON",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Paramètre invalide"
     },
     "404": {
      "description": "Entreprise introuvable"
     },
     "429": {
      "description": "Limite atteinte (sans clé : 30 requêtes par jour et par IP). La réponse indique comment créer une clé gratuite."
     }
    }
   }
  },
  "/api/v1/dirigeant/reseau": {
   "get": {
    "operationId": "dirigeantReseau",
    "summary": "Mandats d'un dirigeant",
    "description": "Jusqu'à 100 mandats et ratio de cessations ; homonymies possibles, aucune détection de fraude.",
    "tags": [
     "Dirigeants"
    ],
    "parameters": [
     {
      "name": "nom",
      "in": "query",
      "required": true,
      "description": "Nom du dirigeant",
      "schema": {
       "type": "string"
      },
      "example": "dupont"
     }
    ],
    "responses": {
     "200": {
      "description": "Réponse JSON",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Paramètre invalide"
     },
     "404": {
      "description": "Entreprise introuvable"
     },
     "429": {
      "description": "Limite atteinte (sans clé : 30 requêtes par jour et par IP). La réponse indique comment créer une clé gratuite."
     }
    }
   }
  },
  "/api/v1/comparer": {
   "get": {
    "operationId": "comparer",
    "summary": "Comparer deux entreprises",
    "description": "Comparaison structurée de deux SIREN.",
    "tags": [
     "Entreprises"
    ],
    "parameters": [
     {
      "name": "a",
      "in": "query",
      "required": true,
      "description": "SIREN A",
      "schema": {
       "type": "string"
      },
      "example": "552032534"
     },
     {
      "name": "b",
      "in": "query",
      "required": true,
      "description": "SIREN B",
      "schema": {
       "type": "string"
      },
      "example": "542065479"
     }
    ],
    "responses": {
     "200": {
      "description": "Réponse JSON",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Paramètre invalide"
     },
     "404": {
      "description": "Entreprise introuvable"
     },
     "429": {
      "description": "Limite atteinte (sans clé : 30 requêtes par jour et par IP). La réponse indique comment créer une clé gratuite."
     }
    }
   }
  },
  "/api/v1/entreprise/{siren}/enrichissement": {
   "get": {
    "operationId": "enrichissement",
    "tags": [
     "Entreprises"
    ],
    "summary": "Site web et activité réelle",
    "description": "Site web rattaché à l'entreprise (avec la méthode de rapprochement et sa date de vérification), activité décrite, activité déclarée. Paramètre detail=apercu|complet.",
    "parameters": [
     {
      "name": "siren",
      "in": "path",
      "required": true,
      "description": "Numéro SIREN à 9 chiffres",
      "schema": {
       "type": "string",
       "pattern": "^[0-9]{9}$"
      },
      "example": "552032534"
     },
     {
      "name": "detail",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "apercu",
        "complet"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Réponse JSON",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        },
        "example": {
         "siren": "552032534",
         "identity": {
          "site_url": "https://danone.fr/",
          "kind": "group",
          "label": "Lien avec le groupe",
          "method": "Domaine au nom de la maison mère au registre .fr",
          "checked_at": "2026-09-04 06:51:11",
          "age_days": 74,
          "freshness": "dated",
          "review_after_days": 90
         },
         "activity": {
          "text": "L’activité déclarée de DANONE est « Activités des sièges sociaux ».",
          "source": "naf",
          "sources": [
           {
            "url": "https://annuaire-entreprises.data.gouv.fr/entreprise/552032534",
            "label": "Activité déclarée (code NAF)"
           }
          ],
          "collectedAt": null
         },
         "declared_activity": {
          "code": "7010Z",
          "label": "Activités des sièges sociaux"
         },
         "access": {
          "detail": "locked",
          "website": "/sales-intel#tarifs",
          "api": "/api-pro"
         },
         "detail": null
        }
       }
      }
     },
     "400": {
      "description": "Paramètre invalide"
     },
     "429": {
      "description": "Limite atteinte (sans clé : 30 requêtes par jour et par IP). La réponse indique comment créer une clé gratuite."
     }
    }
   }
  },
  "/api/v1/recherche/activite": {
   "get": {
    "operationId": "rechercheActivite",
    "tags": [
     "Entreprises"
    ],
    "summary": "Recherche d'entreprises par activité (abonnement API Pro ou Business)",
    "description": "Recherche multicritère par activité ; réservée aux clés API Pro/Business (https://openbase.fr/api-pro).",
    "security": [
     {
      "bearer": []
     },
     {
      "cle": []
     }
    ],
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "example": "boulangerie"
     }
    ],
    "responses": {
     "200": {
      "description": "Réponse JSON"
     },
     "400": {
      "description": "Paramètre invalide"
     },
     "429": {
      "description": "Limite atteinte (sans clé : 30 requêtes par jour et par IP). La réponse indique comment créer une clé gratuite."
     },
     "401": {
      "description": "Clé API Pro ou Business requise"
     }
    }
   }
  },
  "/api/v1/watches/events": {
   "get": {
    "operationId": "evenementsSurveillance",
    "tags": [
     "Surveillance"
    ],
    "summary": "Événements des entreprises surveillées (clé + abonnement Surveillance Pro)",
    "description": "Flux des événements (BODACC, dirigeants, sanctions, finances) des entreprises suivies par le compte.",
    "security": [
     {
      "bearer": []
     },
     {
      "cle": []
     }
    ],
    "parameters": [
     {
      "name": "since",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "until",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "siren",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "category",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "severity_min",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Réponse JSON"
     },
     "401": {
      "description": "Clé API requise"
     },
     "400": {
      "description": "Paramètre invalide"
     },
     "429": {
      "description": "Limite atteinte (sans clé : 30 requêtes par jour et par IP). La réponse indique comment créer une clé gratuite."
     }
    }
   }
  }
 }
}