> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gestio.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> Base URL, autenticação, formato de resposta, códigos de status e limites da API de Clientes.

## Base URL

A API de Integração Gestio disponibiliza dois ambientes:

| Ambiente | Base URL | Uso |
| - | - | - |
| Produção | `https://api.gestio.com.br` | Dados reais dos seus clientes |
| Desenvolvimento | `https://devapi.gestio.com.br` | Testes e homologação da integração |

Os endpoints de Cliente descritos nesta referência estão disponíveis sob o prefixo `/v2`, por exemplo `/v2/cliente`.

<Tip>
  Utilize o ambiente de **desenvolvimento** (`https://devapi.gestio.com.br`) durante a implementação e testes da sua integração para evitar impacto nos dados de produção. No playground desta documentação, é possível alternar entre os ambientes pelo seletor de servidor.
</Tip>

<Warning>
  Os ambientes de produção e desenvolvimento são independentes: credenciais, tokens e dados não são compartilhados entre eles. Gere um usuário de integração específico para cada ambiente.
</Warning>

***

## Autenticação

Toda requisição (exceto a de autenticação) deve incluir o token de acesso no header `Authorization`:

```bash theme={null}
Authorization: Bearer SEU_TOKEN_DE_ACESSO
```

<Card title="Gere um token em /v2/autenticar" icon="key" horizontal>
  Envie `email` e `password` do usuário de integração cadastrado no Gestio para receber o `accessToken`.
</Card>

<Note>
  A rota `/v2/autenticar` sempre responde com HTTP `200`, mesmo quando `email`/`password` estão incorretos. Verifique o campo `authenticated` no corpo da resposta para saber se a autenticação foi bem-sucedida.
</Note>

<Tip>
  Tokens expiram após um período determinado. Se receber `401` em qualquer rota de Cliente, gere um novo token antes de repetir a chamada.
</Tip>

<Warning>
  Nunca exponha `email`/`password` de integração em código client-side (frontend, apps mobile). A autenticação deve ser feita apenas pelo seu backend.
</Warning>

***

## Formato de resposta

Os endpoints de Cliente retornam JSON com um envelope simples baseado no campo `success`:

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

Em endpoints de listagem sem filtro de registro único (como `GET /v2/cliente` sem `cnpjcpf`/`idws`), `data` é um array de clientes. Quando um filtro de registro único é informado, `data` é um único objeto (ou `null`, se nada for encontrado).

Em caso de erro de validação ou de regra de negócio (HTTP `400`), o envelope muda de formato:

```json theme={null}
{
  "success": false,
  "errors": [
    {
      "key": "cnpjcpf",
      "value": "CNPJ/CPF já cadastrado para outro cliente.",
      "dateOccurred": "2026-07-29T14:32:10"
    }
  ]
}
```

<Info>
  Sempre verifique `success` antes de acessar `data`. Em respostas de erro, use o array `errors` para identificar o campo (`key`) e a mensagem (`value`) de cada notificação.
</Info>

***

## Códigos de status HTTP

| Código | Significado |
| - | - |
| `200` | Sucesso — verifique `success` no corpo, pois alguns endpoints (como a autenticação) sempre retornam `200` |
| `400` | Requisição inválida — body não informado ou falha de validação de negócio |
| `401` | Não autenticado — token ausente, inválido ou expirado |
| `404` | Recurso não encontrado — por exemplo, código de cliente inexistente |
| `5xx` | Erro interno — tente novamente com backoff exponencial |

***

## Limites

Consultas de listagem (`GET /v2/cliente` sem `cnpjcpf`/`idws`) são limitadas a 500 registros por chamada. Use os parâmetros `dataInferior`/`dataSuperior` para filtrar por período de atualização e paginar a consulta manualmente.

<Tip>
  Use `dataInferior`/`dataSuperior` para limitar a janela consultada. Sem filtro, a resposta pode ser volumosa.
</Tip>

***

## Precisa de ajuda?

<CardGroup cols={2}>
  <Card title="Portal de sugestões" icon="lightbulb" href="https://sugestoes.gestio.com.br/">
    Sugira melhorias e novos recursos para a API.
  </Card>

  <Card title="Suporte" icon="headphones" href="https://ajuda.gestio.com.br/hc/pt-br/requests/new">
    Abra um chamado com nossa equipe de suporte.
  </Card>
</CardGroup>