APIEmpresas.es - SDK para Python

SDK oficial para consultar la API de APIEmpresas.es desde Python 3.7 o superior.

Instalación

pip install apiempresas

Uso

from apiempresas import ApiEmpresas, ApiError

api = ApiEmpresas('TU_API_KEY')

# Datos de una empresa (devuelve directamente el objeto de la empresa)
empresa = api.companies.get('A15075062')
print(empresa['name'])

# Con administradores y cargos (Pro/Business)
empresa = api.companies.get('A15075062', admin=True)

# Varias empresas por nombre, con paginación (devuelve data y meta)
pagina = api.companies.search_multiple('software', limit=20)
siguiente = pagina['meta'].get('next_cursor')
if siguiente:
    pagina = api.companies.search_multiple('software', cursor=siguiente)

# Consulta múltiple (devuelve data y meta)
lote = api.companies.batch(['A15075062', 'A46103834'])

# Match (Business): el sector del vendedor es obligatorio
match = api.companies.match('A15075062', 'software')

# Radar de empresas nuevas (todos los planes: 10 resultados en Free con nombre y CIF ocultos, 100 en Pro, 1.000 en Business). range: 'hoy' (por defecto) o días atrás ('7', '30')
nuevas = api.companies.radar(province='Madrid', range='7')

Los métodos devuelven el contenido de data, salvo cuando la respuesta trae también meta (batch, search_multiple, radar), que devuelven la respuesta completa.

Verificación KYB (Pro) — 2 consultas

v = api.companies.verify('A46103834', name='Mercadona SA', person='Juan Roig Alfonso', vat=True,
                         iban='ES9121000418450200051332')  # (1.5.0) ¿IBAN bien formado? No dice de quién es la cuenta
print(v['decision_hint'])   # pass | review | fail
print(v['checks']['iban'])  # valid, country, sepa, bank_code, reason

Cada empresa trae además status_code (ACTIVE, INSOLVENCY, EXTINCT...), status_source, status_date y, en Pro/Business, financials. Los administradores traen since. Desde la 1.3.0 la respuesta lleva también identifiers (código LEI) y legal_form (forma jurídica con su código ISO 20275) en todos los planes, y en Pro/Business group (matriz directa y última según GLEIF) y ownership (socio único según el BORME). En verify, con person, checks.person.is_sole_shareholder dice si quien firma es el socio único. Desde la 1.5.0, en Pro/Business, size (tramo de empleados con su fuente; None si no consta) y address_density (cuántas sociedades activas comparten la dirección exacta); filter() admite size_category (micro, small, medium, large).

El Radar acepta también cnae, min_score, main_act_type y has_phone.

Nombre a CIF (Pro)

r = api.companies.reconcile(['Mercadona', {'name': 'Talleres Pérez', 'province': 'Madrid'}])
# r['data'][i]['status']: match (con company.cif) | ambiguous (candidates) | no_match. Solo se cobran los match.

Validar el NIF de tus clientes antes de facturar (Pro, Business o saldo; desde 1.6.0)

r = api.companies.verify_batch([
    {'cif': 'A46103834', 'name': 'Mercadona', 'ref': 'cliente-0001'},  # name: la razón social que tienes guardada
    {'cif': 'A15075062', 'name': 'Inditex', 'ref': 'cliente-0002'},    # ref: tu identificador, vuelve tal cual
    'B12345674',                                                        # o el NIF suelto
])
for fila in r['data']:
    print(fila['input'], fila['invoice_hint'])  # ok | revisar | no_facturar
# api.companies.verify_batch(['A46103834'], vat=True)  # también VIES

Por cada NIF, en el mismo orden: valid_format, exists, legal_name, address, status_code, name_check (si das name) e invoice_hint (ok, revisar o no_facturar) con sus motivos en flags. meta trae requested, found, cost, truncated y summary. Hasta 1.000 NIF por llamada; con vat (lotes de hasta 20) comprueba también el NIF-IVA en VIES. Cobra 1 consulta por sociedad encontrada: los NIF inválidos, de personas o que no constan no se cobran; si no te llega el saldo, las filas que no caben vuelven con processed: false. No sustituye la comprobación contra el censo de la AEAT.

Segmentos de empresas

total = api.companies.count(cnae=['62'], province='MADRID', has_phone=True)   # gratis
pagina = api.companies.filter(cnae=['62'], province='MADRID', limit=100)      # Business: 5 consultas por fila
# Siguiente página: cursor=pagina['meta']['next_cursor'] con los mismos filtros

Vigilancia de empresas (Pro: 100, Business: 1.000) — sin coste

api.watchlist.add(['A46103834', 'A28015865'])
lista = api.watchlist.list()                     # {'success', 'data', 'meta'}
cambios = api.watchlist.events(since='2026-09-01', types=['borme_act', 'status_change'])
api.watchlist.remove('A28015865')

Webhooks (Business)

hook = api.webhooks.create('https://tu-servidor.com/apiempresas', 'watchlist.*')
# (1.5.0) Sociedades nuevas del BORME del día, con filtros opcionales
nuevas = api.webhooks.create('https://tu-servidor.com/nuevas', 'company.created',
                             filters={'province': ['MADRID'], 'keywords': ['software'], 'min_capital': 3000})
# Guarda hook['secret']: con él se comprueba la firma.
api.webhooks.test(hook['id'])

# Historial de entregas (lo más reciente primero): estado, intentos, código HTTP y error
r = api.webhooks.deliveries(hook['id'], status='dead', limit=20)
print(r['meta']['total'], r['data'][:1])

En tu servidor, comprueba la firma con el cuerpo en bruto (Flask):

from apiempresas import construct_webhook_event, ApiError

@app.post('/apiempresas')
def apiempresas_webhook():
    try:
        evento = construct_webhook_event(request.get_data(), request.headers.get('X-ApiEmpresas-Signature'), SECRET)
    except ApiError:
        return '', 400
    # evento['event']: company.borme_act | company.status_changed | company.risk_level_changed | test.ping
    return '', 200

Si tu servidor no responde 2xx, se reintenta a los 1 min, 5 min, 30 min, 2 h y 6 h.

Licitaciones públicas abiertas (Business) — 1 consulta

r = api.tenders.list(q="limpieza", province="Madrid", type="services")
for t in r["data"]["tenders"]:
    print(t["title"], t["deadline"], t["url"])

# Las parecidas a los contratos que una empresa ya ha ganado (ordenadas por match_score)
r = api.tenders.for_company("A82018474")

Listas de sanciones (Business) — 1 consulta

# Una empresa y sus administradores vigentes, en las listas de la UE, la ONU y OFAC
r = api.sanctions.screen(cif="A46103834")
print(r["summary"]["result"])  # clear | possible_match | match

# Un nombre suelto
r = api.sanctions.screen(name="Vladimir Putin", type="person")
# Cada coincidencia trae level (strong | possible), list, programs, countries y birth_dates

Con Business, companies.verify() incluye checks.sanctions.

Subvenciones y ayudas públicas (Business, desde 1.5.0) — 1 consulta

s = api.companies.subsidies('B12345678', year=2025, limit=50)  # BDNS desde 2022, Kit Digital incluido
print(s['summary']['total_grants'], s['summary']['total_amount'], s['summary']['by_year'])
for g in s['grants']:
    print(g['grant_date'], g['amount'], g['call'])

Feed de cambios (Business, desde 1.5.0) — 1 consulta por página

pagina = api.companies.changes(since='2026-10-19', types=['address', 'officers'], province='MADRID')
# Siguiente página: cursor=pagina['meta']['next_cursor'] con los mismos filtros

# O todas las páginas, cambio a cambio (usa c['id'] para no procesar dos veces el mismo)
for c in api.companies.iter_changes(since='2026-10-19'):
    print(c['cif'], c['change_types'], c['status_code'])

Solo salen sociedades con CIF: las recién constituidas llegan por el webhook company.created.

Estadísticas del BORME (todos los planes, desde 1.5.0) — 1 consulta

st = api.stats(metrics=['incorporations', 'dissolutions'], province='MADRID', from_='2025-01', to='2025-12')
print(st['data']['totals'])
for fila in st['data']['series']:
    print(fila['period'], fila['incorporations'])
# Por años: api.stats(group='year', from_='2015', to='2025')

Sandbox

Para probar sin gastar consultas, con tu misma API Key y datos simulados:

api = ApiEmpresas('TU_API_KEY', base_url='https://apiempresas.es/api/sandbox/v1')

Tiene también subsidies() y changes(); stats() y usage() no.

Consumo

u = api.usage()  # no gasta consultas; no está en el Sandbox
print(u['stats']['remaining_calls'])

Valores de los filtros

cat = api.catalog()  # no gasta consultas; también en el Sandbox
print(cat['province'], cat['size_band'], cat['radar']['priority'], cat['webhook_events'], cat.get('change_types'))

Errores

try:
    api.companies.get('A15075062')
except ApiError as e:
    print(e.status)      # código HTTP
    print(str(e))        # mensaje legible
    print(e.code)        # p. ej. QUOTA_EXCEEDED, TOO_MANY_REQUESTS, API_KEY_INVALID
    print(e.error_code)  # campo "error" de la respuesta (como en versiones anteriores)
    print(e.request_id)  # dáselo a soporte
    print(e.retry_after) # segundos, en los 429 por velocidad
    print(e.required_plan, e.checkout_url)  # en los 403 de plan

Un 429 con code == 'TOO_MANY_REQUESTS' se resuelve esperando y reintentando; con QUOTA_EXCEEDED no: hay que recargar saldo o cambiar de plan.

Licencia

MIT