---
title: "Configurar actividad para onboarding SaaS / facturación"
method: POST
path: "/onboarding/activity"
tags: ["B2B"]
---

# Configurar actividad para onboarding SaaS / facturación

`POST /onboarding/activity`

Vista de onboarding para SaaS de facturación y ERPs. Dado un código IAE/CNAE o texto de actividad libre, devuelve toda la configuración fiscal necesaria para pre-rellenar un alta de autónomo o empresa: epígrafe IAE, casillas Modelo 036, tipo y régimen de IVA, retención IRPF (tipo general y tipo inicio de actividad), régimen recomendado y próximos plazos fiscales. Requiere plan Profesional o superior. Envía `code` (+ `code_type` opcional) O `activity_text` (2–200 caracteres), nunca ambos a la vez.

## Request body

- ActivityLookupRequest — 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`.

## Response `200`

Configuración fiscal para onboarding

- OnboardingActivityResponse — Respuesta del endpoint `/onboarding/activity`.
  - `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
  - `alta_036` object — Datos para pre-rellenar el Modelo 036 de alta.
    - `epigrafe_iae` string, nullable — Epígrafe IAE a consignar en el Modelo 036.
    - `casillas_relevantes` string[] — Casillas del Modelo 036 relevantes para esta alta.
  - `facturacion` object — Configuración de facturación para pre-rellenar el SaaS.
    - `iva_tipo` union — Tipo de IVA aplicable (número, p. ej. 21, o 'exento').
      - number
      - 'exento'
    - `iva_regimen` string, nullable — Régimen de IVA aplicable.
    - `retencion_irpf` object
      - `tipo` number, nullable — Tipo de retención IRPF general (número, p. ej. 15).
      - `tipo_inicio_actividad` number, nullable — Tipo reducido para los 3 primeros años de actividad (p. ej. 7). Null cuando no aplica.
    - `verified` boolean — Si la configuración está verificada contra fuentes oficiales.
  - `regimen_recomendado` object, nullable — Régimen fiscal recomendado para esta actividad. Null si no se pudo determinar.
    - `modulos_elegible` boolean
    - `modulos_summary` string, nullable
    - `calculo_hints` unknown
    - `verified` boolean
  - `calendario` Obligacion[] — Próximos plazos fiscales aplicables (misma estructura que Obligacion).
    - `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
  - `reta` object — Información orientativa sobre la cuota RETA.
    - `tarifa_plana_eur_mes` number, nullable — Cuota de tarifa plana (€/mes). Null si no aplica.
    - `base_minima_aplica` boolean — Si se puede optar por la base mínima RETA.
    - `nota` string — Nota informativa sobre la cuota RETA.
    - `mei_eur_mes` number, nullable — Cuota MEI mensual (€) cuando aplica.
    - `total_primer_periodo_eur_mes` number, nullable — Total primer periodo RETA (€/mes) cuando aplica.
    - `source_anchor` string, nullable — Referencia normativa de la tarifa plana.
  - `_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.

---

[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)