# Escrita à mão para Excel

Converta tabelas e registros manuscritos em arquivos XLSX editáveis com reconhecimento otimizado para escrita à mão.

Documentação oficial: https://img2excel.net/pt/docs/api/handwriting-to-excel

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

Converta tabelas e registros manuscritos em arquivos XLSX editáveis com reconhecimento otimizado para escrita à mão. O endpoint síncrono aguarda a conclusão. Conversões com falha não consomem créditos.

Use uma imagem nítida, com iluminação uniforme e a tabela inteira visível. Confira nomes, datas e números extraídos antes de usar o arquivo.

## Requisição

### Cabeçalhos

| Cabeçalho | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | Sim | `Bearer $IMG2EXCEL_API_KEY`. Use uma chave de API no servidor. |
| `Content-Type` | Sim | `multipart/form-data` com boundary. Deixe o cliente HTTP definir o cabeçalho ao enviar o arquivo. |
| `Idempotency-Key` | Não | Chave de idempotência de até 200 caracteres. Recomendada em cada envio; reutilize o valor ao repetir o mesmo envio. |

### Corpo

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `file` | Arquivo binário | Sim | Uma imagem PNG, JPG ou JPEG de até 4 MB. |

Envie a imagem como arquivo, não como corpo JSON nem URL. O endpoint seleciona o perfil de reconhecimento automaticamente.

## Exemplos de requisição

Execute os exemplos no servidor com `IMG2EXCEL_API_KEY` definido. Python requer `pip install requests`; Node.js requer a versão 20 ou posterior.


### cURL

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


### Python

```python
import os
import requests

with open("handwritten-log.jpg", "rb") as image:
    response = requests.post(
        "https://img2excel.net/api/v1/handwriting-to-excel",
        headers={
            "Authorization": f"Bearer {os.environ['IMG2EXCEL_API_KEY']}",
            "Idempotency-Key": "handwritten-log-001",
        },
        files={"file": ("handwritten-log.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('handwritten-log.jpg');
const form = new FormData();
form.set('file', new File([file], 'handwritten-log.jpg', { type: 'image/jpeg' }));

const response = await fetch('https://img2excel.net/api/v1/handwriting-to-excel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.IMG2EXCEL_API_KEY}`,
    'Idempotency-Key': 'handwritten-log-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);
```




## Resposta

**200 OK** — conversão concluída. Baixe o Excel por `result.download_url`. A URL do exemplo é ilustrativa.

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "handwriting-to-excel",
  "status": "succeeded",
  "credits_reserved": 2,
  "credits_used": 2,
  "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** — conversão com falha. A resposta inclui o ID da tarefa, `status: "failed"`, `error.code` e `error.message`. Nenhum crédito é consumido.

Se a chave corresponder a uma conversão existente, será retornado `Idempotent-Replayed: true`. Uma tarefa concluída retorna `200`; um resultado expirado, `410`. Se a tarefa estiver na fila ou em execução, a nova tentativa retorna `202` com `Location`. Consulte essa URL sem criar outra conversão.

Veja os campos em [Tarefas e erros](https://img2excel.net/pt/docs/api/jobs). Chamadas síncronas e assíncronas compartilham os registros, limites da conta e chaves de idempotência de cada tipo de conversão.

O endpoint síncrono aguarda a conversão. Configure o tempo limite do cliente HTTP para 330 segundos. Se a conexão expirar, tente novamente com o mesmo `Idempotency-Key`. Uma chave nova inicia outra conversão.

## Conversão assíncrona (opcional)

Use `POST /api/v1/handwriting-to-excel/jobs` para enviar sem esperar. Os campos e a autenticação são os mesmos. Uma nova tarefa retorna `202`, seu ID e `Location`. Consulte `GET /api/v1/jobs/{job_id}` a cada 2–3 segundos até `succeeded`, `failed` ou `expired`. Em caso de sucesso, baixe `result.download_url`. Veja [Tarefas e erros](https://img2excel.net/pt/docs/api/jobs).

---

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