---
title: "Enriquecer actividad económica para KYB bancario"
method: POST
path: "/kyb/enrich"
tags: ["B2B"]
---

# Enriquecer actividad económica para KYB bancario

`POST /kyb/enrich`

Vista KYB (Know Your Business) para entidades financieras. Devuelve la clasificación IAE/CNAE del cliente, perfil fiscal completo (sector de riesgo, regímenes IVA/IRPF, retenciones, casillas Modelo 036) y obligaciones fiscales aplicables. Requiere plan Profesional o superior. Envía `code` (+ `code_type` opcional) O `activity_text` (2–200 caracteres), nunca ambos a la vez.

## Request body

- KybEnrichRequest — Cuerpo de petición compartido por `/kyb/enrich` y `/onboarding/activity`. Envía un epígrafe IAE via `code` con `code_type:"iae"` (o sin `code_type`, ya que `"iae"` es el valor por defecto) O describe la actividad con `activity_text` (2–200 caracteres). Nunca envíes `code` y `activity_text` a la vez (devuelve 400). La búsqueda directa por código CNAE (`code_type:"cnae"`) no está soportada en estos endpoints — devuelve 400; usa el epígrafe IAE correspondiente o `activity_text`.
  - `code` string — Epígrafe IAE con o sin puntos (solo alfanuméricos y puntos, máx. 20 caracteres). Mutuamente excluyente con `activity_text`. Úsalo siempre junto a `code_type:"iae"` (o sin `code_type`); `code_type:"cnae"` devuelve 400 en estos endpoints.
  - `code_type` 'iae' | 'cnae' — Tipo de catálogo del código. Opcional; por defecto `"iae"`. Solo se admite `"iae"` en estos endpoints — enviar `"cnae"` devuelve 400. Para buscar por actividad sin conocer el epígrafe IAE, usa `activity_text` en su lugar.
  - `activity_text` string — Descripción libre de la actividad económica (2–200 caracteres). Mutuamente excluyente con `code`.
  - `company_name` string — Denominación social de la empresa a enriquecer con datos de constitución BORME. Debe enviarse junto con `code` o `activity_text`; en solitario devuelve 400.
  - `provincia` string — Provincia de la empresa, para desambiguar homónimos en la búsqueda BORME. Opcional, solo válido junto a `company_name`.
  - `nif` string — NIF/CIF español a validar en el censo VIES (IVA intracomunitario) de la Comisión Europea y a contrastar con la publicación oficial de deudores (art. 95 bis LGT) como señal dentro del expediente de diligencia debida. Debe enviarse junto con `code` o `activity_text`; en solitario devuelve 400. Un formato inválido (con o sin prefijo `ES`) también devuelve 400.

## Response `200`

Perfil fiscal completo para KYB

- KybEnrichResponse — Respuesta del endpoint `/kyb/enrich`.
  - `match` ActivityMatch — Resultado de la resolución del código o actividad.
    - `confidence` number, nullable — Confianza del match (0.0–1.0). null para lexical/no-match.
    - `method` 'exact_code' | 'semantic' | 'lexical' — Método de resolución: `exact_code` (código exacto), `semantic` (búsqueda semántica) o `lexical` (búsqueda léxica sin embedding).
    - `alternatives` object[] — Alternativas de menor confianza cuando el match semántico es ambiguo.
      - `code` string
      - `titulo` string
      - `type` 'iae' | 'cnae'
      - `score` number, nullable
  - `classification` ActivityClassification — Clasificación IAE y CNAE 2025 del match.
    - `iae` object, nullable
      - `code` string — Código con puntos.
      - `codeNormalized` string — Código sin puntos (normalizado).
      - `titulo` string
    - `cnae2025` object, nullable
      - `code` string — Código con puntos.
      - `codeNormalized` string — Código sin puntos (normalizado).
      - `titulo` string
  - `fiscal_profile` object — Perfil fiscal de la actividad para evaluación de riesgo KYB.
    - `sector_riesgo` string — Nivel de riesgo fiscal del sector (bajo, medio, alto).
    - `iva_regimen` string — Régimen de IVA aplicable.
    - `irpf_regimen` string — Régimen de IRPF aplicable.
    - `retencion_irpf_pct` number, nullable — Porcentaje de retención IRPF aplicable.
    - `modelo_036_casillas_relevantes` string[] — Casillas del Modelo 036 relevantes para esta actividad.
  - `obligaciones` Obligacion[] — Obligaciones fiscales (modelos AEAT) aplicables.
    - `modelo_id` string
    - `name` string, nullable
    - `periodicidad` string, nullable
    - `confidence` number, nullable
    - `reason` string, nullable
    - `fecha_proximo_plazo` string, nullable — Fecha nominal del calendario AEAT (sin prórroga de días inhábiles aplicada).
  - `subvenciones` ActivitySubvencionesBlock, nullable — Subvenciones BDNS/SNPSAP abiertas para la sección CNAE de la actividad resuelta. `null` cuando la actividad no tiene correspondencia CNAE 2025 (no se pudo derivar sección) o si el dato no está disponible. NUNCA incluye `fecha_cierre` — el dato de BDNS es poco fiable como plazo y no debe usarse para tomar decisiones de fecha límite.
    - `seccion` string, nullable — Sección CNAE (A–U) derivada del código CNAE 2025 resuelto.
    - `abiertas_count` integer — Convocatorias abiertas en esta sección CNAE.
    - `para_actividad_economica_count` integer — Subconjunto de abiertas_count dirigido a autónomos/pyme/empresa (tipos_beneficiarios).
    - `destacadas` object[] — Hasta 3 convocatorias abiertas más relevantes para la actividad.
      - `codigo_bdns` string
      - `titulo` string
      - `organo` string, nullable
      - `importe` number, nullable — Dotación de la convocatoria (no por beneficiario).
      - `url_oficial` string, uri, nullable
    - `fuente` string
  - `registro` BormeRegistroBlock — Datos de constitución de empresa (BORME) fusionados en el dossier cuando se envía `company_name` y hay coincidencia. Cobertura: constituciones desde 2026-01 (no es el Registro Mercantil completo).
    - `denominacion` string — Denominación social tal como consta en BORME.
    - `provincia` string, nullable
    - `capital_eur` number, nullable
    - `objeto_social` string, nullable
    - `cnae_registral` string, nullable — CNAE declarado en la constitución (puede diferir del CNAE clasificado por actividad).
    - `cnae_confidence` number, nullable
    - `fecha_constitucion` string, nullable — Fecha de publicación en BORME del acto de constitución (proxy — BORME no expone una fecha de constitución independiente).
    - `match_quality` 'exact' | 'multiple' | 'fuzzy' — `exact`: única coincidencia tras normalizar la denominación. `multiple`: varias empresas homónimas — se devuelve la constitución más reciente. `fuzzy`: coincidencia aproximada (reservado, no emitido actualmente).
    - `fuente` 'BORME'
    - `cobertura` 'constituciones desde 2026-01'
  - `vies` ViesResult — Resultado de la validación VIES (Comisión Europea) del NIF/CIF enviado en `nif`. Dato meramente informativo, no constituye asesoramiento fiscal.
    - `consultado` boolean — false cuando VIES no respondió (timeout, error de red o payload inesperado) — el resto del dossier se devuelve igualmente.
    - `valido` boolean — Presente solo cuando consultado=true. Indica si el NIF/CIF está registrado como operador intracomunitario válido en VIES.
    - `fecha_consulta` string — Presente solo cuando consultado=true. Fecha/hora de la consulta a VIES (ISO 8601).
    - `nota` string — Presente solo cuando consultado=true.
    - `error` 'no disponible' — Presente solo cuando consultado=false.
  - `deudores_aeat` DeudoresResult — Contraste del NIF/CIF enviado en `nif` con la publicación oficial de deudores a la Hacienda Pública (art. 95 bis LGT), como señal dentro del expediente de diligencia debida — nunca un listado independiente. Art. 95 bis.4 LGT: la publicación oficial no debe indexarse ni republicarse tal cual.
    - `comprobado` boolean — false cuando la consulta a AEAT no respondió (timeout, error de red o payload inesperado) — el resto del dossier se devuelve igualmente.
    - `aparece` boolean — Presente solo cuando comprobado=true. Indica si el NIF/CIF figura en la publicación vigente de deudores.
    - `importe_eur` number — Presente solo cuando comprobado=true y aparece=true. Importe publicado en la lista oficial de deudores (art. 95 bis LGT).
    - `edicion` string — Presente solo cuando comprobado=true. Edición de la publicación consultada.
    - `fuente` 'AEAT art. 95 bis LGT' — Presente solo cuando comprobado=true.
  - `estado_registral` EstadoRegistral — Ciclo de vida de la empresa en el Registro Mercantil (BORME) y señales de drift, fusionado en el dossier cuando se envía `company_name` y hay coincidencia en el histórico de actos BORME (vía normativa-api, distinto de `registro`, que lee la constitución local). Cobertura: actos BORME desde 2026-01 (cobertura parcial del historial registral, no el Registro Mercantil completo).
    - `estado` 'activa' | 'extinguida' | 'disuelta' | 'en_concurso' — Precedencia: concurso > extincion > disolucion > activa (por defecto cuando ninguno de los anteriores aplica).
    - `ultimo_acto` string — Tipo del acto BORME más reciente por fecha.
    - `fecha_ultimo_acto` string — Fecha del acto más reciente.
    - `senales_drift` object[] — Actos que suponen una divergencia entre la actividad/datos declarados y los registrados — señal de re-verificación (art. 10.2 RD 304/2014).
      - `tipo` 'cambio_objeto_social' | 'cambio_denominacion' | 'cambio_domicilio'
      - `fecha` string
    - `hoja` string — Hoja registral BORME de la empresa emparejada.
    - `match_quality` 'exact' | 'multiple' — `exact`: única coincidencia tras normalizar la denominación (con desambiguación por provincia si hacía falta). `multiple`: varias empresas homónimas sin provincia que las distinga — se devuelve el acto más reciente.
    - `fuente` 'BORME (Registro Mercantil)'
    - `cobertura` string
  - `riesgo_resumen` RiesgoResumen — Semáforo de riesgo que agrega estado_registral, vies, deudores_aeat y el sector de riesgo fiscal. Se incluye siempre que la petición envíe `company_name` o `nif` (aunque los bloques subyacentes no encuentren coincidencia) — un resultado limpio se expresa como `nivel:"verde"` explícito, nunca omitido.
    - `nivel` 'verde' | 'ambar' | 'rojo' — rojo: estado extinguida/en_concurso, deudores_aeat.aparece, o vies.valido=false. ambar: estado disuelta, cualquier señal de drift, o sector_riesgo="alto". verde: ninguno de los anteriores.
    - `motivos` string[] — Explicación en español de cada señal que activó el nivel — vacío cuando nivel="verde".
    - `senales_evaluadas` integer — Cuántos de los 4 bloques de entrada (estado_registral, vies, deudores_aeat, sector_riesgo) estaban presentes en la petición — no cuántos dispararon una alerta.
  - `audit` object — Metadatos de auditoría y trazabilidad de la respuesta.
    - `source` string — Identificador de la fuente de los datos.
    - `sources_oficiales` string[] — Fuentes oficiales que respaldan la clasificación. Incluye 'BORME' cuando la respuesta trae un bloque 'registro' o un bloque 'estado_registral' (una sola vez aunque traiga ambos), 'VIES' cuando trae un bloque 'vies' con consultado:true, y 'AEAT (art. 95 bis)' cuando trae un bloque 'deudores_aeat' con comprobado:true.
    - `data_version` string, nullable — Versión del catálogo usado (ISO timestamp).
    - `generated_at` string, date-time
    - `data_residency` string — Región de residencia de los datos (RGPD).
  - `_meta` Meta — Metadatos del envelope para endpoints con clave: plan actual, cuota restante y nudge de upgrade (solo plan Free al ≥80% de cuota).
    - `plan` string, required — Plan de la clave (free, profesional, empresa, enterprise).
    - `remaining` integer, required — Peticiones restantes de la cuota diaria.
    - `upgrade_hint` string — Mensaje legible de upgrade. Presente solo en plan Free al consumir ≥80% de la cuota.
    - `upgrade` UpgradeMeta — Forma estructurada del nudge de upgrade para renderizar UI nativa. Presente solo en plan Free al ≥80% de cuota.
      - `hint` string
      - `url` string, uri
      - `current_plan` string
      - `recommended_plan` object
        - `id` string
        - `label` string
        - `daily_limit` integer
        - `monthly_price_eur` integer
      - `daily_limit_after` integer
      - `price_eur_monthly` integer

## Other responses

- `400` — Petición inválida (parámetro o cuerpo mal formado).
- `401` — Falta la cabecera `X-API-Key` o la clave es inválida/desactivada.
- `403` — El endpoint requiere un plan de pago (Profesional o superior).
- `429` — Límite de cuota diaria o de ráfaga superado. La cabecera `Retry-After` indica los segundos hasta poder reintentar.
- `500` — Error interno del servidor.

## Changes

- **2026-07-26** `73d1f4818b9e` — 2 breaking, 3 warning, 5 info
  - added `#/components/schemas/ActivityLookupRequest, subschema #2` to the request body `allOf` list
  - the request's body type changed from `object` to no type
  - removed the request property `activity_text`
  - removed the request property `code`
  - …6 more

[Change history](https://skmtc.dev/conversoriaecnae/apis/conversor-iae-cnae-api/changes/kyb/enrich/post.md)

---

[API](https://skmtc.dev/conversoriaecnae/apis/conversor-iae-cnae-api.md) · [All operations](https://skmtc.dev/conversoriaecnae/apis/conversor-iae-cnae-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/conversoriaecnae/conversor-iae-cnae-api/revisions/2f9842f5e11b/schema)