# Conversor IAE/CNAE API — Pricing and Capabilities

Infraestructura de datos fiscales para el software español. REST API for Spanish tax codes IAE (Impuesto sobre Actividades Económicas), CNAE 2025 (Clasificación Nacional de Actividades Económicas, the Spanish implementation of NACE Rev. 2), and AEAT (Agencia Estatal de Administración Tributaria) tax models. Built for gestorías, fintech onboarding (KYB), ERPs, and banca that need verified classification data without scraping AEAT or INE. Plan Gratis covers most prototypes; production starts at 29 EUR/month.

- Base URL: `https://www.conversoriaecnae.es/api/v1`
- Authentication: `X-API-Key` header
- Response format: JSON, UTF-8
- Region: Vercel + Supabase eu-central-2
- Status: production, stable since 2025

## Pricing Tiers

| Tier | Price | Daily quota | Burst limit | Use case | Checkout |
|------|-------|-------------|-------------|----------|----------|
| Gratis | 0 EUR | 250 req/day | 10 req/min | Prototypes, side projects, evaluation | https://www.conversoriaecnae.es/precios#signup-free |
| Profesional | 29 EUR/month (290 EUR/year, 2 months free) | 2 000 req/day | 30 req/min | Gestorías, fintech onboarding, ERP integrations in production | https://www.conversoriaecnae.es/precios |
| Empresa | 79 EUR/month (790 EUR/year, 2 months free) | 10 000 req/day | 100 req/min | SaaS multi-tenant, banking KYB/onboarding, high-volume directories | https://www.conversoriaecnae.es/precios |
| Enterprise | Custom | Unlimited | Negotiated | Negotiated SLA, dedicated account manager, white-label available | mailto:brian@conversoriaecnae.es |

Billed monthly or annually via Stripe (annual = 2 months free on Profesional and Empresa). EU VAT handled by Stripe Tax. No overage billing — requests beyond the daily quota get `429` until the window resets; there is no surprise invoice.

- **Gratis** includes: IAE/CNAE search, 7 500 requests/month, the 18 free MCP tools, full documentation.
- **Profesional** adds: white-label responses (no `_source` field), the `/bulk` endpoint (up to 50 codes) plus `consulta_masiva` in MCP, CNAE 2009 → CNAE 2025 correspondence, AI enrichment (`ai_summary`, `fiscal_signals`, semantic crosswalks), full DGT/legislación/BORME/subvenciones datasets, priority support.
- **Empresa** adds: the B2B KYB and onboarding dossiers (see below), source-audit + EU data-residency attestation, **99.9% SLA**, **DPA contract**, dedicated support.
- **Enterprise** adds: unlimited requests, negotiated SLA, dedicated account manager, white-label.

## Endpoints

### Detail endpoints

| Method | Path | Description | Min tier |
|--------|------|-------------|----------|
| GET | `/iae/{code}` | IAE epígrafe: title, description, módulos eligibility. Crosswalk fields (associated CNAE, related IAE) require Profesional. | Gratis |
| GET | `/cnae/{code}` | CNAE 2025 code: title, description, category, sector. Crosswalk fields (`associated_iae`, `related_cnae`, `cnae_2009`) require Profesional. | Gratis |
| GET | `/cnae-2009/{code}` | CNAE 2009 → CNAE 2025 equivalence with migration notes | Profesional |

Code format accepts both dotted (`501.3`) and dotless (`5013`). URLs are normalized before lookup.

### Empresas (firmografía por actividad)

| Method | Path | Description | Min tier |
|--------|------|-------------|----------|
| GET | `/empresas/{cnae}` | BORME company-formation firmographics for a CNAE 2025 code: total constitutions, avg/median capital, monthly trend, top provinces (aggregates are free). The full recent-company list (denominación, capital, date, CNAE) plus `limit`/`offset` pagination require Profesional. | Gratis |

Company-level data only (Ley 37/2007) — no personal data. Free keys get the aggregates plus a 3-row sample.

### B2B activity-profile (Empresa tier)

Two thin, persona-specific projections over the same actividad → perfil fiscal core (`lib/api/activity-profile.ts`). Both accept `code`, `code_type`, `activity_text`, and `strict` in the body; sending both a direct `code` and free-text `activity_text` returns `400`.

| Method | Path | Description | Min tier |
|--------|------|-------------|----------|
| POST | `/kyb/enrich` | Bank KYB dossier: activity classification, fiscal profile, and `sector_riesgo`, plus an `audit` block (sources, `data_version`, EU residency). | Empresa |
| POST | `/onboarding/activity` | SaaS onboarding dossier: `alta_036`, `facturacion` (IVA/retención), `regimen_recomendado`, `calendario`, and an honest RETA floor (never fabricates a cuota — needs `rendimiento_neto` for the real figure). | Empresa |

### Search

| Method | Path | Description | Min tier |
|--------|------|-------------|----------|
| GET | `/search?q={query}&type={iae\|cnae\|both}&limit={1-50}` | Hybrid lexical + semantic search across IAE/CNAE/CNAE 2009 (768-dim Gemini embeddings) | Gratis |

Search returns top-K results with relevance scores. Semantic component is optional and degrades gracefully under quota pressure.

### Bulk

| Method | Path | Description | Min tier |
|--------|------|-------------|----------|
| POST | `/bulk` | Lookup up to 50 codes in one request; body: `{"codes":["501.3","504.1"],"type":"iae"}` | Profesional |

### Calendar

| Method | Path | Description | Min tier |
|--------|------|-------------|----------|
| GET | `/calendario/{code_type}/{code}.ics` | iCalendar feed of AEAT model deadlines applicable to a code (036, 130, 303, 347, 349, 390, 100, 131) | Gratis |

Subscribable from Google Calendar, Outlook, Apple Calendar. Updated quarterly.

### Legislación (BOE consolidado)

| Method | Path | Description | Min tier |
|--------|------|-------------|----------|
| GET | `/legislacion?q={query}&boe_id=&limit=&offset=` | Full-text search over in-force BOE consolidated law text. Free tier returns the top 3 snippets for `q` only. | Gratis |
| GET | `/legislacion/{boe_id}?articulo=&facts=&full=&historial=` | Consolidated article text for a BOE norm (free tier). | Gratis |

Paid extras — fact-graph (`facts`), full norm dump (`full`), version history (`historial`), `boe_id` filtering and real pagination on search — require Profesional or higher.

### Account

| Method | Path | Description | Min tier |
|--------|------|-------------|----------|
| POST | `/signup` | Create free API key; body: `{"email":"...", "name":"...", "terms_accepted":true}`. No credit card required. | n/a |

## Quick Start (Free Tier)

1. Request a free API key:

```bash
curl -X POST https://www.conversoriaecnae.es/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","name":"Tu Nombre","terms_accepted":true}'
```

The response returns your full key in `api_key` (shown only once — save it immediately; it is also emailed to you) plus a `masked_key` field for reference.

2. Make your first call:

```bash
curl -H "X-API-Key: YOUR_KEY" \
  https://www.conversoriaecnae.es/api/v1/iae/501.3
```

3. (Optional) Sign in to https://www.conversoriaecnae.es/api-dashboard to view usage and rotate keys.

## Authentication

All requests must include:

```
X-API-Key: <your_api_key>
```

Unauthenticated requests are rejected with `401 Unauthorized`. Quota exhaustion returns `429 Too Many Requests` with `Retry-After` header in seconds.

## Rate Limiting and Error Codes

| Code | Meaning | Recovery |
|------|---------|----------|
| 200 | Success | — |
| 400 | Malformed request | Fix body or query |
| 401 | Missing or invalid API key | Set `X-API-Key` |
| 403 | Endpoint requires higher plan | Upgrade at /precios |
| 404 | Code not found | Verify code format (dotted or dotless) |
| 429 | Rate limit or daily quota hit | Honor `Retry-After`; consider upgrading |
| 5xx | Server error | Retry with exponential backoff |

## Data Sources

All data is sourced from official Spanish and European registries. Updates are applied quarterly.

- AEAT — Agencia Estatal de Administración Tributaria — IAE tariffs: https://sede.agenciatributaria.gob.es
- INE — Instituto Nacional de Estadística — CNAE 2025: https://www.ine.es
- BOE — Boletín Oficial del Estado — Real Decreto Legislativo 2/2004 (IAE): https://www.boe.es/buscar/act.php?id=BOE-A-2004-4214
- BOE — Real Decreto 10/2025 (CNAE 2025): https://www.boe.es
- Eurostat — NACE Rev. 2 (European parent classification): https://ec.europa.eu/eurostat/web/nace

## Coverage

- 2 875 total codes: 1 186 IAE epígrafes (full Tarifa AEAT) + 1 060 CNAE 2025 codes (clase level) + 629 CNAE 2009 obsolete codes
- 1 010 CNAE 2009 → CNAE 2025 correspondences (full official mapping)
- 81 IAE codes flagged as eligible for IRPF estimación objetiva (módulos)
- ~1 897 binding DGT (Dirección General de Tributos) rulings indexed
- 8 AEAT tax models with deadlines, casillas, and applicable codes (036, 100, 130, 131, 303, 347, 349, 390)

## Compliance and Legal

- GDPR / RGPD compliant — no PII stored beyond email and hashed IP for rate limiting
- Empresa and Enterprise plans include a 99.9% SLA, a Spanish DPA contract, and an EU data-residency attestation (Supabase eu-central-2) — the baseline banking and regulated-client compliance teams ask for. A Spanish bank already runs this API in production for customer activity classification.
- Billing through Stripe with EU VAT handling
- Terms: https://www.conversoriaecnae.es/terminos-condiciones
- Privacy: https://www.conversoriaecnae.es/politica-privacidad

## Free-Tier Signup Methods

### Via web form

https://www.conversoriaecnae.es/precios#signup-free

### Via curl

```bash
curl -X POST https://www.conversoriaecnae.es/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","name":"Tu Nombre","terms_accepted":true}'
```

The `terms_accepted: true` field is required and signals acceptance of the terms of use; `name` is also required. Plan Gratis is permanent — no automatic upgrades or trial expirations.

## Documentation and Support

- Interactive docs (request/response examples for every endpoint): https://www.conversoriaecnae.es/api/v1/docs
- OpenAPI 3.0 spec (JSON, importable into RapidAPI/Postman): https://www.conversoriaecnae.es/openapi.json
- Pricing page (compare plans side-by-side): https://www.conversoriaecnae.es/precios
- LLM-friendly site index: https://www.conversoriaecnae.es/llms.txt
- Full agent documentation: https://www.conversoriaecnae.es/llms-full.txt
- Email support: brian@conversoriaecnae.es (English or Spanish)
- Response time: business days, EU CET

## Public agent endpoint (unauthenticated)

For AI agents and MCP servers that need lightweight read-only access without a key:

```
POST https://lctcvzapdeljxhjoevvp.supabase.co/functions/v1/conversor-search
Content-Type: application/json

{ "q": "actividades odontológicas", "type": "all", "top_k": 5 }
```

Rate limited to 50 req / 5 min per IP. CORS open. For production workloads, use the keyed `/api/v1/search` endpoint.

## Changelog

- 2025-Q4 — CNAE 2025 catalogue launched; CNAE 2009 endpoints added
- 2026-Q1 — Bulk endpoint, iCalendar feeds for AEAT models
- 2026-Q2 — Hybrid semantic search (Gemini embeddings 768-dim, HNSW cosine)
- 2026-Q2 — B2B activity-profile layer (`/kyb/enrich`, `/onboarding/activity`), Empresa-tier SLA + DPA
- 2026-Q2 — MCP server launched (19 tools: 18 free, 1 premium); DGT, legislación, BORME, and subvenciones datasets added to Profesional

## Official listings

The API is indexed on the following third-party marketplaces (our own canonical profiles — not affiliate links):

- [RapidAPI — conversor-iae-cnae-api](https://rapidapi.com/conversoriaecnae/api/conversor-iae-cnae-api): Browse endpoints, run live test calls and subscribe via the RapidAPI marketplace.
- [Postman — Conversor IAE CNAE Spanish Tax Codes API](https://www.postman.com/conversoriaecnae-7485136/conversor-iae-cnae-spanish-tax-codes-api/collection/l129wqp/conversor-iae-cnae-spanish-tax-codes-api): Import the published Postman v2.1 collection for all endpoints with pre-filled examples.

## Contact

- Email: brian@conversoriaecnae.es
- Data controller: Brian Mena Gómez (Spain)
- Response within 5 business days for sales; within 24 hours for paid-tier support tickets