# Tareas y errores

Consulta una tarea, descarga su libro y resuelve los errores de las solicitudes.

Documentación oficial: https://img2excel.net/es/docs/api/jobs

`GET /api/v1/jobs/{job_id}`

Los endpoints síncronos devuelven directamente los resultados terminados. Usa este endpoint para tareas asíncronas, reintentos idempotentes pendientes o renovar una URL mientras se conserva el resultado. Un fallo síncrono devuelve `422` con una tarea; consultar una tarea existente devuelve `200`. Comprueba siempre `status`.

Consulta el estado actual de una conversión. Imagen a Excel y Escritura manuscrita a Excel usan el mismo endpoint.

## Solicitud

| Parámetro | Ubicación | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `job_id` | Ruta | Sí | El `id` recibido al crear la tarea. |
| `Authorization` | Cabecera | Sí | `Bearer $IMG2EXCEL_API_KEY`. La clave debe pertenecer a la cuenta de la tarea. |

```bash
curl --fail-with-body https://img2excel.net/api/v1/jobs/job_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $IMG2EXCEL_API_KEY"
```

Una solicitud válida devuelve **200 OK**, incluso si la conversión falló. Comprueba `status` en el JSON: el éxito HTTP no implica que el libro esté listo.

## Estados de las tareas

| Estado | Significado | Siguiente acción |
| --- | --- | --- |
| `queued` | Carga aceptada, pendiente de ejecución. | Volver a consultar tras 2–3 segundos. |
| `processing` | Conversión en curso. | Volver a consultar tras 2–3 segundos. |
| `succeeded` | Libro listo. | Descargar desde `result.download_url` y dejar de consultar. |
| `failed` | Conversión fallida. | Leer `error.code` y `error.message`; dejar de consultar. |
| `expired` | Terminó el periodo de conservación. | Dejar de consultar. Crear una nueva tarea con otra clave de idempotencia si hace falta. |

## Respuesta

### Conversión correcta

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "image-to-excel",
  "status": "succeeded",
  "credits_reserved": 1,
  "credits_used": 1,
  "created_at": "2026-09-07T12:00:00.000Z",
  "completed_at": "2026-09-07T12:00:18.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
  }
}

```

La URL anterior es ilustrativa. Usa la que devuelva tu tarea.

| Campo | Tipo | Descripción |
| --- | --- | --- |
| `id` | Cadena | Identificador de la tarea. |
| `type` | Cadena | `image-to-excel` o `handwriting-to-excel`. |
| `status` | Cadena | Uno de los cinco estados anteriores. |
| `credits_reserved` | Entero | Créditos necesarios para la conversión. |
| `credits_used` | Entero | Créditos consumidos por la conversión. |
| `created_at` | Cadena | Fecha y hora UTC en formato ISO 8601. |
| `completed_at` | Cadena o null | Fecha y hora de finalización; antes, `null`. |
| `result` | Objeto | Presente cuando la tarea terminó correctamente y hay resultado disponible. |
| `error` | Objeto | Presente al fallar la conversión; incluye `code` y `message`. |

### Campos del resultado

| Campo | Tipo | Descripción |
| --- | --- | --- |
| `filename` | Cadena | Nombre sugerido para el archivo del libro. |
| `content_type` | Cadena | Tipo MIME de XLSX. |
| `size_bytes` | Entero o null | Tamaño del archivo en bytes; `null` si no está disponible. |
| `download_url` | Cadena | URL de descarga firmada y temporal. |
| `download_url_expires_in` | Entero | Validez en segundos: `900` (15 minutos). |

El resultado está disponible 24 horas tras finalizar. Si la URL caduca durante ese periodo, consulta de nuevo la tarea para renovarla. No registres ni publiques las URL firmadas.

### Conversión fallida

El fallo aparece en la respuesta de la tarea, por ejemplo:

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "image-to-excel",
  "status": "failed",
  "credits_reserved": 1,
  "credits_used": 0,
  "created_at": "2026-10-04T09:00:00.000Z",
  "completed_at": "2026-10-04T09:00:18.000Z",
  "error": {
    "code": "CONVERSION_FAILED",
    "message": "The conversion could not be completed."
  }
}
```

Las conversiones fallidas no consumen créditos. Revisa el mensaje antes de reintentar. Una nueva conversión requiere otra clave de idempotencia; reutilizar la anterior devuelve la misma tarea fallida.

## Consultar y descargar

Instala `requests` con `pip install requests`, define `IMG2EXCEL_API_KEY` y sustituye `job_id` por tu ID. El ejemplo realiza hasta 60 consultas. Un error HTTP o de red detiene el script; en producción, trata los fallos temporales según las indicaciones siguientes.

```python
import os
import time
import requests

job_id = "job_0123456789abcdef0123456789abcdef"
headers = {"Authorization": f"Bearer {os.environ['IMG2EXCEL_API_KEY']}"}

for _ in range(60):
    response = requests.get(
        f"https://img2excel.net/api/v1/jobs/{job_id}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    job = response.json()

    if job["status"] == "succeeded":
        xlsx = requests.get(job["result"]["download_url"], timeout=60)
        xlsx.raise_for_status()
        with open(job["result"]["filename"], "wb") as output:
            output.write(xlsx.content)
        break
    if job["status"] in ("failed", "expired"):
        raise RuntimeError(job.get("error", {"code": job["status"]}))

    time.sleep(2)
else:
    raise TimeoutError("IMG2Excel conversion did not finish in time")

```

## Errores de solicitud

Una solicitud HTTP rechazada devuelve un estado distinto de 2xx y un objeto de error:

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "A valid API key is required."
  }
}
```

| Estado HTTP | Código | Causa | Solución |
| --- | --- | --- | --- |
| 400 | `INVALID_REQUEST` | No se puede analizar el cuerpo como formulario multipart. | Usar la carga multipart del cliente HTTP. |
| 400 | `INVALID_FILE` | Falta `file` o no es un archivo. | Adjuntar la imagen en `file`. |
| 400 | `INVALID_IDEMPOTENCY_KEY` | La clave supera los 200 caracteres. | Acortar el valor de la cabecera. |
| 401 | `INVALID_API_KEY` | Clave ausente, inválida, caducada, revocada o sin permisos de conversión. | Revisar Bearer y la clave en [Configuración de API](https://img2excel.net/es/settings/api). |
| 403 | `API_ACCESS_REQUIRED` | La cuenta no tiene acceso a la API. | Comprar el paquete Business o Professional. |
| 404 | `JOB_NOT_FOUND` | La tarea no existe o es de otra cuenta. | Revisar el ID y usar una clave de la cuenta creadora. |
| 409 | `JOB_CONFLICT` | Un conflicto impide crear la tarea. | Reintentar con la clave de idempotencia original. |
| 413 | `FILE_TOO_LARGE` | El archivo supera los 4 MB. | Reducir el tamaño antes de subirlo. |
| 429 | `RATE_LIMITED` | Demasiadas tareas en el último minuto. | Esperar según `Retry-After` y reintentar con la misma clave. |
| 429 | `CONCURRENCY_LIMITED` | Demasiadas tareas en cola o en curso. | Esperar a que termine una antes de enviar otra. |

La falta de créditos o un fallo de reconocimiento pueden ocurrir **después** de aceptar una tarea. Al consultarla, aparecerán `status: "failed"`, `error.code` y `error.message`, sin rechazar necesariamente la carga inicial. Revisa el saldo si el mensaje indica créditos insuficientes.

## Límites y reintentos

| Límite | Valor |
| --- | --- |
| Nuevas tareas por cuenta | 30 por minuto, entre ambos endpoints de conversión |
| Tareas simultáneas en cola o en curso | Business: 3; Professional: 10 |
| Tamaño del archivo | Hasta 4 MB |
| Validez de la URL de descarga | 15 minutos |
| Conservación del resultado | 24 horas tras finalizar correctamente |

Ante `429`, respeta `Retry-After` si está presente. Para fallos temporales `5xx` o de red, aumenta progresivamente la espera y añade un retraso aleatorio. Conserva la clave original al reintentar cargas y el mismo ID al consultar estados. Fija un plazo máximo de consultas en tu aplicación.

No reintentes automáticamente solicitudes inválidas ni errores de autenticación. Corrige primero la solicitud. Si persiste el fallo, contacta con [soporte](mailto:support@img2excel.net) con el ID y código de error, sin clave API ni URL de descarga.

---

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