Caso de uso · Riesgo de terceros

API de Diligencia de Proveedores

Resuelva cada proveedor a un identificador oficial, obtenga la ficha registral, críbelo a él y a sus administradores contra sanciones, compruebe si hay concurso o insolvencia societaria, y siga vigilando tras el alta — en cualquier país que cubre la API, desde una sola API REST.

Publicado el 15 de septiembre de 2026

El problema

Compras y gestión de proveedores homologan a un proveedor una vez — un formulario, un par de documentos, quizá una consulta manual al registro — y pasan al siguiente. El proveedor que parecía correcto en el alta puede cambiar: un administrador cesa, la sociedad entra en concurso, una filial aparece en una lista de sanciones dieciocho meses después. Nadie repite la comprobación original, porque nunca se construyó para repetirse.

Los equipos financieros notan el mismo hueco desde otro ángulo: una factura pagada a un proveedor que ya ha solicitado el concurso de acreedores, o transferida a una entidad que ya no existe legalmente, es dinero que no vuelve.

La Directiva europea de diligencia debida en sostenibilidad corporativa (CSDDD) y la mayoría de políticas internas de riesgo de terceros piden la misma base, con independencia del papeleo que la rodee: confirmar que la contraparte existe y está activa, cribarla por exposición a sanciones, y saber si atraviesa dificultades financieras — en el alta y de nuevo después. Prometiam no es asesoramiento legal sobre si una relación de proveedor concreta cumple una u otra; es la capa de identidad, estado, sanciones e insolvencia que un expediente de diligencia debida necesita para mostrar que las comprobaciones se hicieron.

El patrón

Cinco llamadas, todas por lotes, para que todo el maestro de proveedores se mueva a la vez en lugar de fila a fila:

1. Resolver. POST /companies/lookup admite hasta 100 proveedores por llamada — por company_number, nif, siren, vat o un name difuso con match_score — y devuelve un identificador oficial por fila, en el orden enviado.
2. Verificar. GET /companies/{id}?include=risk_flags,insolvency,lei trae la ficha completa: status registral, dissolution_date, administradores donde el registro los recoja, el aviso de grandes deudores de la AEAT solo para España, y cualquier LEI que la empresa tenga registrado.
3. Cribar. POST /sanctions/screen comprueba la razón social y, donde exista, cada administrador, contra sanciones y las listas de control de exportaciones de EE. UU. en la misma llamada — hasta 50 nombres, con un threshold a su elección. Beta, y alcance de plan Professional.
4. Comprobar insolvencia. POST /insolvency/check cubre hasta 100 elementos por llamada en dieciséis mercados con cobertura de insolvencia societaria, España incluida (los concursos del BORME, enlazados por NIF); GET /search también sirve los anuncios concursales de España.
5. Seguir vigilando. POST /monitor da de alta una empresa para avisos por webhook en 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; un barrido diario con GET /company-events/search hace el mismo trabajo por sondeo, para España, Francia y Reino Unido.

# 1. Resolver cada proveedor a un identificador oficial — hasta 100 por llamada
curl -X POST "https://api.prometiam.com/functions/v1/risk-api/companies/lookup" \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "country": "ES", "nif": "B12345678" },
      { "country": "FR", "siren": "552032534" }
    ]
  }'

# 2. Obtener la ficha: status, dissolution_date, administradores, el aviso
#    de la AEAT solo en España, y el bloque LEI
curl "https://api.prometiam.com/functions/v1/risk-api/companies/812044?include=risk_flags,insolvency,lei" \
  -H "Authorization: Bearer rk_live_..."

# 3. Cribar la razón social y cada administrador — alcance de plan Professional, beta
curl -X POST "https://api.prometiam.com/functions/v1/risk-api/sanctions/screen" \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "names": ["ACME TRADING SL"], "threshold": 85 }'

# 4. España: anuncios concursales por GET /search
curl "https://api.prometiam.com/functions/v1/risk-api/search?vat=B12345678&country=ES" \
  -H "Authorization: Bearer rk_live_..."

# 5. Proveedores extranjeros: insolvencia societaria por el índice de dieciséis mercados
curl -X POST "https://api.prometiam.com/functions/v1/risk-api/insolvency/check" \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "items": [ { "country": "FR", "company_number": "552032534" } ] }'

# 6. Seguir vigilando: webhook para 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
curl -X POST "https://api.prometiam.com/functions/v1/risk-api/monitor" \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": 812044,
    "country": "ES",
    "webhook_url": "https://tu-erp.example.com/hooks/prometiam"
  }'

Un ejemplo real

En la práctica esto se ejecuta como un trabajo por lotes contra su maestro de proveedores: extraiga la lista, divídala en bloques de 100, y escriba una fila de resultado por proveedor.

import os, csv, requests

API = "https://api.prometiam.com/functions/v1/risk-api"
HEAD = {"Authorization": f"Bearer {os.environ['PROMETIAM_API_KEY']}"}
PAISES_INSOLVENCIA = {"FR", "DE", "GB", "AT", "CH", "NO", "FI", "US", "NL", "DK", "HR", "SE"}

def lotes(items, tam=100):
    for i in range(0, len(items), tam):
        yield items[i:i + tam]

def comprobar_cartera(proveedores):
    # proveedores: [{"country": "ES", "nif": "B12345678"}, ...]
    filas = []
    for lote in lotes(proveedores, 100):
        resueltos = requests.post(f"{API}/companies/lookup", json={"items": lote}, headers=HEAD).json()["data"]
        for proveedor, resultado in zip(lote, resueltos):
            empresa = resultado.get("company")
            fila = {"pais_entrada": proveedor["country"],
                    "id_entrada": proveedor.get("nif") or proveedor.get("siren") or proveedor.get("name"),
                    "status": resultado["status"], "company_id": None, "razon_social": None,
                    "estado_registral": None, "sanciones": None, "insolvencia": None}
            if empresa:
                fila["company_id"], fila["razon_social"], fila["estado_registral"] = (
                    empresa["id"], empresa["company_name"], empresa["status"])
                sanc = requests.post(f"{API}/sanctions/screen", headers=HEAD,
                    json={"names": [empresa["company_name"]], "threshold": 85}).json()["data"][0]
                fila["sanciones"] = sanc["status"]  # match | clear | error | timeout
                if proveedor["country"] == "ES":
                    # España: anuncios concursales por GET /search (también están en el índice de dieciséis mercados)
                    avisos = requests.get(f"{API}/search", headers=HEAD,
                        params={"vat": empresa["company_number"], "country": "ES"}).json()["data"]
                    fila["insolvencia"] = "found" if avisos else "none"
                elif proveedor["country"] in PAISES_INSOLVENCIA:
                    ins = requests.post(f"{API}/insolvency/check", headers=HEAD, json={"items": [
                        {"country": proveedor["country"], "company_number": empresa["company_number"]}]}).json()["data"][0]
                    fila["insolvencia"] = ins["status"]  # found | none | error | timeout
                # Irlanda y Polonia: sin cobertura de anuncios de insolvencia todavía, queda en None
            filas.append(fila)
    return filas

proveedores = [{"country": "ES", "nif": "B12345678"}, {"country": "FR", "siren": "552032534"}]
filas = comprobar_cartera(proveedores)
with open("resultados_proveedores.csv", "w", newline="") as f:
    w = csv.DictWriter(f, fieldnames=list(filas[0].keys()))
    w.writeheader()
    w.writerows(filas)

Unas 40 líneas. Resuelve un bloque de hasta 100 proveedores en una sola llamada, y luego criba (alcance de plan Professional) y comprueba la insolvencia solo de los que encontró — dirigiendo la comprobación al endpoint correcto según el país: POST /insolvency/check para los dieciséis mercados con cobertura (España incluida; GET /search también sirve sus anuncios), y dejando la columna vacía para Irlanda y Polonia en lugar de reportar un falso "none", porque ninguna de las dos tiene cobertura de anuncios de insolvencia todavía.

Lo que devuelve

La respuesta de resolución trae un resultado por proveedor, en el orden de la solicitud: un status de found, not_found, error o timeout; el objeto company resuelto o null; y un match_score cuando la coincidencia viene de un nombre en lugar de un identificador exacto. meta.found y meta.not_found dan los totales del lote.

La ficha añade status, dissolution_date, founding_date, el capital registrado, y contacts — cada administrador con su full_name, role, appointment_date y is_current — más, donde se solicite, el aviso de grandes deudores de la AEAT y la ficha LEI de la empresa.

El cribado de sanciones devuelve un status de match, clear, error o timeout por nombre, con hits que trae match_score, source_list, program y listing_date, además de hit_count y distinct_entities. La comprobación de insolvencia devuelve status found, none, error o timeout, hasta cinco notices de más reciente a más antiguo, y latest_filing_date. Un resultado none o clear significa que nada coincidió en los mercados cubiertos — no es prueba de que el proveedor esté solvente o ausente de cualquier otra lista.

www.prometiam.com/dashboard/companies

Límites de alcance, dicho con claridad

Los cinco pasos anteriores no llegan a cada país de la misma manera. Esto es lo que cada país realmente soporta:

Resolver y la ficha (pasos 1 y 2) funcionan igual para todos. El cribado de sanciones también corre en todos, sobre la razón social como mínimo — alcance de plan Professional, beta.

• La titularidad real es solo el registro británico de Personas con Control Significativo; el resto de registros devuelve administradores y consejeros, no titulares reales. Un proveedor con Identificador de Entidad Legal (LEI) añade los padres de GLEIF Nivel 2 vía GET /lei/{lei}/relationships.
• Los avisos de riesgo son solo de España: la lista de grandes deudores de la AEAT es de un momento dado — saldos a 31 de diciembre del año anterior, publicados unos seis meses después — no un saldo en vivo.
• El cribado PEP existe (beta, solo España, por ocupación, sin familiares ni allegados) pero es un aviso aparte, no parte de este patrón.
• Prometiam no devuelve una puntuación de crédito, un estado financiero ni datos ESG, para ningún país. El historial de adjudicaciones de contratos públicos es un endpoint aparte para España, Francia, Reino Unido, Irlanda, Polonia y Noruega (contratación pública).

Ajuste de precio

POST /companies/lookup, GET /companies/{id} y POST /insolvency/check corren en el mismo alcance base que una búsqueda de empresas, así que un maestro de 2.000 proveedores es 2.000 + 2.000 + 4.000 = 8.000 créditos (1 por consulta, 1 por ficha, 2 por comprobación de insolvencia) — más de lo que incluye el plan Starter (9,99 €/mes, 1.000 créditos, 60 solicitudes/min), así que hace falta el plan Professional.

El cribado de sanciones es el único paso limitado por alcance en lugar de por volumen: POST /sanctions/screen necesita el plan Professional (29,99 €/mes, 10.000 créditos, 120 solicitudes/min), sea cual sea el tamaño del maestro — es también donde se activa el cribado completo de sanciones y control de exportaciones. Cribar los 2.000 nombres suma 6.000 créditos (3 por nombre), 14.000 con los otros tres pasos, así que Professional cubre el maestro en dos meses y Scale (99,99 €/mes, 50.000 créditos, 300 solicitudes/min) en uno, con margen para una revisión mensual y los proveedores nuevos que se sumen.

Cada elemento de un lote cuenta como una solicitud. Un lote mayor que lo que queda en el plan para ese minuto, día o mes se rechaza de antemano con 429 batch_exceeds_quota, y max_items_now en la respuesta indica cuántos caben ahora mismo — para que un script divida el resto y lo reintente en lugar de adivinar.

Preguntas frecuentes

¿Qué se entiende por diligencia debida de un proveedor?
Como mínimo: confirmar que la entidad existe y está activa, cribar su razón social y sus administradores donde el registro los recoja contra las listas de sanciones, y comprobar si hay anuncios de insolvencia societaria. La Directiva europea de diligencia debida en sostenibilidad corporativa (CSDDD) y la mayoría de políticas internas de riesgo de terceros piden esa misma base. Prometiam no es asesoramiento legal sobre si una relación concreta cumple una u otra — aporta las comprobaciones de identidad, estado, sanciones e insolvencia que el expediente necesita para mostrar que se hicieron.

¿Puedo ejecutar esto contra varios miles de proveedores a la vez?
Sí. POST /companies/lookup y POST /insolvency/check admiten hasta 100 elementos por llamada, y POST /sanctions/screen hasta 50 nombres. Cada elemento cuenta como una solicitud dentro de su plan. Un lote mayor que lo que queda en el plan se rechaza de antemano con 429 batch_exceeds_quota, y max_items_now en la respuesta indica cuántos caben ahora mismo. El cribado de sanciones necesita además el alcance del plan Professional; los otros tres endpoints por lotes funcionan en cualquier plan.

¿Esto cubre la titularidad real, no solo los administradores?
Solo para el Reino Unido, a través del registro de Personas con Control Significativo (PSC) en la ficha de la empresa. España, Francia, Reino Unido, Noruega, Polonia y Chequia (personas físicas polacas enmascaradas por el propio registro; las checas, solo el nombre y el mes y año de nacimiento) devuelven administradores y consejeros, pero un administrador no es un titular real. Irlanda es a nivel de empresa: sin administradores todavía, para ninguna de las dos cosas. Si el proveedor tiene un identificador LEI, GET /lei/{lei}/relationships añade el padre directo y el último de GLEIF Nivel 2.

¿Qué países tienen realmente cobertura de insolvencia para un proveedor?
España, Francia, Reino Unido, Noruega, Finlandia, Dinamarca, Croacia, Suecia, Suiza, Letonia y Estonia tienen cobertura societaria a través de POST /insolvency/check (los concursos de España, publicados en el BORME, se vinculan por NIF; los avisos suizos se vinculan a la ficha de empresa por UID cuando el aviso lo nombra), junto con otros mercados donde Prometiam no tiene registro mercantil: Alemania, Austria, Estados Unidos y Países Bajos. Irlanda y Polonia no tienen cobertura de anuncios de insolvencia en ninguno de los dos endpoints todavía, ni tampoco Bélgica o Eslovaquia (su quiebra figura en el estado de la empresa).

¿Cómo sigo vigilando a un proveedor tras el alta?
Dos formas. POST /monitor da de alta una empresa y envía un webhook firmado ante cambios de estado, disolución y nuevas coincidencias en sanciones, para 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. Para España, Francia y Reino Unido, un barrido diario con GET /company-events/search sobre su propio maestro de proveedores recoge capital_change, director_change, dissolution y el resto. Noruega solo tiene eventos de cambio del registro, desde el 14 de octubre de 2026 (sin boletín), y un proveedor noruego se vigila con POST /monitor.

Relacionado

• Diligencia debida continua — el mismo patrón de vigilancia aplicado de forma continua a cualquier contraparte, no solo a proveedores
• Concursos de acreedores por API — la guía completa de anuncios concursales y de riesgo para España
• Verificar NIF de empresa por API — cómo resolver y validar un NIF español paso a paso
• Supplier Due Diligence API — la edición en inglés de este mismo caso de uso
• Batch screening (en inglés) — resoluciones, cribado e insolvencia a escala de lista
• Prometiam en español — la página de inicio en español