# Início rápido

Faça sua primeira chamada à API e baixe um arquivo Excel.

Documentação oficial: https://img2excel.net/pt/docs/api/getting-started

A API IMG2Excel converte imagens de tabelas em pastas de trabalho do Excel editáveis. Recomendamos o endpoint síncrono: envie a imagem, aguarde a conversão e baixe o XLSX pela URL retornada. Os endpoints assíncronos continuam disponíveis.

| Parâmetro | Valor |
| --- | --- |
| URL base | `https://img2excel.net` |
| Autenticação | `Authorization: Bearer $IMG2EXCEL_API_KEY` |
| Acesso à API | Pacote de créditos Business ou Professional |
| Entrada | Uma imagem PNG, JPG ou JPEG de até 4 MB |
| Saída | Um arquivo `.xlsx` editável |

## 1. Configure sua chave de API

Copie sua chave nas [configurações da API](https://img2excel.net/pt/settings/api) e salve-a em uma variável de ambiente no servidor:

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

Mantenha a chave em segredo. Não a inclua no código do navegador nem em repositórios públicos.

## 2. Envie uma imagem de tabela

Escolha o endpoint adequado à imagem:

| Imagem | Endpoint |
| --- | --- |
| Tabela impressa, captura de tela ou planilha digitalizada | [Imagem para Excel](https://img2excel.net/pt/docs/api/image-to-excel) |
| Tabela, diário ou registro manuscrito | [Escrita à mão para Excel](https://img2excel.net/pt/docs/api/handwriting-to-excel) |

O exemplo envia uma tabela impressa. Substitua `table.png` pelo caminho da imagem. Para escrita à mão, use `/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"
```

Use um `Idempotency-Key` diferente para cada imagem nova. Reutilize-o apenas ao tentar novamente o mesmo envio.

A requisição síncrona retorna **200 OK** ao concluir, com `result.download_url`. A URL abaixo é um exemplo; use a retornada na sua resposta.

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

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.

## 3. Baixe o arquivo Excel

Copie `result.download_url` da resposta bem-sucedida:

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

A URL de download vale por 15 minutos. O resultado é mantido por 24 horas após a conclusão. Consulte a tarefa novamente nesse período para obter outra URL. Conversões com falha não consomem créditos.

## Conversão assíncrona (opcional)

Para processar em segundo plano, acrescente `/jobs` ao endpoint. Uma tarefa nova retorna `202`, seu ID e o cabeçalho `Location`. Consulte essa URL a cada 2–3 segundos até `succeeded`, `failed` ou `expired`. Veja o script em [Tarefas e erros](https://img2excel.net/pt/docs/api/jobs).

Uma falha na conversão síncrona retorna `422`, `error.code` e `error.message`. Repetir com a mesma chave de idempotência retorna a tarefa original. Se ela estiver em andamento, retorna `202`; consulte a URL `Location`. Um resultado expirado retorna `410`.

## Use um assistente de programação com IA

Selecione **Copiar para IA** acima e cole as instruções no ChatGPT, Claude, Gemini, Cursor ou outro assistente. Informe a linguagem do servidor e se a tabela é impressa ou manuscrita. Cada página de endpoint também oferece a função de cópia e exemplos Python / Node.js.

Consulte a [especificação OpenAPI](https://img2excel.net/api/openapi.json) ou a [documentação completa da API](https://img2excel.net/pt/docs/api/text/llms-full.txt) para a definição completa.

---

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