API v1 · OpenAPI 3.1 · estable

Referencia de la API

Consulta datos de empresas francesas (SIRENE/INSEE + RNE/INPI) desde tu aplicación: búsqueda, unidades legales, establecimientos, directivos y cuentas anuales. Una sola URL base, autenticación con un par de claves.

Visión general

Una API REST sin estado, JSON de entrada/salida, versionada. Todas las rutas llevan el prefijo /v1 y devuelven el sobre { success, data, timestamp }.

URL basehttps://companyfrance.fr/api/v1
Versiónv1 · OpenAPI 3.1
Formatoapplication/json
AutenticaciónX-API-Key + X-API-Secret

Datos procedentes de SIRENE/INSEE (open data) enriquecidos con RNE/INPI. El contrato completo está disponible en OpenAPI 3.1.

Autenticación

Cada solicitud debe incluir tu par de claves API en las cabeceras HTTP. La clave pública identifica tu cuenta; la clave secreta la autentica. Nunca expongas tu clave secreta en el navegador.

curl "https://companyfrance.fr/api/v1/me" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Cabeceras requeridas

X-API-Key — clave pública, formato pk_live_…
X-API-Secret — clave secreta, formato sk_live_… (mantener en el servidor)

Crea y revoca tus claves desde /dashboard/api/keys.

Formato de errores

Todos los errores devuelven un estado HTTP 4xx o 5xx y un cuerpo JSON con success: false, un campo error (legible) y un campo code (identificador de máquina).

application/json

{
  "success": false,
  "error": "No legal unit found for this SIREN.",
  "code": "NOT_FOUND",
  "timestamp": "2026-06-22T10:00:00.000Z"
}

MISSING_CREDENTIALSFaltan las claves API en las cabeceras.
INVALID_API_KEYClave pública o secreta no válida.
API_KEY_DISABLEDClave desactivada o caducada.
MISSING_FILTERNo se proporcionó ningún filtro de búsqueda (q, naf, codePostal…).
INVALID_SIRENSIREN no válido: se esperan 9 dígitos.
NOT_FOUNDRecurso no encontrado.
INTERNAL_ERRORError interno del servidor.

Paginación

Los endpoints de listado aceptan page (por defecto 1) y perPage (por defecto 20, máx. 100). La respuesta incluye un objeto pagination que describe la página actual y si existe una página siguiente.

application/json

"pagination": {
  "page": 1,
  "perPage": 20,
  "total": 137,
  "totalPages": 7,
  "hasNext": true
}

Cuotas y límites

Las llamadas se descuentan de la cuota mensual de tu plan y están limitadas por hora. Cada respuesta expone tu consumo mediante las cabeceras X-RateLimit-*.

Cuota mensual del planX-RateLimit-Limit
Llamadas restantes en el períodoX-RateLimit-Remaining
Marca de tiempo (epoch) de reinicioX-RateLimit-Reset

Superación

Por encima de la cuota o del límite por hora, la API devuelve 429. Una suscripción inactiva devuelve 402. Vigila tu cabecera X-RateLimit-Remaining para anticiparte.

Buscar unidades legales

GET/v1/search

Búsqueda en base de datos sobre empresas francesas. Proporciona al menos un filtro. Los resultados están paginados y ordenados por nombre.

Parámetros de consulta

qstringopcional
Texto libre: nombre, nombre del directivo o prefijo de SIREN. Un q de 9 dígitos realiza una búsqueda exacta por SIREN.
nafstringopcional
Código NAF/APE exacto (p. ej. 29.10Z) o prefijo de división (p. ej. 62).
categorieJuridiquestringopcional
Código INSEE de categoría jurídica (p. ej. 5710).
etatstringopcional
AC
Estado administrativo: A (activa) o C (cesada).
codePostalstringopcional
Código postal exacto (coincide con un establecimiento).
communestringopcional
Nombre del municipio (coincidencia parcial).
departementstringopcional
Departamento de 2 dígitos (prefijo del código postal).
pageintegeropcionalpor defecto 1
Número de página (a partir de 1).
perPageintegeropcionalpor defecto 20
Resultados por página (máx. 100).

Respuestas

200Resultados paginados (items + pagination).
400No se proporcionó ningún filtro.
401Claves API ausentes o no válidas.
429Cuota o límite de tasa superado.

cURL

curl "https://companyfrance.fr/api/v1/search?q=renault&departement=92&perPage=20" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "siren": "552032534",
        "sirenFormatted": "552 032 534",
        "name": "RENAULT",
        "sigle": null,
        "legalForm": { "code": "5710", "label": "SA à conseil d'administration" },
        "activity": { "code": "29.10Z", "label": "Construction de véhicules automobiles" },
        "category": "GE",
        "active": true,
        "state": "A",
        "dateCreation": "1955-01-01T00:00:00.000Z"
      }
    ],
    "pagination": { "page": 1, "perPage": 20, "total": 3, "totalPages": 1, "hasNext": false }
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

Buscar empresas por directivo

GET/v1/search/dirigeants

Búsqueda inversa: todas las empresas que una persona dirige o ha dirigido (directivos del RNE + empresarios individuales). Sin distinción de mayúsculas ni acentos. Proporciona al menos nom o prenom (mín. 2 caracteres).

Parámetros de consulta

nomstringopcional
Apellido (o cualquier término del nombre).
prenomstringopcional
Nombre(s).
strictbooleanopcionalpor defecto false
true → coincidencia bloqueada por campo (nom↔nom, prénom↔prénom): menos homónimos.
pageintegeropcionalpor defecto 1
Número de página (a partir de 1).
perPageintegeropcionalpor defecto 20
Resultados por página (máx. 100).

Respuestas

200Empresas vinculadas a la persona (items + pagination, totalMatched, capped).
400No se proporcionó ningún nombre de directivo.
401Claves API ausentes o no válidas.
429Cuota o límite de tasa superado.

cURL

curl "https://companyfrance.fr/api/v1/search/dirigeants?nom=Dupont&prenom=Jean" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "siren": "552032534",
        "sirenFormatted": "552 032 534",
        "name": "RENAULT",
        "activity": { "code": "29.10Z", "label": "Construction de véhicules automobiles" },
        "active": true,
        "state": "A",
        "dateCreation": "1955-01-01T00:00:00.000Z",
        "dateRadiation": null,
        "roles": ["Président du conseil d'administration"],
        "matched": "Jean Dupont"
      }
    ],
    "pagination": { "page": 1, "perPage": 20, "total": 3, "totalPages": 1, "hasNext": false },
    "totalMatched": 3,
    "capped": false
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

Buscar empresas por dirección

GET/v1/search/adresse

Búsqueda inversa: todas las empresas domiciliadas en una dirección, agrupadas por SIREN (sede primero). El código postal es obligatorio; afina con la vía y el municipio.

Parámetros de consulta

codePostalstringobligatorio
Código postal — obligatorio. 5 dígitos (o un prefijo de mín. 4 dígitos). Es el ancla indexada.
voiestringopcional
Términos de vía (número / tipo / nombre), en cualquier orden.
communestringopcional
Nombre del municipio (refinamiento opcional).
pageintegeropcionalpor defecto 1
Número de página (a partir de 1).
perPageintegeropcionalpor defecto 20
Resultados por página (máx. 100).

Respuestas

200Empresas en la dirección (items + pagination, totalMatched, capped).
400Falta el código postal.
401Claves API ausentes o no válidas.
429Cuota o límite de tasa superado.

cURL

curl "https://companyfrance.fr/api/v1/search/adresse?codePostal=92100&voie=Quai+Le+Gallo" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "siren": "552032534",
        "sirenFormatted": "552 032 534",
        "name": "RENAULT",
        "activity": { "code": "29.10Z", "label": "Construction de véhicules automobiles" },
        "active": true,
        "state": "A",
        "dateCreation": "1955-01-01T00:00:00.000Z",
        "address": "13 Quai Alphonse Le Gallo, 92100 Boulogne-Billancourt",
        "street": "13 Quai Alphonse Le Gallo",
        "postalCode": "92100",
        "commune": "Boulogne-Billancourt",
        "headOffice": true,
        "establishmentsMatched": 1
      }
    ],
    "pagination": { "page": 1, "perPage": 20, "total": 12, "totalPages": 1, "hasNext": false },
    "totalMatched": 12,
    "capped": false
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

Obtener una unidad legal

GET/v1/unite-legale/{siren}

Ficha completa de la empresa: denominaciones, forma jurídica, actividad, capital (Pro/Enterprise), plantilla, número de IVA y recuento de establecimientos.

Parámetros de ruta

sirenstringobligatorio
SIREN de la unidad legal — 9 dígitos.

Respuestas

200Ficha de la unidad legal.
404Recurso no encontrado.

cURL

curl "https://companyfrance.fr/api/v1/unite-legale/552032534" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "siren": "552032534",
    "sirenFormatted": "552 032 534",
    "name": "RENAULT",
    "legalForm": { "code": "5710", "label": "SA à conseil d'administration" },
    "activity": { "code": "29.10Z", "label": "Construction de véhicules automobiles" },
    "active": true,
    "state": "A",
    "vatNumber": "FR41552032534",
    "workforceRange": "53",
    "capital": { "amount": 1126701902, "currency": "EUR", "variable": false },
    "establishments": { "total": 12, "active": 9 }
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

Listar los establecimientos de una unidad legal

GET/v1/unite-legale/{siren}/etablissements

Establecimientos (SIRET) vinculados a un SIREN, paginados. Filtra por estado para conservar solo los establecimientos activos.

Parámetros de ruta

sirenstringobligatorio
SIREN de la unidad legal — 9 dígitos.

Parámetros de consulta

etatstringopcional
AF
Estado del establecimiento: A (activo) o F (cerrado).
pageintegeropcionalpor defecto 1
Número de página (a partir de 1).
perPageintegeropcionalpor defecto 20
Resultados por página (máx. 100).

Respuestas

200Establecimientos paginados.
404Recurso no encontrado.

cURL

curl "https://companyfrance.fr/api/v1/unite-legale/552032534/etablissements?etat=A" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

Listar los directivos de una unidad legal

GET/v1/unite-legale/{siren}/dirigeants

Directivos (gerente, presidente…) procedentes del RNE. Para un empresario individual, la persona física se sintetiza a partir de la identidad de la unidad legal.

Parámetros de ruta

sirenstringobligatorio
SIREN de la unidad legal — 9 dígitos.

Respuestas

200Lista de directivos (count + items).
404Recurso no encontrado.

cURL

curl "https://companyfrance.fr/api/v1/unite-legale/552032534/dirigeants" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "siren": "552032534",
    "count": 1,
    "items": [
      {
        "type": "person",
        "name": "Jean Dupont",
        "nom": "Dupont",
        "prenoms": "Jean",
        "denomination": null,
        "role": "Président du conseil d'administration",
        "birthYear": 1968
      }
    ]
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

Cuentas anuales de una unidad legal

GET/v1/unite-legale/{siren}/finances

Cuentas anuales depositadas (cifra de negocios, resultado neto…) cuando están disponibles.

Parámetros de ruta

sirenstringobligatorio
SIREN de la unidad legal — 9 dígitos.

Respuestas

200Cuentas anuales.
403Plan insuficiente — se requiere mejora.
404Recurso no encontrado.

Endpoint reservado a los planes Pro y Enterprise

El acceso a las cuentas anuales requiere una suscripción Pro o Enterprise. Con un plan inferior, la API devuelve 403.

cURL

curl "https://companyfrance.fr/api/v1/unite-legale/552032534/finances" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "siren": "552032534",
    "count": 1,
    "items": [
      {
        "year": 2024,
        "dateCloture": "2024-12-31",
        "typeBilan": "C",
        "totalBilan": 98765432000,
        "capitauxPropres": 31200000000,
        "resultatNet": 752000000,
        "chiffreAffaires": 56601000000,
        "currency": "EUR",
        "confidential": false,
        "dateDepot": "2025-05-14"
      }
    ]
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}

Obtener un establecimiento

GET/v1/etablissement/{siret}

Ficha de un establecimiento por su SIRET: dirección, actividad, rótulo, indicador de sede y estado administrativo.

Parámetros de ruta

siretstringobligatorio
SIRET del establecimiento — 14 dígitos.

Respuestas

200Ficha del establecimiento.
404Recurso no encontrado.

cURL

curl "https://companyfrance.fr/api/v1/etablissement/55203253400041" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

Nomenclatura NAF

GET/v1/naf

Lista de códigos NAF/APE con sus etiquetas. Filtra con q para buscar por etiqueta o código.

Parámetros de consulta

qstringopcional
Búsqueda por etiqueta o código NAF.

Respuestas

200Códigos NAF.

cURL

curl "https://companyfrance.fr/api/v1/naf?q=automobile" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

Resolver un código NAF

GET/v1/naf/{code}

Devuelve la etiqueta de un código NAF/APE concreto.

Parámetros de ruta

codestringobligatorio
Código NAF/APE a resolver (p. ej. 29.10Z).

Respuestas

200Etiqueta del código.
404Recurso no encontrado.

cURL

curl "https://companyfrance.fr/api/v1/naf/29.10Z" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

Nomenclatura de categorías jurídicas

GET/v1/categories-juridiques

Lista de códigos de forma jurídica (INSEE) con sus etiquetas. Filtra con q.

Parámetros de consulta

qstringopcional
Búsqueda por etiqueta o código.

Respuestas

200Categorías jurídicas.

cURL

curl "https://companyfrance.fr/api/v1/categories-juridiques?q=SARL" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

Tu plan y consumo

GET/v1/me

Devuelve la cuenta que realiza la llamada, su plan y su consumo actual. Esta llamada también se descuenta de la cuota.

Respuestas

200Plan + consumo.
400Clave API no vinculada a una empresa.

cURL

curl "https://companyfrance.fr/api/v1/me" \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

200 OK

{
  "success": true,
  "data": {
    "keyId": "key_01J…",
    "company": { "id": "cmp_01J…" },
    "plan": {
      "code": "pro",
      "name": "Pro",
      "status": "active",
      "trialEndsAt": null,
      "currentPeriodEnd": "2027-06-22T00:00:00.000Z"
    },
    "usage": {
      "used": 1284,
      "limit": 50000,
      "remaining": 48716,
      "percentage": 3,
      "resetAt": "2026-07-01T00:00:00.000Z",
      "hourlyRateLimit": 1000
    }
  },
  "timestamp": "2026-06-22T10:00:00.000Z"
}