Regístrate

Caso de uso · KYB

API de verificación KYB

Verifica empresas de la UE y Reino Unido en producción con 30 líneas de código. NIF, SIREN, company_number → ficha registral completa + cribado de sanciones en una sola llamada REST.

Publicado el 15 de septiembre de 2026 · English version

El problema

Dar de alta a una contraparte B2B en un entorno financiero regulado en la UE exige probar cuatro cosas antes de operar: que la empresa existe legalmente, que sabes quién la controla, que ninguna de esas partes está sancionada y que no hay una señal adversa evidente. Lo habitual es un conjunto fragmentado de herramientas: un proveedor para datos españoles, otro para franceses, un tercero para el Companies House británico, un cuarto para sanciones, a veces un quinto para reputación adversa. Cada contrato es anual, de precio opaco y exige una llamada comercial.

Para una fintech que da de alta a unos pocos cientos de clientes B2B al mes, ese conjunto de proveedores es excesivo, caro y lento de integrar. La API de Prometiam sustituye las partes de registro y sanciones por un único endpoint REST y precios por consumo predecibles.

La integración en tres pasos

Tres endpoints cubren el flujo de registro y sanciones del KYB. Se ejecutan en este orden:

# 1. Resolver la contraparte por NIF (España), SIREN (Francia) o company_number (Reino Unido)
curl 'https://api.prometiam.com/functions/v1/risk-api/companies/search?company_number=A78053147&country=ES' \
  -H 'Authorization: Bearer rk_live_...'

# 2. Obtener la ficha completa (administradores, capital, coordenadas registrales)
curl 'https://api.prometiam.com/functions/v1/risk-api/companies/812044' \
  -H 'Authorization: Bearer rk_live_...'

# 3. Cribar la razón social y cada administrador contra sanciones
curl 'https://api.prometiam.com/functions/v1/risk-api/sanctions/screen?name=Telefonica&threshold=85' \
  -H 'Authorization: Bearer rk_live_...'

Eso es toda la superficie de registro del KYB para una única contraparte. Envuélvelo en una función, llámala desde tu formulario de alta y tendrás una integración funcionando en menos de una hora.

Un ejemplo real en Python

import os, requests

API = 'https://api.prometiam.com/functions/v1/risk-api'
HEAD = {'Authorization': f'Bearer {os.environ["PROMETIAM_API_KEY"]}'}

def verificar_kyb(nif: str, country: str = 'ES'):
    # Resolver la empresa
    s = requests.get(f'{API}/companies/search', params={'company_number': nif, 'country': country}, headers=HEAD).json()
    if not s.get('data'): return {'estado': 'no_encontrado'}
    empresa = s['data'][0]

    # Ficha completa (administradores + coordenadas registrales)
    ficha = requests.get(f'{API}/companies/{empresa["id"]}', headers=HEAD).json()['data']

    # Sanciones sobre la persona jurídica
    hits_empresa = requests.get(f'{API}/sanctions/screen',
                                params={'name': ficha['company_name'], 'threshold': 85},
                                headers=HEAD).json()['data']

    # Sanciones sobre cada administrador vigente
    hits_administradores = []
    for c in ficha.get('contacts', []):
        if not c.get('is_current'): continue
        h = requests.get(f'{API}/sanctions/screen',
                         params={'name': c['full_name'], 'threshold': 85, 'entity_type': 'person'},
                         headers=HEAD).json()['data']
        if h: hits_administradores.append({'administrador': c['full_name'], 'coincidencias': h})

    return {
        'estado': 'verificado' if (not hits_empresa and not hits_administradores) else 'revisar',
        'empresa': ficha,
        'sanciones': {'entidad': hits_empresa, 'administradores': hits_administradores},
    }

30 líneas incluyendo los imports. Una aplicación de KYB típica construida sobre esto devuelve un veredicto de verificado o a revisar en bien menos de un segundo con resultados en caché.

Qué te devuelve exactamente

La respuesta de /companies/{id} incluye todo lo que necesita un oficial de KYB para completar un expediente de alta:

  • Identidad: denominación social, NIF/SIREN/company_number, forma jurídica, domicilio, fecha de constitución
  • Coordenadas registrales: tomo / libro / folio / hoja exactos en España, oficina de registro en Francia, matrícula de Companies House en Reino Unido
  • Administradores: nombramientos vigentes e históricos — nombre, cargo, fecha de nombramiento, fecha de cese
  • Estado: activa, disuelta, en liquidación, etc., actualizado a diario
  • Capital y objeto social: capital registrado (capital_amount + capital_currency) y la descripción oficial de la actividad (activity_description, con activity_code y su clasificación en activity_code_scheme)

La respuesta de /sanctions/screen devuelve coincidencias con puntuación de confianza (0–100), lista de origen (UE / ONU / OFAC / Reino Unido / Australia (DFAT) / congelaciones francesas / US CSL) y los alias que existan. El umbral se fija por llamada para controlar la tasa de falsos positivos.

Captura del panel de clientes: la ficha de una empresa con identificadores y señalesCaptura del panel de clientes: la ficha de una empresa con identificadores y señales
La misma ficha en el panel: identificadores, domicilio social y las señales de insolvencia, sanciones (beta) y registro en una página. Se muestra una empresa del Reino Unido. Ábrelo en el panel

Encaje de precio

Para una fintech que da de alta a 500 contrapartes B2B al mes, el patrón típico de llamadas de KYB es de unas 5 por contraparte (resolución + ficha + 3 cribados de sanciones para la entidad y los principales administradores). Son 2.500 llamadas al mes, unos 5.500 créditos (11 por contraparte: 1 la resolución, 1 la ficha, 3 cada cribado) — cómodamente dentro del plan Professional (29,99 €/mes, 10.000 créditos al mes), que además incluye los cribados de sanciones que usa este flujo. Con 4.000 contrapartes al mes (unos 44.000 créditos), el plan Scale (99,99 €/mes, 50.000 créditos al mes) encaja sin apuros.

Creditsafe e Iberinform no publican precio para un volumen equivalente: requiere contacto comercial y un contrato anual.

Patrones de implementación

Cachea las consultas frecuentes. La mayoría de las fintechs B2B dan de alta repetidamente a las mismas empresas matriz. Guarda en caché la respuesta de /companies/{id} durante 24 horas; refréscala bajo demanda o con una actualización diaria en segundo plano.

Modo de vigilancia. Combina el KYB con el patrón de vigilancia de contrapartes: guarda el company_id de cada contraparte dada de alta y consulta /company-events/timeline a diario para detectar eventos posteriores al alta (cambios de administrador, reducciones de capital, disolución) que deban activar una revisión. Si la contraparte es española, el expediente de concurso de acreedores se consulta con GET /insolvency/search (España es uno de sus dieciséis mercados) y también con GET /search.

Ajuste del umbral de sanciones. Empieza en 85 (el valor por defecto) y ajústalo según el coste de un falso positivo. Para altas de mayor riesgo (préstamos, procesamiento de pagos), 80 es la opción más prudente. Para altas de bajo riesgo (alta en una newsletter, verificación de plan gratuito), 90 reduce el ruido.

Límites de alcance, sin rodeos

  • Cribado de sanciones: en beta.
  • Cribado PEP: en beta y solo España, sin familiares ni allegados (RCA).
  • Titularidad real: solo Reino Unido, vía PSC; el resto de registros devuelven administradores, no titularidad real.
  • Irlanda: a nivel empresa, todavía sin administradores.
  • Noruega: sin flujo de actos societarios (corporate events).
  • Vigilancia (POST /monitor): todos los países en producción excepto Francia y Chile, con México limitado a las entidades con LEI y Argentina sin alerta de disolución.
  • Insolvencia: los expedientes son solo de empresas, en dieciséis mercados (FR, DE, GB, AT, CH, NO, FI, US, NL, DK, HR, SE, ES, LV, EE, SG); los concursos de acreedores de España, que publica el BORME, están en GET /insolvency/search y también en GET /search.

Preguntas frecuentes

¿Qué es KYB?
Know Your Business: verificar una contraparte empresarial antes de operar con ella. Confirma la existencia legal, la titularidad real, la exposición a sanciones y la reputación adversa.

¿Qué países cubre el KYB de Prometiam?
España (BORME), Francia (BODACC), Reino Unido (Companies House), Irlanda (CRO, a nivel empresa), Polonia (KRS, a nivel empresa), Noruega (Brønnøysundregistrene, empresas y administradores), Finlandia (PRH/YTJ), Suecia (Bolagsverket), Bélgica (KBO), Croacia (Sudski registar), Dinamarca (CVR), Estonia (Äriregister), Eslovaquia (RPO), Suiza (Zefix), Letonia (Uzņēmumu reģistrs), Chipre (DRCOR) y Rumanía (ONRC) y Estados Unidos; Finlandia, Suecia, Bélgica, Croacia, Dinamarca, Estonia, Eslovaquia, Suiza, Letonia, Chipre, Rumanía, Lituania, Canadá, Australia, Japón, Israel, Singapur, Colombia, Taiwán, Alemania, Brasil y Estados Unidos solo con datos de empresa. Se usa ?country=ES|FR|GB|IE|PL|NO|FI|SE|BE|HR|DK|EE|SK|CH|LV|CY|RO|US|LT|CA|AU|JP|IL|SG|CO|TW|BR|CZ|DE|AR|UA|RS|EC|NL|CL|NL|MX.

¿Qué tan rápido se integra?
La primera llamada suele hacerse en menos de 60 segundos desde el alta. Una integración de producción de principio a fin suele ser el trabajo de medio día.

¿Incluye titularidad real (UBO)?
Para Reino Unido, sí, vía PSC (Persons with Significant Control), en /companies/{id} y /people/{id}. Para España y Francia exponemos lo que consta en el registro mercantil que consultamos; la cadena completa de titularidad real exige el registro nacional correspondiente (el RBR español, el RBE francés), que todavía no exponemos.

¿Cómo se compara el KYB de Prometiam con Creditsafe o Iberinform?
Para el alcance UE + RU, normalmente entre un 50 % y un 95 % más barato en escala pyme y mid-market. Ver alternativa a Creditsafe y alternativa a Iberinform.

¿Los datos son lo bastante recientes para un alta en tiempo real?
El BORME y el BODACC se actualizan a diario; Companies House es descarga mensual más incrementos diarios. /coverage devuelve latest_filing por país.

Ver también