Tu Primera Llamada a la API Conversor IAE CNAE en 5 Minutos: Guía de Inicio Rápido

¡Bienvenido a bordo! Estamos encantados de tenerte. Esta guía está diseñada para ayudarte a realizar tu primera llamada exitosa a la API y empezar a construir lo antes posible. En menos de 5 minutos, pasarás de tener una idea a obtener datos reales y valiosos.

El objetivo de esta guía: Realizar una conversión de un código IAE a su correspondiente CNAE usando tu clave de API personal.

Prerrequisitos:

Tener una cuenta en API Conversor IAE CNAE (el plan gratuito es perfecto para empezar)
Conocimientos básicos sobre cómo funciona una API REST

Paso 1: Obtén tu Clave de API (API Key)

La clave de API es tu llave de acceso personal y segura a nuestros servicios. Así es como la API sabe quién eres y verifica que tienes permiso para hacer una solicitud.

1. Inicia sesión en tu cuenta.

2. Navega en tu Dashboard a la sección "API Keys".

3. Haz clic en "Generar nueva clave". Dale un nombre descriptivo (por ejemplo, "Mi Primer Proyecto").

4. Copia tu clave de API y guárdala en un lugar seguro.

Nota de Seguridad: Trata tu clave de API como si fuera una contraseña. No la compartas públicamente ni la incluyas directamente en el código del frontend.

Paso 2: Realiza tu Primera Llamada (con cURL)

La forma más rápida de probar que todo funciona es usar cURL desde tu terminal. Es una herramienta universal y no requiere configuración.

Abre tu terminal, copia el siguiente comando, reemplaza TU_API_KEY con la clave que acabas de generar y presiona Enter.

curl -X POST "https://api.conversoriaecnae.es/api/convert-iae-to-cnae" \
-H "Content-Type: application/json" \
-H "X-API-Key: TU_API_KEY" \
-d '{
"codigo_iae": "111.1"
}'

¿Qué hace este comando?

-X POST: Especifica que estamos haciendo una solicitud POST.
"https://api.conversoriaecnae.es/api/convert-iae-to-cnae": Es el endpoint para la conversión de IAE a CNAE.
-H "Content-Type: application/json": Le dice a la API que estamos enviando datos en formato JSON.
-H "X-API-Key: TU_API_KEY": Aquí es donde te autenticas.
-d '{...}': Es el cuerpo (payload) de nuestra solicitud, con el código IAE que queremos convertir.

Respuesta Exitosa:

Si todo ha ido bien, recibirás una respuesta JSON como esta:

[
{
"codigo_cnae_asociado": [
"05.10"
]
}
]

¡Felicidades! Acabas de realizar tu primera conversión exitosa.

Paso 3: Intégralo en tu Código (Ejemplo en Python)

Ahora, vamos a hacer algo más práctico. Aquí tienes un ejemplo de cómo integrar esta llamada en un script de Python usando la popular librería requests.

import requestsrt json

# --- Configuration ---
# It's recommended to load API keys from environment variables for security.
# For example: import os; API_KEY = os.getenv("CONVERSORIA_API_KEY", "YOUR_DEFAULT_API_KEY")
# Replace "YOUR_API_KEY" with your actual key.
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.conversoriaecnae.es/api"

# --- API Endpoints ---
# Define endpoints as constants for clarity and easier modification.
CONVERT_IAE_TO_CNAE_ENDPOINT = "/convert-iae-to-cnae"

def convert_iae_to_cnae(iae_code: str) -> dict:
"""
Converts an IAE code to its corresponding CNAE codes using the Conversoria API.

Args:
iae_code: The IAE code to convert (e.g., "843.1").

Returns:
A dictionary containing the API response data, or an error message.
"""
url = f"{BASE_URL}{CONVERT_IAE_TO_CNAE_ENDPOINT}"

headers = {
"X-API-Key": API_KEY,
"Content-Type": "application/json"
}

payload = {
"codigo_iae": iae_code
}

try:
response = requests.post(url, headers=headers, data=json.dumps(payload))
response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)

result = response.json()
if result.get("success"):
return {"success": True, "data": result["data"]}
else:
return {"success": False, "error": result.get("error", "Unknown API error")}

except requests.exceptions.HTTPError as http_err:
print(f"HTTP Error: {http_err}")
print(f"Response body: {response.text}")
return {"success": False, "error": f"HTTP Error: {http_err}", "response_body": response.text}
except requests.exceptions.ConnectionError as conn_err:
print(f"Connection Error: {conn_err}")
return {"success": False, "error": f"Connection Error: {conn_err}"}
except requests.exceptions.Timeout as timeout_err:
print(f"Timeout Error: {timeout_err}")
return {"success": False, "error": f"Timeout Error: {timeout_err}"}
except requests.exceptions.RequestException as req_err:
print(f"An unexpected request error occurred: {req_err}")
return {"success": False, "error": f"An unexpected request error occurred: {req_err}"}
except json.JSONDecodeError as json_err:
print(f"JSON Decode Error: Could not parse response. {json_err}")
print(f"Raw response: {response.text}")
return {"success": False, "error": f"JSON Decode Error: {json_err}", "raw_response": response.text}
except Exception as err:
print(f"An unexpected error occurred: {err}")
return {"success": False, "error": f"An unexpected error occurred: {err}"}

# --- Example Usage ---
if __name__ == "__main__":
# Example IAE code: "843.1" for cleaning services
iae_to_convert = "843.1"
conversion_result = convert_iae_to_cnae(iae_to_convert)

if conversion_result["success"]:
print(f"Conversion successful for IAE {iae_to_convert}:")
print("Corresponding CNAE codes:", conversion_result["data"])
else:
print(f"Conversion failed for IAE {iae_to_convert}: {conversion_result['error']}")
if "response_body" in conversion_result:
print(f"API Response Body: {conversion_result['response_body']}")
elif "raw_response" in conversion_result:
print(f"Raw API Response: {conversion_result['raw_response']}")

print("\n--- Another Example (Invalid IAE) ---")
iae_invalid = "123.X" # An example of an invalid IAE code
conversion_result_invalid = convert_iae_to_cnae(iae_invalid)

if conversion_result_invalid["success"]:
print(f"Conversion successful for IAE {iae_invalid}:")
print("Corresponding CNAE codes:", conversion_result_invalid["data"])
else:
print(f"Conversion failed for IAE {iae_invalid}: {conversion_result_invalid['error']}")
if "response_body" in conversion_result_invalid:
print(f"API Response Body: {conversion_result_invalid['response_body']}")
elif "raw_response" in conversion_result_invalid:
print(f"Raw API Response: {conversion_result_invalid['raw_response']}")

Ejecuta este script y verás un resultado similar en tu consola, demostrando lo fácil que es integrar la lógica de conversión en tus aplicaciones.

¿Y ahora qué? Próximos Pasos

Ya has dominado lo básico. Aquí tienes algunas ideas para seguir explorando:

1. Prueba otras conversiones:

Convierte de CNAE a IAE usando el endpoint /api/convert-cnae-to-iae.
Obtén los detalles completos de un código con /api/cnae-2025-details o /api/iae-details.

2. Explora la Documentación Completa: