Regístrate

Caso de uso · Cumplimiento y AML

API de verificación de titularidad real

El registro PSC del Reino Unido para titularidad real de verdad, administradores para España, Francia, Noruega y Polonia, padres GLEIF para quien tiene LEI, y cribado de sanciones para cada nombre recopilado — una sola clave, y una respuesta clara para todo lo demás.

Publicado el 16 de septiembre de 2026 · English version

TL;DR

Aquí solo existen datos reales de titularidad real para un país: el Reino Unido, vía el registro Persons with Significant Control (PSC), incluido en la ficha de empresa y consultable por nombre. España, Francia y Noruega devuelven administradores y cargos — una señal real, pero no titularidad real. Irlanda es a nivel empresa, sin ningún dato de administradores. GLEIF Level 2 añade un padre societario declarado para las entidades con Legal Entity Identifier — un vínculo de grupo, no un porcentaje de propiedad. Prometiam no tiene el Registro Central de Titularidades Reales (RCTIR) español, el Registre des bénéficiaires effectifs francés, el RBO irlandés, el CRBR polaco, ni el registro noruego de titulares reales — combina esta API con uno de ellos, o con una solicitud documental, para cerrar el hueco.

El problema

La verificación de titularidad real suele recaer en el responsable de cumplimiento o en el analista AML que ejecuta el KYB, y plantea una pregunta muy concreta: quién posee o controla en última instancia esta contraparte por encima de un umbral regulatorio — no quién figura como administrador. Ambas cosas se confunden constantemente, porque un listado de administradores es fácil de obtener y un registro de titularidad real casi nunca lo es: tras una sentencia del TJUE de 2022, la mayoría de los estados miembros de la UE restringieron el acceso público a sus registros de titularidad real, así que una consulta que antes era una búsqueda gratuita hoy es una autodeclaración o una solicitud documental.

El Reino Unido es la excepción: su registro PSC es público, y Prometiam lo sirve a través de los mismos endpoints que el resto de países. Eso convierte al Reino Unido en el único lugar donde "titular real" significa lo que dice — en todos los demás, lo que se obtiene son administradores, o nada.

El patrón

Dos llamadas concentran la señal de titularidad real del Reino Unido. GET /people/search?country=GB resuelve un nombre a candidatos de persona — administradores y PSC juntos, ordenados por match_score. GET /companies/{id}?country=GB devuelve la ficha completa de empresa con todos los cargos y nombramientos PSC en su array contacts. Ambas necesitan country=GB para llegar a la capa PSC: las mismas llamadas contra ES, FR o NO devuelven solo administradores; contra IE o PL, nada (a nivel empresa).

# Buscar registros PSC / de administradores del Reino Unido por nombre
curl 'https://api.prometiam.com/functions/v1/risk-api/people/search?country=GB&name=Jane+Smith' \
  -H 'Authorization: Bearer rk_live_...'

# Ficha completa de empresa — {id} es el id interno de un resultado de /companies/search,
# no el company number. contacts[] guarda administradores Y PSC juntos.
curl 'https://api.prometiam.com/functions/v1/risk-api/companies/{id}?country=GB' \
  -H 'Authorization: Bearer rk_live_...'

Dos señales relacionadas: GET /people/{id} extrae el historial completo de nombramientos de una persona marcada, y GET /directors/network localiza a la misma persona dirigiendo un número inusual de otras empresas — una señal de concentración, no de propiedad. Consulta análisis de red de administradores (en inglés) para ese patrón.

Un ejemplo real

Para un número de empresa del Reino Unido, el script siguiente resuelve el id interno, lista a todos en contacts (administradores y PSC juntos — role indica cuál es cuál), resuelve la cadena de padres GLEIF de la empresa si tiene LEI, y criba cada nombre recopilado — PSC, administradores y la razón social del padre LEI — en una sola llamada por lote de sanciones.

# ubo_check.py -- comprobación de titularidad real del Reino Unido: ficha, PSC/administradores, padre LEI, sanciones
import os, requests

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

def get(path, **params):
    r = requests.get(f'{API}{path}', params=params, headers=HEAD)
    r.raise_for_status()
    return r.json()['data']

def ubo_check(company_number):
    # 1. Resolver el id interno a partir de un company number del Reino Unido
    hits = get('/companies/search', country='GB', company_number=company_number)
    if not hits:
        return {'error': 'empresa no encontrada'}
    company = hits[0]

    # 2. Ficha completa -- administradores y PSC viven juntos en contacts
    profile = get(f"/companies/{company['id']}", country='GB')
    people = [{'name': c['full_name'], 'role': c['role']} for c in profile.get('contacts', [])]
    names_to_screen = {p['name'] for p in people if p['name']}

    # 3. Cadena de padres LEI -- solo existe si la empresa tiene LEI
    parents = None
    candidates = get('/lei/search', name=profile['company_name'])
    if candidates:
        rel = get(f"/lei/{candidates[0]['lei']}/relationships")
        parents = {'direct_parent': rel.get('direct_parent'), 'ultimate_parent': rel.get('ultimate_parent')}
        if rel.get('ultimate_parent'):
            names_to_screen.add(rel['ultimate_parent']['legal_name'])

    # 4. Una sola llamada por lote criba todos los nombres recopilados (beta; exige el scope de sanciones)
    resp = requests.post(f'{API}/sanctions/screen', headers=HEAD,
                          json={'names': sorted(names_to_screen), 'group': 'entity'})
    resp.raise_for_status()

    return {'company': profile['company_name'], 'people': people,
            'lei_parents': parents, 'screening': resp.json()['data']}

if __name__ == '__main__':
    import sys, json
    print(json.dumps(ubo_check(sys.argv[1]), indent=2, ensure_ascii=False))

Unas 30 líneas. El paso 4, POST /sanctions/screen, exige el scope de sanciones directamente — a diferencia de la forma GET de un solo nombre, la llamada por lote se salta la cuota de prueba gratuita, así que este script necesita una clave Professional para llegar al paso 4. Sustitúyelo por un bucle de llamadas GET /sanctions/screen (misma cuota de prueba que /people/search) para prototipar el resto en la prueba gratuita de 14 días.

Qué te devuelve

  • GET /people/search y GET /people/{id} devuelven una persona: full_name, nif, is_legal_entity, match_score en una búsqueda por nombre, first_seen_date / last_seen_date, y appointments[].
  • Cada nombramiento — en appointments[] o en el contacts[] de una empresa — lleva full_name, role, appointment_date, end_date, is_current, company_name y company_number. En un registro del Reino Unido, role indica el cargo ocupado o, en un registro PSC, la naturaleza del control declarado — por ejemplo, más del 25 % de las acciones, o el derecho a nombrar administradores.
  • GET /lei/search devuelve candidatos con lei, legal_name, jurisdiction, entity_status, city y country. GET /lei/{lei}/relationships devuelve direct_parent y ultimate_parent con la misma forma, además de direct_children (hasta 15) — solo cuando la entidad declaró la relación a GLEIF; muchas no declaran ninguna.
  • POST /sanctions/screen devuelve un resultado por nombre, en orden: status (match, clear, error o timeout — clear significa que no hay coincidencia por encima de tu umbral, no una certificación), hits[] con la misma forma que el endpoint de un solo nombre (entity_name, aliases, source_list, program, listing_date, is_active, match_score), más hit_count, distinct_entities y best_match_score.

Encaje de precio

Por volumen bruto de créditos — cuatro llamadas por comprobación: ficha (1 crédito), búsqueda PSC/administradores (2), LEI (1), cribado de sanciones (3), es decir 7 créditos — los 500 créditos de la prueba gratuita cubrirían unas 70 comprobaciones, y los 1.000 al mes del plan Starter unas 140. Eso exagera lo que ambos planes ejecutan en la práctica, porque dos de las cuatro llamadas están limitadas por scope: /people/search exige el scope de personas (Starter en adelante; Free tiene una cuota de prueba de 25 llamadas al mes), y el acceso completo a /sanctions/screen exige el scope de sanciones (Professional en adelante; la llamada por lote de arriba lo exige directamente, sin cuota de prueba).

Así que Free sirve para construir y probar el patrón anterior, no para ejecutarlo en producción. Starter (9,99 €/mes, 1.000 créditos al mes) levanta el límite de la búsqueda PSC/administradores pero aún carece de cribado de sanciones completo. Professional (29,99 €/mes, 10.000 créditos al mes, cribado de sanciones y de listas de control de exportación completo) ejecuta los cuatro pasos — unos 20 a 22 créditos por comprobación si criba cinco o seis nombres (3 créditos cada uno), es decir, unas 450 a 500 comprobaciones al mes; Scale (50.000 créditos al mes) unas 2.300 a 2.500.

Límites de alcance, sin rodeos

  • La titularidad real solo es real para el Reino Unido, a través del registro PSC incluido en la ficha de empresa y vía /people/search / /people/{id}.
  • España, Francia, Noruega y Polonia devuelven administradores y cargos a través de los mismos endpoints — eso no es titularidad real, solo quién ocupa un cargo.
  • Irlanda es a nivel empresa: sin administradores, sin PSC, nada sobre quién dirige o posee la empresa.
  • GLEIF Level 2 (/lei/{lei}/relationships) da el padre directo y el padre último, y hasta 15 filiales directas, para una entidad con LEI que ha declarado la relación — un vínculo de grupo societario, no un porcentaje de participación ni un titular real persona física, y muchas entidades no declaran ninguno.
  • Prometiam no tiene el Registro Central de Titularidades Reales (RCTIR) español, el Registre des bénéficiaires effectifs francés, el RBO irlandés, el CRBR polaco, ni el registro noruego de titulares reales. Ninguno de estos registros es consultable a través de esta API, en ningún plan.
  • El cribado de sanciones está en beta. El cribado PEP está disponible aparte (consulta cribado de sanciones, en inglés), y está en beta, solo España, sin familiares ni allegados (RCA).
  • Sin registros de accionistas, sin porcentajes de propiedad más allá de PSC y GLEIF Level 2, sin reputación adversa, sin verificación de documento de identidad, y sin credit score ni risk score — una coincidencia de sanciones lleva un match_score, que es una confianza de coincidencia de nombre, no una calificación de riesgo.
  • El AMLR (Reglamento (UE) 2024/1624, aplicable desde el 10 de julio de 2027) fija el umbral de titularidad real en el 25 % de la propiedad o los derechos de voto, 15 % en sectores de mayor riesgo — consulta el calendario de cumplimiento del AMLR (en inglés). Esta página no es asesoramiento legal: describe lo que devuelve la API, no si una estructura concreta cumple tu obligación.

Preguntas frecuentes

¿Tiene Prometiam un registro de titularidad real?
Solo para el Reino Unido. El registro Persons with Significant Control (PSC) se incluye en la ficha de empresa (GET /companies/{id}?country=GB) y es consultable por nombre (GET /people/search?country=GB). España, Francia y Noruega devuelven administradores y cargos a través de los mismos endpoints — una señal real, pero no titularidad real. Irlanda es a nivel empresa, sin datos de administradores ni de PSC.

¿Cómo compruebo la titularidad real de una empresa española, francesa, irlandesa, polaca o noruega?
Combina lo que devuelve la API — identidad, estado, administradores cuando existen, padres LEI y cribado de sanciones sobre los nombres recopilados — con el registro propio del país o una solicitud documental: el Registro Central de Titularidades Reales (RCTIR) en España, el Registre des bénéficiaires effectifs en Francia, el RBO en Irlanda, el CRBR en Polonia, o el registro de titulares reales en Noruega. Ninguno de estos registros es consultable a través de esta API.

¿Qué aporta la cadena de padres LEI de GLEIF?
Para una entidad con Legal Entity Identifier que ha declarado la relación a GLEIF, GET /lei/{lei}/relationships devuelve su padre directo, su padre último y hasta 15 filiales directas. Es un vínculo de grupo societario declarado, no un porcentaje de propiedad ni un titular real persona física, y muchas entidades no declaran ninguna relación.

¿Qué umbral de titularidad real usa el AMLR?
El Reglamento (UE) 2024/1624 (AMLR), aplicable en toda la UE desde el 10 de julio de 2027, fija el umbral de titularidad real en el 25 % de la propiedad, los derechos de voto u otro interés, con la posibilidad de que la Comisión lo reduzca al 15 % en sectores de mayor riesgo. Consulta el calendario de cumplimiento del AMLR. Esto no es asesoramiento legal.

¿Cuánto cuesta una comprobación de titularidad real del Reino Unido?
Las consultas a la ficha de empresa y a LEI funcionan en todos los planes, incluido el gratuito. /people/search exige el scope de personas desde el plan Starter (9,99 €/mes); el acceso completo a /sanctions/screen exige el scope de sanciones desde el plan Professional (29,99 €/mes), que además incluye el cribado de listas de control de exportación. Una clave de prueba permite probar /people/search 25 veces al mes; la llamada de sanciones por lote exige el plan Professional directamente.