# Consulta Cliente

A API de Consulta de Clientes permite consultar uma lista de CNPJs e receber os dados básicos dos clientes, pessoas, responsáveis, contatos, vencimentos e o indicador de enriquecimento.

## Endereço

```
POST https://api.xeotech.com.br/api/v1/clientes/consulta/{token}
```

O token é informado na URL. Para localizar seu token, consulte a página [Meu token](https://ajuda.xeotech.com.br/books/apis-de-integracao/page/meu-token-para-proprietarios).

## Autorização e acesso

O token precisa possuir um vínculo ativo com uma estrutura ativa. A estrutura é obtida pelo usuário do token: não envie `estruturaId` no payload.

Usuários com perfil `PROPRIETARIO` ou permissão `CLIENTE_CARTEIRA_VER_TUDO` podem consultar os clientes da estrutura. Os demais precisam estar cadastrados como responsáveis diretos pelo cliente. A consulta aos dados extras segue essa regra; estar na hierarquia de um responsável não substitui o vínculo direto.

CNPJs inexistentes ou sem autorização aparecem na mesma lista `cnpjsNaoEncontradosOuNaoAutorizados`. A API não revela cadastros de outras estruturas.

## Payload

```
{
  "cnpjs": [
    "55275604000132",
    "12.345.678/0001-90"
  ]
}
```

<table id="bkmrk-campo-obrigat%C3%B3rio-de"><thead><tr class="header"><th>Campo</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr class="odd"><td>`cnpjs`</td><td>Sim</td><td>Lista de 1 a 50 CNPJs distintos, enviados como texto. Aceita 14 dígitos ou a máscara `00.000.000/0000-00`.</td></tr></tbody></table>

Somente o campo `cnpjs` é aceito. Não envie `formato`: o retorno é exclusivamente JSON. CNPJs repetidos são rejeitados, inclusive quando um é enviado com máscara e outro sem máscara.

A máscara é removida antes da consulta. O cadastro é localizado pelo CNPJ armazenado sem máscara. Os dígitos verificadores não são validados nessa consulta. Números JSON, CPFs, listas vazias e campos adicionais são rejeitados.

## Exemplo cURL

```
curl --fail-with-body --request POST \
  'https://api.xeotech.com.br/api/v1/clientes/consulta/SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --output clientes.json \
  --data '{"cnpjs":["55275604000132","12.345.678/0001-90"]}'
```

## Retorno JSON

Exemplo ilustrativo. Os IDs, nomes e dados abaixo são fictícios; os campos correspondem ao contrato da API.

```
{
  "requestId": "d8e4c3c2-0000-0000-0000-000000000000",
  "totalRegistros": 1,
  "dados": [
    {
      "id": 1001,
      "cpfCnpj": "55275604000132",
      "nome": "Empresa Exemplo Ltda.",
      "cep": "88330000",
      "logradouro": "Rua Exemplo",
      "numero": "100",
      "complemento": null,
      "bairro": "Centro",
      "cidade": "Balneário Camboriú",
      "estado": "SC",
      "inscricaoEstadual": null,
      "tags": "#CLIENTE",
      "observacao": null,
      "dataHoraAtualizacao": "2026-10-05T08:00:00",
      "classificacao": "Cliente",
      "enriquecido": true,
      "pessoas": [
        {
          "id": 101,
          "nome": "Pessoa Exemplo",
          "cpf": null,
          "rg": null,
          "email": "pessoa@example.com",
          "celular": "47999990000",
          "telefone2": null,
          "nascimento": null,
          "papel": "Contato comercial"
        }
      ],
      "responsaveis": [
        {
          "id": 201,
          "usuarioId": 301,
          "nome": "Consultor Exemplo",
          "login": "consultor@example.com",
          "estruturaUsuarioId": 401,
          "ativo": true,
          "equipeId": 501,
          "equipeNome": "Equipe Comercial"
        }
      ],
      "contatos": [
        {
          "id": 601,
          "tipo": null,
          "valor": "47999990000",
          "verificado": null
        }
      ],
      "vencimentos": [
        {
          "id": 701,
          "identificador": "NUMERO-CONTRATO",
          "dia": 10,
          "apartir": "2026-01-01",
          "ate": "2026-12-31"
        }
      ]
    }
  ],
  "cnpjsNaoEncontradosOuNaoAutorizados": [
    "12345678000190"
  ]
}
```

Campos sem valor podem retornar `null`. As listas sem registros retornam `[]`. Os valores de `tipo` e `verificado`, quando preenchidos, são os nomes dos indicadores cadastrados no Xeotech.

<table id="bkmrk-campo-da-resposta-de"><thead><tr class="header"><th>Campo da resposta</th><th>Descrição</th></tr></thead><tbody><tr class="odd"><td>`requestId`</td><td>Identificador da requisição para suporte; também enviado no header `X-Request-Id`.</td></tr><tr class="even"><td>`totalRegistros`</td><td>Quantidade de clientes disponíveis retornados.</td></tr><tr class="odd"><td>`dados`</td><td>Lista de clientes, na ordem dos CNPJs solicitados, omitindo os indisponíveis.</td></tr><tr class="even"><td>`cnpjsNaoEncontradosOuNaoAutorizados`</td><td>CNPJs normalizados que não foram localizados ou autorizados.</td></tr></tbody></table>

## Dados básicos do cliente

<table id="bkmrk-grupo-campos-e-descr"><thead><tr class="header"><th>Grupo</th><th>Campos e descrição</th></tr></thead><tbody><tr class="odd"><td>Identificação</td><td>`id`, `cpfCnpj` e `nome`.</td></tr><tr class="even"><td>Endereço</td><td>`cep`, `logradouro`, `numero`, `complemento`, `bairro`, `cidade` e `estado`.</td></tr><tr class="odd"><td>Cadastro</td><td>`inscricaoEstadual`, `tags`, `observacao`, `cadastroWhatsapp` e `dataHoraAtualizacao`.</td></tr><tr class="even"><td>Classificação</td><td>`classificacao`: nome da classificação, ou `null`.</td></tr><tr class="odd"><td>Enriquecimento</td><td>`enriquecido`: indicador booleano de enriquecimento existente na estrutura autorizada.</td></tr></tbody></table>

## Pessoas

<table id="bkmrk-campo-descri%C3%A7%C3%A3o-id-i"><thead><tr class="header"><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr class="odd"><td>`id`</td><td>Identificador da pessoa.</td></tr><tr class="even"><td>`nome`</td><td>Nome cadastrado.</td></tr><tr class="odd"><td>`cpf / rg`</td><td>Documentos cadastrados, quando disponíveis.</td></tr><tr class="even"><td>`email / celular / telefone2`</td><td>Dados de contato.</td></tr><tr class="odd"><td>`nascimento`</td><td>Data de nascimento, no formato yyyy-MM-dd.</td></tr><tr class="even"><td>`papel`</td><td>Papel da pessoa no cliente.</td></tr></tbody></table>

## Responsáveis

<table id="bkmrk-campo-descri%C3%A7%C3%A3o-id-i-1"><thead><tr class="header"><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr class="odd"><td>`id`</td><td>Identificador do registro de responsabilidade.</td></tr><tr class="even"><td>`funcao`</td><td>Função cadastrada.</td></tr><tr class="odd"><td>`usuarioId / nome / login`</td><td>Identificação do usuário responsável.</td></tr><tr class="even"><td>`estruturaUsuarioId`</td><td>Identificador do vínculo do usuário com a estrutura.</td></tr><tr class="odd"><td>`ativo`</td><td>Situação do vínculo com a estrutura.</td></tr><tr class="even"><td>`equipeId / equipeNome`</td><td>Equipe vinculada ao responsável, ou null.</td></tr></tbody></table>

## Contatos

<table id="bkmrk-campo-descri%C3%A7%C3%A3o-id-i-2"><thead><tr class="header"><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr class="odd"><td>`id`</td><td>Identificador do contato.</td></tr><tr class="even"><td>`tipo`</td><td>Tipo do contato, conforme cadastro.</td></tr><tr class="odd"><td>`valor`</td><td>Telefone, e-mail ou outro valor cadastrado.</td></tr><tr class="even"><td>`verificado`</td><td>Indicador de verificação cadastrado.</td></tr><tr class="odd"><td>`nivelRelevancia`</td><td>Nível de relevância do contato.</td></tr><tr class="even"><td>`temWhats`</td><td>Indica WhatsApp cadastrado; pode retornar null.</td></tr><tr class="odd"><td>`dataWhats`</td><td>Data da informação de WhatsApp.</td></tr></tbody></table>

## Vencimentos

<table id="bkmrk-campo-descri%C3%A7%C3%A3o-id-i-3"><thead><tr class="header"><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr class="odd"><td>`id`</td><td>Identificador do vencimento.</td></tr><tr class="even"><td>`nome`</td><td>Descrição cadastrada.</td></tr><tr class="odd"><td>`dia`</td><td>Dia informado para o vencimento.</td></tr><tr class="even"><td>`apartir`</td><td>Data inicial de vigência, no formato yyyy-MM-dd. O nome do campo é exatamente apartir.</td></tr><tr class="odd"><td>`ate`</td><td>Data final de vigência, ou null.</td></tr></tbody></table>

## Indicador enriquecido

`enriquecido: true` significa que existe um registro de enriquecimento para esse CNPJ na estrutura do token. `false` significa que não foi localizado esse registro. O indicador não garante que todos os contatos estejam preenchidos ou atualizados.

Essa consulta apenas informa o enriquecimento existente. Ela não executa enriquecimento e não consome créditos para enriquecer o cliente.

## Limites e guard

A consulta compartilha o guard da API de pedidos. Chamadas de consulta de clientes e das APIs de pedidos disputam os mesmos limites de execução; trocar o token não elimina os limites por estrutura.

<table id="bkmrk-regra-limite-padr%C3%A3o-"><thead><tr class="header"><th>Regra</th><th>Limite padrão</th></tr></thead><tbody><tr class="odd"><td>Execuções simultâneas no guard compartilhado</td><td>2</td></tr><tr class="even"><td>Execuções simultâneas por estrutura</td><td>1</td></tr><tr class="odd"><td>Intervalo após o término de uma execução</td><td>120 segundos</td></tr><tr class="even"><td>Execuções por estrutura</td><td>3 a cada 10 minutos</td></tr><tr class="odd"><td>Tentativas por token</td><td>20 a cada 60 segundos</td></tr><tr class="even"><td>Tentativas globais</td><td>600 a cada 60 segundos</td></tr><tr class="odd"><td>Autenticações simultâneas</td><td>8</td></tr><tr class="even"><td>CNPJs por requisição</td><td>50</td></tr><tr class="odd"><td>Payload</td><td>16 KiB</td></tr><tr class="even"><td>Itens de cada coleção no lote completo</td><td>5.000 por coleção: pessoas, responsáveis, contatos ou vencimentos</td></tr><tr class="odd"><td>Timeout configurado de processamento no banco</td><td>30 segundos; limite de consulta configurado de 10 segundos</td></tr></tbody></table>

Concorrência global e intervalo entre execuções seguem a configuração vigente do servidor. Quando um limite é atingido, a API retorna `429` com o header `Retry-After`, indicando quantos segundos aguardar. O controle é aplicado por instância da aplicação.

Se uma coleção ultrapassar 5.000 itens somando todos os clientes do lote, a API rejeita a resposta inteira com `LIMITE_ITENS`. Reduza a quantidade de CNPJs e consulte novamente. A resposta não é truncada silenciosamente.

## Respostas de erro

<table id="bkmrk-http-c%C3%B3digo-como-tra"><thead><tr class="header"><th>HTTP</th><th>Código</th><th>Como tratar</th></tr></thead><tbody><tr class="odd"><td>400</td><td>`PAYLOAD_INVALIDO` / `JSON_INVALIDO`</td><td>Corrija o JSON, os CNPJs ou a quantidade de itens.</td></tr><tr class="even"><td>401</td><td>`TOKEN_INVALIDO`</td><td>Verifique o token.</td></tr><tr class="odd"><td>403</td><td>`ACESSO_NEGADO`</td><td>Verifique o vínculo e a estrutura autorizada.</td></tr><tr class="even"><td>413</td><td>`PAYLOAD_GRANDE`</td><td>Reduza o payload para até 16 KiB.</td></tr><tr class="odd"><td>422</td><td>`LIMITE_ITENS`</td><td>Divida a lista de CNPJs em lotes menores.</td></tr><tr class="even"><td>422</td><td>`CADASTRO_AMBIGUO`</td><td>Há cadastros duplicados para CNPJs solicitados; contate o suporte.</td></tr><tr class="odd"><td>429</td><td>`LIMITE_API`</td><td>Aguarde o tempo informado em Retry-After.</td></tr><tr class="even"><td>504</td><td>`TEMPO_EXCEDIDO`</td><td>Reduza o lote e respeite o intervalo antes de repetir.</td></tr><tr class="odd"><td>500</td><td>`ERRO_INTERNO`</td><td>Informe o requestId ao suporte.</td></tr></tbody></table>

```
{
  "codigo": "LIMITE_ITENS",
  "mensagem": "Uma coleção excedeu 5.000 itens. Reduza a lista de CNPJs.",
  "requestId": "d8e4c3c2-0000-0000-0000-000000000000"
}
```

Quando nenhum CNPJ está disponível, a resposta é HTTP `200`, com `dados: []`, `totalRegistros: 0` e a lista dos CNPJs indisponíveis. Não é retornado HTTP 404 para cada cliente.

## Boas práticas

- Agrupe consultas em lotes de até 50 CNPJs e evite uma chamada por cliente.
- Armazene os dados necessários na integração para evitar consultas repetidas.
- Respeite o Retry-After e os limites compartilhados com pedidos.
- Trate listas vazias e campos null.
- Não registre o token completo nos logs.
- O retorno inclui documentos e contatos de pessoas; restrinja o acesso a esses dados na sua integração.

Senhas e credenciais de gestor ou conta online não fazem parte da resposta.