Referência

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.

Campos obrigatórios

Só nomeComercial é obrigatório.

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:

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": "[email protected]",                     // opcional
  "telefone": "11999999999"                                // opcional
}

Resposta:

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

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

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.

PUT /v2/cliente/idws
{
  "codigoDoCliente": 4821,
  "idws": "erp-cliente-4821"
}

Consulta por idws

Use GET /v2/cliente?idws=erp-cliente-4821 para buscar o cliente pelo identificador externo, sem precisar guardar o código interno do Gestio.

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:

POST /v2/clientecontato
{
  "codigoDoCliente": 4821,   // obrigatório
  "nome": "Maria Souza",     // obrigatório
  "email": "[email protected]",
  "telefone": "11988887777",
  "cargo": "Financeiro"
}

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.

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.

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

Introdução

Autenticação

Cadastro

Compras

Estoque

Financeiro

Vendas

Utilitários

Criar um Cliente

Campos obrigatórios

Identificador externo (`idws`)

Consulta por idws

Categorias, tipos e contatos

Listagem e limites

​Criar um Cliente

Campos obrigatórios

​Identificador externo (idws)

Consulta por idws

​Categorias, tipos e contatos

​Listagem e limites

Criar um Cliente

Identificador externo (`idws`)

Categorias, tipos e contatos

Listagem e limites