# Configuración del Entorno — Claves API e Instalación del Cliente

> Cómo instalar un cliente, almacenar de forma segura su clave API de ImageToTable.ai y solucionar los problemas más comunes del tipo «Envié una solicitud y obtuve un error» antes de empezar a usar la API v1.

Esta página es para quienes nunca han llamado a una API HTTP desde un terminal. Si ya se siente cómodo con `curl` y las variables de entorno, vaya directamente a [Inicio Rápido](/developers/quickstart).

## Instalar un cliente

Necesita algo que pueda enviar una solicitud HTTP con encabezados personalizados. Dos opciones comunes:

- **curl** — una herramienta de línea de comandos, normalmente ya instalada en macOS y Linux. Compruébelo con `curl --version` en un terminal. En Windows, instálelo desde [curl.se/windows](https://curl.se/windows/) o use curl incluido con Git Bash / WSL. Todos los ejemplos de esta documentación están escritos primero como comandos curl.
- **Postman** (o Insomnia) — una aplicación gráfica para crear y guardar solicitudes, útil si prefiere hacer clic en un formulario en lugar de escribir comandos de shell. Instálelo desde [postman.com/downloads](https://www.postman.com/downloads/) y luego reproduzca cualquier ejemplo curl de este sitio copiando la URL, el método, los encabezados y el cuerpo en una nueva solicitud.

## Usar los ejemplos de Python

Todos los fragmentos de código de este sitio tienen una pestaña de Python basada en la popular biblioteca [`requests`](https://requests.readthedocs.io/) — **no es un SDK oficial de ImageToTable.ai** (no publicamos ninguno; son llamadas HTTP simples con cualquier cliente estándar). Necesita:

- **Python 3.8+** — compruébelo con `python3 --version`. Obténgalo desde [python.org/downloads](https://www.python.org/downloads/) si no lo tiene.
- **`requests`** — no forma parte de la biblioteca estándar, instálelo primero:`pip install requests`(o `pip3 install requests`, según su sistema).

Los ejemplos de exportación que analizan el archivo descargado (xlsx/docx) también usan `openpyxl` / `python-docx` — solo son necesarios si sigue esos ejemplos específicos, instálelos con `pip install openpyxl python-docx`.

## Uso de los ejemplos en JavaScript

La pestaña de JavaScript usa la API nativa `fetch` — no necesita instalar ninguna biblioteca — pero asume un entorno de ejecución razonablemente actualizado:

- **Node.js 20+** si se ejecuta del lado del servidor — verifique con `node --version`. Los ejemplos usan `await` de nivel superior y `crypto.randomUUID()` global, ambos requieren un Node reciente; en Node 18 (ahora al final de su vida útil) `crypto` no es confiablemente global fuera de CommonJS/REPL y estos ejemplos pueden fallar con un confuso error `crypto is not defined` que no tiene nada que ver con su clave API. Obtenga una versión actualizada desde [nodejs.org](https://nodejs.org/).
- O simplemente **pegue el fragmento en la consola DevTools de un navegador** — todos los navegadores modernos admiten las mismas API (`fetch`, `FormData`, `crypto.randomUUID()`) de forma nativa, sin necesidad de instalar nada.

## Obtenga su clave API

Su clave API se emite desde la [página de configuración del perfil](/profile/) de su cuenta. La API v1 está disponible para planes de pago (Basic y superiores); si la usa con una clave del plan Free, devuelve un error `plan_required` en lugar de un error de autenticación faltante, ya que la clave en sí es válida — simplemente aún no tiene permiso para usar v1.

## Almacene su clave como variable de entorno

No pegue su clave directamente en un comando que pueda compartir, capturar en pantalla o enviar al control de versiones. Expórtela a su sesión de shell y luego refiérase a ella como `$API_KEY` en cada solicitud — todos los ejemplos de este sitio asumen que esta variable existe:

```bash
export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Esto solo dura para la sesión de terminal actual. Para algo más permanente, agregue la misma línea al archivo de inicio de su shell (`~/.bashrc`, `~/.zshrc` o equivalente) — o, si está escribiendo un script, cárguela desde un archivo `.env` / gestor de secretos en lugar de codificarla directamente en el código fuente.

## Enviar una solicitud de prueba

Confirme que su clave y configuración funcionan antes de pasar a documentos reales:

```bash
curl https://imagetotable.ai/api/v1/account \
  -H "Authorization: Bearer $API_KEY"
```

Una clave activa en un plan de pago devuelve una instantánea de su cuenta (plan, rol, créditos disponibles). Si no es así, consulte la lista de verificación de solución de problemas a continuación.

## Lista de verificación de solución de problemas

Cada error de v1 se devuelve como JSON con un `type`/`code`/`message`; consulte la guía completa de [Manejo de Errores](/developers/guides/errors) para la lista completa. Las comprobaciones iniciales más rápidas para una solicitud que no funciona son:

- **¿Obtiene `missing_api_key`?** Verifique que el encabezado sea exactamente `Authorization: Bearer <key>` — la palabra `Bearer`, un solo espacio y luego la clave. Un espacio faltante o un carácter de comilla extraviado en `$API_KEY` producen esto.
- **¿Obtiene `invalid_api_key`?** La clave no coincide con ninguna cuenta, o la cuenta está deshabilitada. Vuelva a copiarla desde su página de perfil: las claves son largas y es fácil truncarlas al copiar y pegar.
- **¿Obtiene `plan_required`?** Su clave es válida, pero su cuenta está en el plan Free. Actualice al plan Basic o superior para usar v1.
- **¿Obtiene un error de conexión, no una respuesta JSON?** Verifique que la URL comience con `https://imagetotable.ai/api/v1/` y que esté usando `-X POST` (o el verbo correcto) para los endpoints que lo requieran: una solicitud GET a un endpoint solo POST no llegará a la ruta en absoluto.
- **¿Sube un archivo y obtiene un error inesperado?** Las cargas de archivos multiparte necesitan `-F "file=@/ruta/al/archivo.jpg"` (la bandera de carga de formulario de curl), no `-d` ni un cuerpo JSON sin procesar: confundirlos es el error de carga más común. La `@` inicial le indica a curl que lea esa ruta como un archivo real *en su propia máquina*; no es una URL, y el archivo ya debe existir allí antes de ejecutar el comando. Si no tiene un archivo local a mano, omita esto por completo: pase un campo `url` en lugar de `file` y el servidor lo obtendrá por usted; consulte [Inicio Rápido](/developers/quickstart).
- **¿Obtiene `rate_limit_exceeded`?** Consulte [Límites de Velocidad](/developers/guides/rate-limits); los límites son por cuenta, no por tipo de solicitud que usted espera, por lo que una ráfaga de llamadas de sondeo puede alcanzar el mismo límite que una ráfaga de cargas.

---

Source: https://imagetotable.ai/es/developers/environment-setup