Documentación del API

1. Introducción

El API de APIEmpresas.es está pensado para usarse desde tu backend (PHP, Node, Python, etc.) y devolver información mercantil en tiempo real.

Todas las peticiones se realizan sobre HTTPS y devuelven respuestas en formato application/json.

Base URL recomendada:

https://api.apiempresas.es/v1

2. Autenticación

La autenticación se realiza mediante una cabecera Authorization: Bearer <API_KEY>. Puedes ver y rotar tu clave desde el panel.

GET /v1/company?cif=B12345678 HTTP/1.1
Host: api.apiempresas.es
Authorization: Bearer sk_live_xxxxxxxx
Accept: application/json

3. Endpoint GET /company

3.1 Descripción

Devuelve la ficha básica de una empresa a partir de su CIF/NIF. Ideal para onboarding de clientes, scoring de riesgo o comprobaciones de compliance.

GET /company?cif={CIF}

3.2 Parámetros

• cif (obligatorio): CIF/NIF de la empresa, sin espacios.
• live (opcional, bool): si se fuerza actualización en tiempo real.

3.3 Ejemplo de respuesta

{
  "cif": "B12345678",
  "name": "EMPRESA DEMO SL",
  "status": "activa",
  "province": "Madrid",
  "municipality": "Madrid",
  "registry": {
    "tomo": "12345",
    "libro": "0",
    "folio": "12",
    "hoja": "M-123456"
  },
  "sources": ["BORME", "AEAT", "VIES"]
}

3.4 Códigos de error

• 400: parámetro cif ausente o inválido.
• 401: API key incorrecta o ausente.
• 404: no se ha encontrado ninguna empresa para ese CIF.
• 429: límite de peticiones excedido.

4. SDK PHP / Laravel

Ejemplo mínimo para validar un CIF desde PHP o Laravel.

4.1 Instalación

composer require apiempresas/sdk-php

4.2 Ejemplo rápido (Laravel)

<?php

use APIEmpresas\Client;

$client = new Client(env('APIEMPRESAS_API_KEY'));

$response = $client->company([
    'cif' => 'B12345678',
]);

if ($response->ok()) {
    $data = $response->json();
    // $data['status'], $data['name'], etc.
}

Puedes ver más ejemplos (middlewares, validación de formularios, jobs en cola) en /docs/sdk-php.

5. SDK Node / JavaScript

Uso típico en un backend Node (Express, Nest, serverless, etc.).

5.1 Instalación

npm install @apiempresas/sdk

5.2 Ejemplo rápido (Node)

import { APIEmpresas } from "@apiempresas/sdk";

const client = new ApiEmpresas(process.env.VE_API_KEY);

const company = await client.company({ cif: "B12345678" });

if (company.status === "activa") {
  console.log("Empresa activa:", company.name);
}