# Tarefas e erros

Consulte uma tarefa, baixe o arquivo e identifique falhas nas requisições.

Documentação oficial: https://img2excel.net/pt/docs/api/jobs

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

Endpoints síncronos retornam resultados concluídos diretamente. Use este endpoint para tarefas assíncronas, novas tentativas idempotentes pendentes ou renovar uma URL durante a retenção. Falhas síncronas retornam `422` com a tarefa; consultas a tarefas existentes retornam `200`. Verifique sempre `status`.

Consulte o estado atual de uma conversão. Imagem para Excel e Escrita à mão para Excel usam o mesmo endpoint.

## Requisição

| Parâmetro | Local | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `job_id` | Caminho | Sim | O `id` retornado ao criar a tarefa. |
| `Authorization` | Cabeçalho | Sim | `Bearer $IMG2EXCEL_API_KEY`. A chave deve pertencer à conta da tarefa. |

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

Uma requisição válida retorna **200 OK**, mesmo se a conversão falhou. Verifique `status` no JSON: sucesso HTTP não significa que o arquivo está pronto.

## Status das tarefas

| Status | Significado | Próxima ação |
| --- | --- | --- |
| `queued` | Envio aceito, aguardando execução. | Consultar novamente em 2–3 segundos. |
| `processing` | Conversão em andamento. | Consultar novamente em 2–3 segundos. |
| `succeeded` | Arquivo pronto. | Baixar por `result.download_url` e parar as consultas. |
| `failed` | Conversão com falha. | Ler `error.code` e `error.message`; parar as consultas. |
| `expired` | Retenção encerrada. | Parar as consultas. Se necessário, criar tarefa com outra chave de idempotência. |

## Resposta

### Conversão bem-sucedida

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

```

A URL acima é ilustrativa. Use a retornada pela sua tarefa.

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `id` | String | Identificador da tarefa. |
| `type` | String | `image-to-excel` ou `handwriting-to-excel`. |
| `status` | String | Um dos cinco estados acima. |
| `credits_reserved` | Inteiro | Créditos necessários à conversão. |
| `credits_used` | Inteiro | Créditos consumidos na conversão. |
| `created_at` | String | Data e hora UTC no formato ISO 8601. |
| `completed_at` | String ou null | Data e hora de conclusão; antes, `null`. |
| `result` | Objeto | Presente se a tarefa foi bem-sucedida e o resultado está disponível. |
| `error` | Objeto | Presente em falhas; contém `code` e `message`. |

### Campos do resultado

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `filename` | String | Nome sugerido para o arquivo Excel. |
| `content_type` | String | Tipo MIME XLSX. |
| `size_bytes` | Inteiro ou null | Tamanho do arquivo em bytes; `null` se indisponível. |
| `download_url` | String | URL de download assinada e temporária. |
| `download_url_expires_in` | Inteiro | Validade em segundos: `900` (15 minutos). |

O resultado permanece disponível por 24 horas após a conclusão. Se a URL expirar nesse período, consulte a tarefa para renová-la. Não registre nem publique URLs assinadas.

### Conversão com falha

A falha é informada na resposta da tarefa, por exemplo:

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

Conversões com falha não consomem créditos. Confira a mensagem antes de tentar novamente. Uma nova conversão requer outra chave de idempotência; a chave anterior retorna a mesma tarefa com falha.

## Consultar e baixar

Instale `requests` com `pip install requests`, defina `IMG2EXCEL_API_KEY` e substitua `job_id` pelo seu ID. O exemplo faz até 60 consultas. Erros de rede ou HTTP interrompem o script; em produção, trate falhas temporárias conforme as orientações abaixo.

```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")

```

## Erros de requisição

Uma requisição HTTP rejeitada retorna status fora de 2xx e um objeto de erro:

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

| Status HTTP | Código | Causa | Solução |
| --- | --- | --- | --- |
| 400 | `INVALID_REQUEST` | Corpo não pode ser lido como formulário multipart. | Usar upload multipart do cliente HTTP. |
| 400 | `INVALID_FILE` | `file` ausente ou não é um arquivo. | Anexar uma imagem em `file`. |
| 400 | `INVALID_IDEMPOTENCY_KEY` | Chave maior que 200 caracteres. | Encurtar o valor do cabeçalho. |
| 401 | `INVALID_API_KEY` | Chave ausente, inválida, expirada, revogada ou sem permissão de conversão. | Verificar Bearer e a chave nas [configurações da API](https://img2excel.net/pt/settings/api). |
| 403 | `API_ACCESS_REQUIRED` | Conta sem acesso à API. | Comprar o pacote Business ou Professional. |
| 404 | `JOB_NOT_FOUND` | Tarefa inexistente ou de outra conta. | Conferir o ID e usar uma chave da conta criadora. |
| 409 | `JOB_CONFLICT` | Um conflito impede criar a tarefa. | Tentar novamente com a chave de idempotência original. |
| 413 | `FILE_TOO_LARGE` | Arquivo maior que 4 MB. | Reduzir o tamanho antes do envio. |
| 429 | `RATE_LIMITED` | Muitas tarefas criadas no último minuto. | Aguardar `Retry-After` e repetir com a mesma chave. |
| 429 | `CONCURRENCY_LIMITED` | Muitas tarefas na fila ou em execução. | Aguardar uma tarefa terminar antes de enviar outra. |

Créditos insuficientes ou falhas de reconhecimento podem ocorrer **após** a tarefa ser aceita. A consulta retorna `status: "failed"`, `error.code` e `error.message`, sem necessariamente rejeitar o envio inicial. Verifique o saldo se a mensagem indicar falta de créditos.

## Limites e novas tentativas

| Limite | Valor |
| --- | --- |
| Novas tarefas por conta | 30 por minuto, somando os dois endpoints de conversão |
| Tarefas simultâneas na fila ou em execução | Business: 3; Professional: 10 |
| Tamanho do arquivo | Até 4 MB |
| Validade da URL de download | 15 minutos |
| Retenção do resultado | 24 horas após conclusão bem-sucedida |

Para `429`, respeite `Retry-After` quando presente. Para falhas temporárias `5xx` ou de rede, aumente gradualmente a espera e acrescente um atraso aleatório. Reutilize a chave original em envios e o mesmo ID em consultas de status. Defina um prazo máximo para as consultas na aplicação.

Não repita automaticamente requisições inválidas ou erros de autenticação. Corrija a requisição primeiro. Se o erro persistir, contate o [suporte](mailto:support@img2excel.net) com o ID e código de erro, sem chave API ou URL de download.

---

OpenAPI 3.1: https://img2excel.net/api/openapi.json
Documentação completa da API: https://img2excel.net/pt/docs/api/text/llms-full.txt