Tutorial · Python

Verificar el NIF de una empresa por API

Valida el formato en local y resuelve la sociedad en el BORME con una llamada REST: administradores, capital, domicilio y estado en unas 30 líneas de Python.

Publicado el 9 de septiembre de 2026 · English version

El problema

Estás dando de alta clientes o proveedores españoles y necesitas confirmar, antes de operar, que el NIF (a) está bien formado, (b) corresponde a una sociedad inscrita y (c) devuelve datos suficientes para el expediente: denominación, forma jurídica, domicilio, capital, estado y quién la administra. Lo primero se resuelve sin red. Lo segundo y lo tercero, con dos llamadas.

El script completo

# verificar_nif.py — validación local del NIF + consulta a la API de Prometiam
import os, re, requests
API = 'https://api.prometiam.com/functions/v1/risk-api'
HEAD = {'Authorization': f'Bearer {os.environ["PROMETIAM_API_KEY"]}'}
NIF_RE = re.compile(r'^[A-HJNPQRSUVW][0-9]{7}[0-9A-J]
#x27;)
LETRAS_CONTROL = 'JABCDEFGHI'  # resto mod 10 -> letra
def nif_valido(nif: str) -> bool:
    nif = nif.upper().strip()
    if not NIF_RE.match(nif): return False
    digitos, ultimo = nif[1:8], nif[8]
    suma = (sum(int(d) for d in digitos[1::2]) +
            sum(sum(divmod(int(d) * 2, 10)) for d in digitos[0::2])) % 10
    control = (10 - suma) % 10
    if nif[0] in 'ABEH': return ultimo == str(control)            # control numérico
    if nif[0] in 'KPQS': return ultimo == LETRAS_CONTROL[control]  # control alfabético
    return ultimo == str(control) or ultimo == LETRAS_CONTROL[control]
def verificar(nif: str) -> dict:
    if not nif_valido(nif):
        return {'estado': 'formato_invalido', 'nif': nif}
    r = requests.get(f'{API}/companies/search', params={'nif': nif, 'country': 'ES'}, headers=HEAD).json()
    if not r.get('data'):
        return {'estado': 'no_encontrado', 'nif': nif}
    empresa = r['data'][0]
    ficha = requests.get(f'{API}/companies/{empresa["id"]}', headers=HEAD).json()['data']
    return {'estado': 'verificado', 'nif': nif, 'empresa': ficha}
if __name__ == '__main__':
    import sys, json
    print(json.dumps(verificar(sys.argv[1]), indent=2, ensure_ascii=False))

Ejecuta python verificar_nif.py A28015865 tras exportar PROMETIAM_API_KEY=rk_live_….

Qué devuelve

{
  "estado": "verificado",
  "nif": "A28015865",
  "empresa": {
    "id": 812044,
    "company_number": "A28015865",
    "company_name": "TELEFONICA, S.A.",
    "legal_form": "SA",
    "region": "MADRID",
    "address": "C/ GRAN VIA 28",
    "postal_code": "28013",
    "activity_code": "6110",
    "activity_code_scheme": "CNAE",
    "capital_eur": 4551929995.36,
    "status": "active",
    "founding_date": "1924-04-19",
    "contacts": [ /* cargos vigentes */ ]
  }
}

www.prometiam.com/dashboard/companies

Paso 1: validación en local

La primera letra del NIF codifica la forma jurídica:

• A Sociedad Anónima · B Sociedad Limitada · C Sociedad Colectiva · D Sociedad Comanditaria
• E Comunidad de bienes · F Cooperativa · G Asociación o fundación · H Comunidad de propietarios
• J Sociedad civil · P Corporación local · Q Organismo público · R Entidad religiosa
• S Órgano de la Administración · U UTE · V Otros · W Establecimiento de entidad extranjera

En un flujo de alta de empresas lo normal es aceptar A, B, F, J, U y W y rechazar el resto. El noveno carácter es el de control: numérico para A B E H, letra de JABCDEFGHI para K P Q S, y cualquiera de los dos para el resto. El validador de arriba aplica esa regla. Si prefieres comprobarlo en el navegador, el validador de identificadores hace lo mismo sin instalar nada.

Paso 2: consulta REST

Con el formato correcto, GET /companies/search?nif=&country=ES devuelve una única fila del BORME con el id interno. Después, GET /companies/{id} devuelve la ficha:

• Denominación, forma jurídica, domicilio y capital
• Fecha de constitución y estado (activa, disuelta, en liquidación)
• Coordenadas registrales: tomo, libro, folio, hoja
• Cargos vigentes con su fecha de nombramiento

Para un expediente KYB completo, pasa también la denominación y cada administrador por /sanctions/screen. El flujo entero está en el caso de uso de alta de clientes, y los endpoints del BORME, en la guía de la API del BORME.

Errores habituales

• Minúsculas. La letra va en mayúscula; el validador normaliza la entrada.
• Confundir NIE con NIF. X, Y y Z son personas físicas extranjeras. Recházalos en el paso de formato si el flujo es de sociedades.
• Otros identificadores. Si el mismo formulario acepta SIREN, SIRET o número de Companies House, envía la consulta con country=FR o country=GB.
• Límites. La prueba gratuita de 14 días incluye 500 créditos. En un flujo de alta con volumen, cachea la respuesta de /companies/{id} 24 horas.

Regístrate