# Guia: consultar clientes

Como localizar um cliente pelo nome e obter os dados completos dele. É também o primeiro passo para criar um orçamento.

Pré-requisitos: `userHash` e `Servidor` ([Autenticação](../autenticacao.md)).

## 1. Sequência

1. Buscar o cliente pelo nome com `ObterLista`, tipo `16`. A resposta traz código e nome.
2. Se vier mais de um cliente parecido, **pergunte ao usuário qual é**. Não escolha o primeiro.
3. Com o código, obter os dados completos (endereço, documento, contatos) com `AcoesDocumentoVendaMarmoraria`, ação `44`.

## 2. Buscar pelo nome: ObterLista, tipo 16

Neste método o `userHash` vai na **query string** e o filtro vai no corpo:

```
POST {Servidor}/API/ObterLista?userHash={userHash}
Content-Type: application/json
```

```json
{
  "Tipo": [16],
  "Search": "maria souza"
}
```

`Search` aceita parte do nome, nome fantasia, razão social, telefone ou CNPJ. Use pelo menos 3 caracteres e remova aspas do texto.

Resposta (valores fictícios). É **sempre uma lista**, com um bloco por tipo pedido:

```json
[
  {
    "Erro": "",
    "Tipo": [16],
    "Dados": [
      { "Codigo": 1523, "Descricao": "MARIA DE SOUZA" },
      { "Codigo": 2077, "Descricao": "MARIA DE SOUZA LIMA" }
    ]
  }
]
```

Verifique `Erro` no primeiro bloco e use `Dados`. `Codigo` é o código do cliente no GransoftWeb.

### Outras listas de apoio do mesmo método

| `Tipo` | Lista | Precisa de `Search` |
|---|---|---|
| `1` | Condições (planos) de pagamento | Não |
| `3` | Produtos de revenda | Não |
| `5` | Produtos de produção (tipos de peça: pia, bancada…) | Não |
| `6` | Serviços | Não |
| `7` | Acabamentos (beneficiamento) | Não |
| `8` | Tabelas de preço | Não |
| `9` | Vendedores | Não |
| `11` | Prazos de entrega | Não |
| `14` | Filiais | Não |
| `16` | Clientes | Sim: texto procurado |
| `18` | Materiais (pedras) | Sim: `"1"` |

Todas devolvem `Dados` com `Codigo` e `Descricao`.

## 3. Dados completos: ação 44

```
POST {Servidor}/API/AcoesDocumentoVendaMarmoraria
Content-Type: application/json
```

```json
{
  "Acao": 44,
  "userHash": "aEJ6cG1oUjllOExOMXB2ay91TE5U...",
  "DadosCliente": { "Codigo": 1523 }
}
```

Resposta (resumida, valores fictícios):

```json
{
  "Erro": "",
  "DadosCliente": {
    "Codigo": 1523,
    "Nome": "MARIA DE SOUZA",
    "Rua": "RUA DAS ACÁCIAS",
    "Numero": "120",
    "EndCompl": "",
    "Bairro": "CENTRO",
    "Cidade": "BELO HORIZONTE",
    "Estado": "MG",
    "CEP": "30110-000",
    "CpfCnpj": "12345678909",
    "InscRG": "",
    "Celular": "31999990000",
    "Telefone": "",
    "Email": "maria@exemplo.com.br"
  }
}
```

## 4. Com o kit em Node.js

```js
const clientes = await gs.obterLista(16, limparBusca("maria souza"));
if (clientes.length === 0) console.log("Nenhum cliente encontrado.");

const { DadosCliente } = await gs.venda(44, { DadosCliente: { Codigo: clientes[0].Codigo } });
console.log(DadosCliente.Nome, DadosCliente.Cidade);
```

Exemplo completo: [kit/exemplo-clientes.js](../kit/exemplo-clientes.js).

## 5. Falhas comuns

| Sintoma | Causa | Solução |
|---|---|---|
| `Erro` em todas as chamadas de `ObterLista` | `userHash` enviado no corpo. | Neste método, envie-o na query string. |
| Lista vazia | Texto não encontrado. | Use só parte do nome, ou o telefone ou CNPJ. |
| Cliente errado | Homônimos. | Mostre a lista ao usuário e peça para escolher. |
| Resposta tratada como objeto | `ObterLista` devolve uma lista de blocos. | Leia `resposta[0].Dados`. |

## 6. Gravar dados de cliente

- Para incluir ou alterar o cliente **dentro de um orçamento**, veja [Criar orçamento](criar-orcamento.md), item 4.
- Para alterar o **cadastro** de clientes, fornecedores e colaboradores, use `EditarPessoa` (catálogo de APIs, grupo Cadastro: `https://www.server1.gransoftweb.com/API/Cadastro`). Teste sempre em dados de teste.