# Conversor IAE/CNAE API — Pricing and Capabilities

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, ERPs, and legal-tech platforms that need verified classification data without scraping AEAT or INE. Plan Desarrollador 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 |
|------|-------|-------------|-------------|----------|----------|
| Desarrollador | 0 EUR | 250 req/day | 10 req/min | Prototypes, side projects, evaluation | https://www.conversoriaecnae.es/api-precios#signup |
| Profesional | 29 EUR/month | 2 000 req/day | 30 req/min | Gestorías, fintech onboarding, ERP integrations in production | https://www.conversoriaecnae.es/api-precios |
| Empresa | 79 EUR/month | 10 000 req/day | 100 req/min | SaaS multi-tenant, high-volume directories | https://www.conversoriaecnae.es/api-precios |
| Enterprise | Custom | Unlimited | Negotiated | SLA 99.9%, dedicated support, custom DPA | mailto:brian@conversoriaecnae.es |

All paid plans include CNAE 2009 → CNAE 2025 correspondence, bulk endpoint, and priority email support. Billed monthly via Stripe. EU VAT handled by Stripe Tax.

## Endpoints

### Detail endpoints

| Method | Path | Description | Min tier |
|--------|------|-------------|----------|
| GET | `/iae/{code}` | Full IAE epígrafe: title, description, associated CNAE, related IAE, módulos eligibility | Desarrollador |
| GET | `/cnae/{code}` | Full CNAE 2025 code: title, description, associated IAE, category, sector | Desarrollador |
| 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.

### 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) | Desarrollador |

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":[{"type":"iae","code":"501.3"}, ...]}` | 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) | Desarrollador |

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

### Account

| Method | Path | Description | Min tier |
|--------|------|-------------|----------|
| POST | `/signup` | Create free API key; body: `{"email":"...", "consent":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","consent":true}'
```

Response includes your API key. Save it; it is shown only once.

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 /api-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

- 1 187 IAE epígrafes (full Tarifa AEAT)
- 1 060 CNAE 2025 codes (clase level)
- 1 010 CNAE 2009 → CNAE 2025 correspondences (full official mapping)
- 81 IAE codes flagged as eligible for IRPF estimación objetiva (módulos)
- 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
- Spanish DPA template available for Empresa and Enterprise plans
- 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/api-precios#signup

### Via curl

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

The `consent: true` field is required and signals acceptance of the privacy policy. Plan Desarrollador 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
- Pricing page (compare plans side-by-side): https://www.conversoriaecnae.es/api-precios
- LLM-friendly site index: https://www.conversoriaecnae.es/llms.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)

## 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