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.

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"
  ]
}

Campo	Obrigatório	Descrição
`cnpjs`	Sim	Lista de 1 a 50 CNPJs distintos, enviados como texto. Aceita 14 dígitos ou a máscara `00.000.000/0000-00`.

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.

Campo da resposta	Descrição
`requestId`	Identificador da requisição para suporte; também enviado no header `X-Request-Id`.
`totalRegistros`	Quantidade de clientes disponíveis retornados.
`dados`	Lista de clientes, na ordem dos CNPJs solicitados, omitindo os indisponíveis.
`cnpjsNaoEncontradosOuNaoAutorizados`	CNPJs normalizados que não foram localizados ou autorizados.

Dados básicos do cliente

Grupo	Campos e descrição
Identificação	`id`, `cpfCnpj` e `nome`.
Endereço	`cep`, `logradouro`, `numero`, `complemento`, `bairro`, `cidade` e `estado`.
Cadastro	`inscricaoEstadual`, `tags`, `observacao`, `cadastroWhatsapp` e `dataHoraAtualizacao`.
Classificação	`classificacao`: nome da classificação, ou `null`.
Enriquecimento	`enriquecido`: indicador booleano de enriquecimento existente na estrutura autorizada.

Pessoas

Campo	Descrição
`id`	Identificador da pessoa.
`nome`	Nome cadastrado.
`cpf / rg`	Documentos cadastrados, quando disponíveis.
`email / celular / telefone2`	Dados de contato.
`nascimento`	Data de nascimento, no formato yyyy-MM-dd.
`papel`	Papel da pessoa no cliente.

Responsáveis

Campo	Descrição
`id`	Identificador do registro de responsabilidade.
`funcao`	Função cadastrada.
`usuarioId / nome / login`	Identificação do usuário responsável.
`estruturaUsuarioId`	Identificador do vínculo do usuário com a estrutura.
`ativo`	Situação do vínculo com a estrutura.
`equipeId / equipeNome`	Equipe vinculada ao responsável, ou null.

Contatos

Campo	Descrição
`id`	Identificador do contato.
`tipo`	Tipo do contato, conforme cadastro.
`valor`	Telefone, e-mail ou outro valor cadastrado.
`verificado`	Indicador de verificação cadastrado.
`nivelRelevancia`	Nível de relevância do contato.
`temWhats`	Indica WhatsApp cadastrado; pode retornar null.
`dataWhats`	Data da informação de WhatsApp.

Vencimentos

Campo	Descrição
`id`	Identificador do vencimento.
`nome`	Descrição cadastrada.
`dia`	Dia informado para o vencimento.
`apartir`	Data inicial de vigência, no formato yyyy-MM-dd. O nome do campo é exatamente apartir.
`ate`	Data final de vigência, ou null.

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.

Regra	Limite padrão
Execuções simultâneas no guard compartilhado	2
Execuções simultâneas por estrutura	1
Intervalo após o término de uma execução	120 segundos
Execuções por estrutura	3 a cada 10 minutos
Tentativas por token	20 a cada 60 segundos
Tentativas globais	600 a cada 60 segundos
Autenticações simultâneas	8
CNPJs por requisição	50
Payload	16 KiB
Itens de cada coleção no lote completo	5.000 por coleção: pessoas, responsáveis, contatos ou vencimentos
Timeout configurado de processamento no banco	30 segundos; limite de consulta configurado de 10 segundos

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

HTTP	Código	Como tratar
400	`PAYLOAD_INVALIDO` / `JSON_INVALIDO`	Corrija o JSON, os CNPJs ou a quantidade de itens.
401	`TOKEN_INVALIDO`	Verifique o token.
403	`ACESSO_NEGADO`	Verifique o vínculo e a estrutura autorizada.
413	`PAYLOAD_GRANDE`	Reduza o payload para até 16 KiB.
422	`LIMITE_ITENS`	Divida a lista de CNPJs em lotes menores.
422	`CADASTRO_AMBIGUO`	Há cadastros duplicados para CNPJs solicitados; contate o suporte.
429	`LIMITE_API`	Aguarde o tempo informado em Retry-After.
504	`TEMPO_EXCEDIDO`	Reduza o lote e respeite o intervalo antes de repetir.
500	`ERRO_INTERNO`	Informe o requestId ao suporte.

{
  "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.

Api de Carga da Produção

Api do Relatório de exportação

Api de Movimentação de Pedidos

Api Consulta Pedido

Api Movimentação de Etapa de Atividade