# Configuração do Ambiente — Chaves de API e Instalação do Cliente

> Como instalar um cliente, armazenar sua chave de API do ImageToTable.ai com segurança e solucionar os problemas mais comuns do tipo "Enviei uma requisição e obtive um erro" antes de começar a usar a API v1.

Esta página é para quem nunca chamou uma API HTTP pelo terminal antes. Se você já se sente confortável com `curl` e variáveis de ambiente, vá direto para o [Início Rápido](/developers/quickstart).

## Instalar um cliente

Você precisa de algo que consiga enviar uma requisição HTTP com cabeçalhos personalizados. Duas opções comuns:

- **curl** — uma ferramenta de linha de comando, geralmente já instalada no macOS e Linux. Verifique com `curl --version` no terminal. No Windows, instale via [curl.se/windows](https://curl.se/windows/) ou use o curl que vem com o Git Bash / WSL. Todos os exemplos nesta documentação são escritos primeiro como comandos curl.
- **Postman** (ou Insomnia) — um aplicativo gráfico para criar e salvar requisições, útil se você prefere clicar em um formulário a escrever comandos de shell. Instale-o em [postman.com/downloads](https://www.postman.com/downloads/) e, em seguida, recrie qualquer exemplo de curl deste site copiando a URL, o método, os cabeçalhos e o corpo em uma nova requisição.

## Usando os exemplos em Python

Todos os exemplos de código neste site têm uma aba Python baseada na popular biblioteca [`requests`](https://requests.readthedocs.io/) — **não é um SDK oficial do ImageToTable.ai** (não publicamos um; estas são chamadas HTTP simples com qualquer cliente padrão). Você precisa de:

- **Python 3.8+** — verifique com `python3 --version`. Obtenha-o em [python.org/downloads](https://www.python.org/downloads/) se estiver faltando.
- **`requests`** — não faz parte da biblioteca padrão, instale-o primeiro:`pip install requests`(ou `pip3 install requests`, dependendo do seu sistema).

Os exemplos de exportação que analisam o arquivo baixado (xlsx/docx) também usam `openpyxl` / `python-docx` — só são necessários se você estiver seguindo esses exemplos específicos; instale com `pip install openpyxl python-docx`.

## Usando os exemplos em JavaScript

A aba JavaScript usa a API nativa `fetch` — nenhuma biblioteca para instalar — mas assume um ambiente de execução razoavelmente atual:

- **Node.js 20+** se estiver executando no lado do servidor — verifique com `node --version`. Os exemplos usam `await` de nível superior e o `crypto.randomUUID()` global, ambos exigindo um Node recente; no Node 18 (agora sem suporte), `crypto` não é confiavelmente global fora do CommonJS/REPL e esses exemplos podem falhar com um erro confuso `crypto is not defined` que não tem nada a ver com sua chave de API. Obtenha uma versão atual em [nodejs.org](https://nodejs.org/).
- Ou simplesmente **cole o trecho no console DevTools de um navegador** — todo navegador moderno suporta as mesmas APIs (`fetch`, `FormData`, `crypto.randomUUID()`) nativamente, sem necessidade de instalação.

## Obtenha sua chave de API

Sua chave de API é emitida na [página de configurações do perfil](/profile/) da sua conta. A API v1 está disponível para planos pagos (Basic e acima); chamá-la com uma chave do plano Free retorna um erro `plan_required` em vez de um erro de autenticação ausente, pois a chave em si é válida — ela só não tem permissão para usar a v1 ainda.

## Armazene sua chave como uma variável de ambiente

Não cole sua chave diretamente em um comando que você possa compartilhar, capturar de tela ou enviar para o controle de versão. Exporte-a para sua sessão do shell e faça referência a ela como `$API_KEY` em cada requisição — todo exemplo neste site assume que essa variável existe:

```bash
export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Isso dura apenas para a sessão atual do terminal. Para algo mais permanente, adicione a mesma linha ao arquivo de inicialização do seu shell (`~/.bashrc`, `~/.zshrc` ou equivalente) — ou, se estiver escrevendo um script, carregue-a de um arquivo `.env` / gerenciador de segredos em vez de codificá-la diretamente no código-fonte.

## Enviar uma solicitação de teste

Confirme sua chave e configuração antes de passar para documentos reais:

```bash
curl https://imagetotable.ai/api/v1/account \
  -H "Authorization: Bearer $API_KEY"
```

Uma chave funcional em um plano pago retorna um resumo da sua conta (plano, função, créditos disponíveis). Qualquer outra coisa, veja a lista de verificação de solução de problemas abaixo.

## Lista de verificação de solução de problemas

Todo erro da v1 retorna como JSON com `type`/`code`/`message` — consulte o guia completo de [Tratamento de Erros](/developers/guides/errors) para a lista completa. As verificações mais rápidas para uma solicitação que não está funcionando:

- **Recebendo `missing_api_key`?** Verifique se o cabeçalho está exatamente `Authorization: Bearer <key>` — a palavra `Bearer`, um espaço simples e a chave. Um espaço faltando ou um caractere de aspas extra em `$API_KEY` produzem isso.
- **Recebendo `invalid_api_key`?** A chave não corresponde a nenhuma conta, ou a conta está desabilitada. Copie-a novamente da sua página de perfil — as chaves são longas e fáceis de truncar ao copiar e colar.
- **Recebendo `plan_required`?** Sua chave é válida, mas sua conta está no plano Free. Faça upgrade para o plano Basic ou superior para usar a v1.
- **Recebendo um erro de conexão, não uma resposta JSON?** Verifique novamente se a URL começa com `https://imagetotable.ai/api/v1/` e se você está usando `-X POST` (ou o verbo correto) para endpoints que exigem isso — uma solicitação GET para um endpoint somente POST não alcançará a rota.
- **Enviando um arquivo e recebendo um erro inesperado?** Uploads de arquivos multipart precisam de `-F "file=@/caminho/para/arquivo.jpg"` (a flag de upload de formulário do curl), não `-d` ou um corpo JSON bruto — misturar esses é o erro de upload mais comum. O `@` inicial diz ao curl para ler aquele caminho como um arquivo real *na sua própria máquina* — não é uma URL, e o arquivo já precisa existir lá antes de você executar o comando. Se você não tiver um arquivo local disponível, pule isso completamente: passe um campo `url` em vez de `file` e o servidor o buscará para você — veja [Quickstart](/developers/quickstart).
- **Recebendo `rate_limit_exceeded`?** Veja [Limites de Taxa](/developers/guides/rate-limits) — os limites são por conta, não por tipo de solicitação que você espera, então uma rajada de chamadas de polling pode acionar o mesmo limite que uma rajada de uploads.

---

Source: https://imagetotable.ai/pt/developers/environment-setup