# Inicio rápido

Realiza tu primera llamada a la API y descarga un archivo Excel.

Documentación oficial: https://img2excel.net/es/docs/api/getting-started

La API IMG2Excel convierte imágenes de tablas en libros de Excel editables. Recomendamos el endpoint síncrono: sube una imagen, espera la conversión y descarga el XLSX desde la URL recibida. También se mantienen los endpoints asíncronos.

| Parámetro | Valor |
| --- | --- |
| URL base | `https://img2excel.net` |
| Autenticación | `Authorization: Bearer $IMG2EXCEL_API_KEY` |
| Acceso a la API | Paquete de créditos Business o Professional |
| Entrada | Una imagen PNG, JPG o JPEG, de hasta 4 MB |
| Salida | Un archivo `.xlsx` editable |

## 1. Configura tu clave de API

Copia tu clave desde [Configuración de API](https://img2excel.net/es/settings/api) y guárdala en una variable de entorno del servidor:

```bash
export IMG2EXCEL_API_KEY="your_api_key"
```

Mantén la clave en privado. No la incluyas en código del navegador ni en repositorios públicos.

## 2. Sube una imagen de tabla

Elige el endpoint adecuado para tu imagen:

| Imagen | Endpoint |
| --- | --- |
| Tabla impresa, captura de pantalla u hoja de cálculo escaneada | [Imagen a Excel](https://img2excel.net/es/docs/api/image-to-excel) |
| Tabla, registro o anotación manuscrita | [Escritura manuscrita a Excel](https://img2excel.net/es/docs/api/handwriting-to-excel) |

El ejemplo envía una tabla impresa. Sustituye `table.png` por la ruta de tu imagen. Para escritura manuscrita, usa `/api/v1/handwriting-to-excel`.

```bash
curl --fail-with-body --max-time 330 -i https://img2excel.net/api/v1/image-to-excel \
  -H "Authorization: Bearer $IMG2EXCEL_API_KEY" \
  -H "Idempotency-Key: table-import-001" \
  -F "file=@table.png"
```

Usa un `Idempotency-Key` distinto para cada imagen nueva. Reutilízalo solo para reintentar la misma carga.

La solicitud síncrona devuelve **200 OK** al terminar, con `result.download_url`. La URL siguiente es un ejemplo; utiliza la recibida en tu respuesta.

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "image-to-excel",
  "status": "succeeded",
  "credits_reserved": 1,
  "credits_used": 1,
  "created_at": "2026-10-04T09:00:00.000Z",
  "completed_at": "2026-10-04T09:00:08.000Z",
  "result": {
    "filename": "table_result.xlsx",
    "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "size_bytes": 17330,
    "download_url": "https://signed-storage-url.example/...",
    "download_url_expires_in": 900
  }
}
```

El endpoint síncrono espera a que termine la conversión. Configura un tiempo de espera de 330 segundos en el cliente HTTP. Si la conexión agota el tiempo, reintenta con el mismo `Idempotency-Key`. Una clave nueva inicia otra conversión.

## 3. Descarga el archivo Excel

Copia `result.download_url` de la respuesta correcta:

```bash
curl --fail --location "PASTE_RESULT_DOWNLOAD_URL_HERE" --output table.xlsx
```

La URL de descarga es válida durante 15 minutos. El resultado se conserva 24 horas tras finalizar. Consulta de nuevo la tarea durante ese periodo para obtener otra URL. Las conversiones fallidas no consumen créditos.

## Conversión asíncrona (opcional)

Para procesar en segundo plano, añade `/jobs` al endpoint. Una tarea nueva devuelve `202`, su ID y la cabecera `Location`. Consulta esa URL cada 2–3 segundos hasta `succeeded`, `failed` o `expired`. Encontrarás el script en [Tareas y errores](https://img2excel.net/es/docs/api/jobs).

Una conversión síncrona fallida devuelve `422` con `error.code` y `error.message`. Reintentar con la misma clave de idempotencia devuelve la tarea original. Si sigue en curso, devuelve `202`; consulta la URL `Location`. Un resultado caducado devuelve `410`.

## Usa un asistente de programación con IA

Selecciona **Copiar para IA** arriba y pega las instrucciones en ChatGPT, Claude, Gemini, Cursor u otro asistente. Indica el lenguaje del servidor y si la tabla es impresa o manuscrita. Cada página de endpoint también permite copiar y ofrece ejemplos de Python / Node.js.

Consulta la [especificación OpenAPI](https://img2excel.net/api/openapi.json) o la [documentación completa de la API](https://img2excel.net/es/docs/api/text/llms-full.txt) para conocer el contrato completo.

---

OpenAPI 3.1: https://img2excel.net/api/openapi.json
Documentación completa de la API: https://img2excel.net/es/docs/api/text/llms-full.txt