> ## 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.

# Referência

> Clientes, fornecedores, produtos e demais cadastros base do sistema

O módulo de Cadastro reúne as entidades usadas pelos demais módulos: Clientes, Fornecedores, Produtos, Centros de Custo e tabelas de apoio (categorias, tipos, formas e condições de pagamento, unidades de medida). O fluxo mais comum é cadastrar um **Cliente** antes de gerar lançamentos financeiros ou notas fiscais para ele.

## Criar um Cliente

Use `POST /v2/cliente`.

<Card title="Campos obrigatórios" horizontal>
  Só `nomeComercial` é obrigatório.
</Card>

O campo **`natureza`** define o tipo de pessoa:

| Valor | Descrição |
| - | - |
| `J` | Pessoa Jurídica (padrão). Quando informado, `cnpj` é validado quanto ao formato. |
| `F` | Pessoa Física. Quando informado, `cpf` é validado quanto ao formato. |

**Exemplo:**

```json theme={null}
POST /v2/cliente
{
  "nomeComercial": "João Silva Materiais de Construção",  // obrigatório
  "natureza": "J",                                         // opcional - padrão "J"
  "cnpj": "12345678000199",                                // opcional
  "seuCodigo": "CLI-0042",                                 // opcional - código externo
  "codigoDoTipoDeCliente": 1,                              // opcional
  "codigoDoVendedor": 12,                                  // opcional
  "email": "contato@joaosilva.com.br",                     // opcional
  "telefone": "11999999999"                                // opcional
}
```

**Resposta:**

```json theme={null}
{
  "success": true,
  "data": {
    "codigoDoCliente": 4821,
    "nomeComercial": "João Silva Materiais de Construção",
    "natureza": "J",
    "cnpj": "12345678000199",
    "cnpjcpf": "12345678000199",
    "seuCodigo": "CLI-0042",
    "ativo": true
  }
}
```

<Tip>
  Campos obrigatórios ausentes ou inválidos retornam `400` com o detalhe em `notifications`/`errors`.
</Tip>

## Identificador externo (`idws`)

Além do `codigoDoCliente` interno, cada cliente pode ter um `idws` (IdClienteWS) — um identificador estável vindo do seu sistema de origem. Ele é atualizado via `PUT /v2/cliente/idws` e permite localizar o cliente sem depender do código interno do Gestio.

```json theme={null}
PUT /v2/cliente/idws
{
  "codigoDoCliente": 4821,
  "idws": "erp-cliente-4821"
}
```

<Card title="Consulta por idws" horizontal>
  Use `GET /v2/cliente?idws=erp-cliente-4821` para buscar o cliente pelo identificador externo, sem precisar guardar o código interno do Gestio.
</Card>

## Categorias, tipos e contatos

Antes de classificar um cliente, cadastre (ou consulte) as tabelas de apoio:

* **Categoria de Cliente** (`/v2/categoriacliente`) e **Tipo de Cliente** (`/v2/tipocliente`) — usados para segmentar a base de clientes.
* **Contato do Cliente** (`/v2/clientecontato`) — pessoas de contato vinculadas a um cliente, com nome, e-mail e telefone próprios.

**Exemplo — vincular um contato ao cliente:**

```json theme={null}
POST /v2/clientecontato
{
  "codigoDoCliente": 4821,   // obrigatório
  "nome": "Maria Souza",     // obrigatório
  "email": "maria@joaosilva.com.br",
  "telefone": "11988887777",
  "cargo": "Financeiro"
}
```

<Note>
  O mesmo padrão de cadastro (código obrigatório mínimo + demais campos opcionais) se repete em **Fornecedor**, **Produto** e **Centro de Custo** — os outros grandes cadastros deste módulo.
</Note>

## Listagem e limites

`GET /v2/cliente` sem filtro retorna a lista completa de clientes atualizados no período informado por `dataInferior`/`dataSuperior`, limitada a 500 registros por chamada.

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