# Imagen a Excel

Convierte tablas impresas de capturas, documentos escaneados o fotos en libros XLSX editables.

Documentación oficial: https://img2excel.net/es/docs/api/image-to-excel

`POST /api/v1/image-to-excel`

Convierte tablas impresas de capturas, documentos escaneados o fotos en libros XLSX editables. El endpoint síncrono espera a que termine la conversión. Las conversiones fallidas no consumen créditos.

## Solicitud

### Cabeceras

| Cabecera | Obligatoria | Descripción |
| --- | --- | --- |
| `Authorization` | Sí | `Bearer $IMG2EXCEL_API_KEY`. Usa una clave de API en el servidor. |
| `Content-Type` | Sí | `multipart/form-data` con boundary. Deja que el cliente HTTP configure esta cabecera al enviar el archivo. |
| `Idempotency-Key` | No | Clave de idempotencia de hasta 200 caracteres. Recomendada en cada carga; conserva el valor al reintentar la misma carga. |

### Cuerpo

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `file` | Archivo binario | Sí | Una imagen PNG, JPG o JPEG, de hasta 4 MB. |

Envía la imagen como archivo, no como cuerpo JSON ni URL. El endpoint selecciona automáticamente el perfil de reconocimiento.

## Ejemplos de solicitudes

Ejecuta los ejemplos en el servidor con `IMG2EXCEL_API_KEY` definido. Python requiere `pip install requests`; Node.js requiere la versión 20 o posterior.


### cURL

```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: image-to-excel-001" \
  -F "file=@spreadsheet-photo.jpg"
```


### Python

```python
import os
import requests

with open("spreadsheet-photo.jpg", "rb") as image:
    response = requests.post(
        "https://img2excel.net/api/v1/image-to-excel",
        headers={
            "Authorization": f"Bearer {os.environ['IMG2EXCEL_API_KEY']}",
            "Idempotency-Key": "spreadsheet-photo-001",
        },
        files={"file": ("spreadsheet-photo.jpg", image, "image/jpeg")},
        timeout=330,
    )

response.raise_for_status()
job = response.json()
print(job["result"]["download_url"])
```


### Node.js

```ts
import { readFile } from 'node:fs/promises';

const file = await readFile('spreadsheet-photo.jpg');
const form = new FormData();
form.set('file', new File([file], 'spreadsheet-photo.jpg', { type: 'image/jpeg' }));

const response = await fetch('https://img2excel.net/api/v1/image-to-excel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.IMG2EXCEL_API_KEY}`,
    'Idempotency-Key': 'spreadsheet-photo-001',
  },
  body: form,
  signal: AbortSignal.timeout(330_000),
});

if (!response.ok) throw new Error(await response.text());
const job = await response.json();
console.log(job.result.download_url);
```




## Respuesta

**200 OK** — conversión terminada. Descarga el Excel desde `result.download_url`. La URL del ejemplo es ficticia.

```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
  }
}
```

**422 Unprocessable Entity** — conversión fallida. La respuesta incluye el ID de tarea, `status: "failed"`, `error.code` y `error.message`. No se consumen créditos.

Si la clave coincide con una conversión existente, se devuelve `Idempotent-Replayed: true`. Una tarea terminada devuelve `200`; un resultado caducado, `410`. Si la tarea original está en cola o en curso, el reintento devuelve `202` con `Location`. Consulta esa URL sin crear otra conversión.

Consulta los campos en [Tareas y errores](https://img2excel.net/es/docs/api/jobs). Las llamadas síncronas y asíncronas comparten registros, límites de cuenta y claves de idempotencia para cada tipo de conversión.

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.

## Conversión asíncrona (opcional)

Usa `POST /api/v1/image-to-excel/jobs` para enviar sin esperar. Los campos y la autenticación son los mismos. Una nueva tarea devuelve `202`, su ID y `Location`. Consulta `GET /api/v1/jobs/{job_id}` cada 2–3 segundos hasta `succeeded`, `failed` o `expired`. Si termina correctamente, descarga `result.download_url`. Véase [Tareas y errores](https://img2excel.net/es/docs/api/jobs).

---

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