Api's de integração

Meu Token (para proprietários)

Para saber seu TOKEN de acesso a API, dentro do sistema acesse MENU -> MEU PERFIL -> MEUS DADOS.

❗Tokens só estarão disponíveis para usuários com perfil de PROPRIETÁRIO.

image.png

❗Se por acaso seu token foi exposto, basta clicar em Gerar novo token que o antigo token será automáticamente inativado.

⚠️ Atenção!
Use sempre HTTPS e mantenha o token de integração protegido. Não publique o token em código-fonte, repositórios, prints ou logs.

Gerar Token para Meus Usuários

Se você tiver o perfil PROPRIETÁRIO, você poderá gerar Tokens para seus usuarios. 
Com o token eles irão conseguir utilzar as integrações disponíveis, SEMPRE limitados à sua hierarquia.

Para isso acesse MENU -> USUÁRIOS -> CADASTRO DE USUÁRIOS, filtre e selecione o usuário em questão.
Clique em Editar, no final do formulário estará o token do usuário.

image.png

Cuidado ao compartilhar o token.
Caso haja vazamento, basta acessar o cadatro do usuário e clicar em GERAR NOVO TOKEN.

Produção

Produção

Api de Carga da Produção

A API de Produção permite consultar os dados que participam de um Painel de Produção autorizado.

Use a API para:

Endereço base

https://api.xeotech.com.br/api/v1/producao/carga/SEU_TOKEN

O token é informado na URL. Não envie o token no corpo do payload.

Quer saber como localizar seu TOKEN dentro do sistema? Clique aqui.

Autorização

O token precisa ser um token de integração de usuário ativo. O usuário também precisa ter acesso à estrutura do painel informado e possuir as permissões:

A API respeita a hierarquia do usuário. A permissão IGNORAR_HIERARQUIA é aplicada pelo próprio Xeotech, de acordo com o usuário autorizado.

Painel, estrutura, vínculo ou permissão indisponível retornam 403. Token inválido retorna 401.

Formatos

O campo formato aceita:

Se formato não for informado, o retorno será JSON.

Chamada

A carga é usada para criar ou atualizar uma cópia dos dados do Xeotech. Baixe a sua base de produção e atualize de hora em hora para manter uma cópia da base de produção. 

POST /api/v1/producao/carga/{token}
Content-Type: application/json

Payload

{
  "painelId": 123,
  "dataHoraInicioCarga": "2026-09-30 09:00:00",
  "dataHoraFimCarga": "2026-09-30 10:00:00",
  "formato": "json"
}
Campo Obrigatório Descrição
painelId Sim ID do Painel de Produção que será consultado.
dataHoraInicioCarga Sim Início do período, no formato yyyy-MM-dd HH:mm:ss.
dataHoraFimCarga Não Fim do período. Se omitido, o Xeotech usa o horário de recebimento da requisição.
formato Não json ou csv. O padrão é json.

Para saber o ID do painel (painelId) acesse MENU -> PRODUÇÃO -> PAINEL DE PRODUÇÃO

image.png

As datas usam o fuso America/Sao_Paulo.

O filtro é aplicado assim:

pedido.data_hora_atualizacao >= dataHoraInicioCarga
pedido.data_hora_atualizacao < dataHoraFimCarga

O início é inclusivo e o fim é exclusivo. Para a próxima carga, é possível usar o fim da carga anterior como início da seguinte.

Durante o dia, entre 05:00 e 22:00, o período máximo é de 90 minutos. Entre 22:00 e 05:00 é possível solicitar períodos maiores, respeitando os limites de registros, tamanho do arquivo e tempo de processamento.

cURL — JSON

curl --fail-with-body --location \
  --request POST \
  'https://api.xeotech.com.br/api/v1/producao/carga/SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --output carga-producao.json \
  --data '{
    "painelId": 123,
    "dataHoraInicioCarga": "2026-09-30 09:00:00",
    "dataHoraFimCarga": "2026-09-30 10:00:00",
    "formato": "json"
  }'

cURL — CSV

curl --fail-with-body --location \
  --request POST \
  'https://api.xeotech.com.br/api/v1/producao/carga/SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --output carga-producao.csv \
  --data '{
    "painelId": 123,
    "dataHoraInicioCarga": "2026-09-30 09:00:00",
    "dataHoraFimCarga": "2026-09-30 10:00:00",
    "formato": "csv"
  }'

Carga inicial e cargas seguintes

Para a primeira carga, use um período histórico adequado, preferencialmente durante a janela noturna. Depois, faça cargas menores, por exemplo, de hora em hora, sempre usando a data de atualização como controle.

A API não informa exclusões. Se um pedido ou item deixar de participar do painel, ele não aparecerá necessariamente em uma carga incremental. Faça uma reconciliação completa periódica e use uma sobreposição de alguns minutos entre cargas para reduzir o risco de atualizações tardias.

Retornos da API

No formato JSON, a carga retorna meta, dados e totalRegistros. Cada elemento de dados representa uma linha da carga e contém os 80 campos documentados abaixo. O relatório de exportação possui um contrato próprio, descrito na página dessa operação.

Campo Descrição
meta Versão, painel, operação, fuso, horário de recebimento (recebidoEm) e período utilizado.
dados Lista de registros. Retorna [] quando não houver resultados.
totalRegistros Quantidade de linhas retornadas, não a soma do campo quantidade.

Datas são retornadas como yyyy-MM-dd; data e hora, como yyyy-MM-ddTHH:mm:ss, podendo conter frações de segundo. Os exemplos abaixo são fictícios. Considere o fuso America/Sao_Paulo; os valores não incluem um deslocamento UTC.

Retorno da carga

O exemplo abaixo apresenta uma linha completa da carga, com os 80 campos retornados pela API, incluindo campos sem valor. Os valores são fictícios. A tabela seguinte lista os mesmos campos na ordem do cabeçalho CSV.

{
  "meta": {
    "versao": "v1",
    "painelId": 123,
    "operacao": "carga",
    "fusoHorario": "America/Sao_Paulo",
    "recebidoEm": "2026-10-05T16:44:05",
    "dataHoraInicioCarga": "2026-10-01T13:00:00",
    "dataHoraFimCarga": "2026-10-01T14:00:00",
    "intervalo": "inicioInclusivoFimExclusivo"
  },
  "dados": [
    {
      "id": "123:1001:2001:10:20",
      "pedidoId": 1001,
      "linhaId": 10,
      "colunaId": 20,
      "nomeLinha": "VOZ - Renovação",
      "nomeColuna": "Ativo/Instalado",
      "quantidade": 5,
      "valor": 199.95,
      "valorUnitario": 39.99,
      "valorDesconto": 0,
      "valorBaseAtual": 0,
      "valorAgregado": 0,
      "numeroPedido": "1001",
      "numeroPedidoOrigem": null,
      "numeroPedidoVinculado": null,
      "tipoNegociacao": "NOVO",
      "clienteId": 3001,
      "nomeCliente": "Empresa Exemplo Ltda.",
      "cpfCnpj": "12345678000190",
      "cidade": "BALNEARIO CAMBORIU",
      "estado": "SC",
      "ddd": "47",
      "estruturaUsuarioId": 4001,
      "nomeUsuario": "Consultor Exemplo",
      "nomeUsuarioAdm": null,
      "equipeId": null,
      "nomeEquipe": null,
      "nomeEtapa": "ATIVO (NEOCRM)",
      "nomeEtapaItem": "CONCLUIDO",
      "dataCadastro": "2026-09-28",
      "dataHoraAtualizacao": "2026-10-01T13:50:13",
      "dataPortabilidade": null,
      "nomeOrigem": "NEOCRM",
      "item": null,
      "itemId": 2001,
      "pedidoItemSolicitacaoId": 4,
      "produtoId": 5001,
      "produtoCategoriaId": 1,
      "nomeProduto": "Plano de voz - Exemplo",
      "nomeCategoria": "VOZ",
      "numeroTelefoneItem": "",
      "dataReferencia": "2026-10-01",
      "nomeConsultorOperadora": null,
      "notasFiscais": null,
      "revisao": null,
      "loginOperadora": null,
      "atividades": null,
      "tags": "",
      "percentualDesconto": null,
      "percentualTroca": null,
      "cep": "88330000",
      "clusterOrigem": null,
      "solicitacaoId": 4,
      "nomeSolicitacao": "RENOVAÇÃO",
      "somaQuantidade": true,
      "dataInstalacao": null,
      "periodo": null,
      "rpon": "",
      "instancia": "",
      "cepInstalacao": null,
      "logradouroInstalacao": null,
      "numeroInstalacao": null,
      "bairroInstalacao": null,
      "complInstalacao": null,
      "cidadeInstalacao": null,
      "estadoInstalacao": null,
      "numeroProvisorio": "",
      "codigoPortabilidade": null,
      "cotacao": null,
      "aparelhoCartaoCredito": null,
      "categoriaAtividade": null,
      "subCategoriaAtividade": null,
      "numeroSimulacao": null,
      "operadoraCedente": "",
      "nomeCedente": "",
      "telefoneCedente": "",
      "emailCedente": "",
      "cpfCnpjCedente": "",
      "claroConvergenciaResposta": null,
      "claroTabelaRenovacao": null
    }
  ],
  "totalRegistros": 1
}

Campos da carga, na ordem do cabeçalho CSV:

Posições Campos
1–8 id, pedidoId, linhaId, colunaId, nomeLinha, nomeColuna, quantidade, valor
9–16 valorUnitario, valorDesconto, valorBaseAtual, valorAgregado, numeroPedido, numeroPedidoOrigem, numeroPedidoVinculado, tipoNegociacao
17–24 clienteId, nomeCliente, cpfCnpj, cidade, estado, ddd, estruturaUsuarioId, nomeUsuario
25–32 nomeUsuarioAdm, equipeId, nomeEquipe, nomeEtapa, nomeEtapaItem, dataCadastro, dataHoraAtualizacao, dataPortabilidade
33–40 nomeOrigem, item, itemId, pedidoItemSolicitacaoId, produtoId, produtoCategoriaId, nomeProduto, nomeCategoria
41–48 numeroTelefoneItem, dataReferencia, nomeConsultorOperadora, notasFiscais, revisao, loginOperadora, atividades, tags
49–56 percentualDesconto, percentualTroca, cep, clusterOrigem, solicitacaoId, nomeSolicitacao, somaQuantidade, dataInstalacao
57–64 periodo, rpon, instancia, cepInstalacao, logradouroInstalacao, numeroInstalacao, bairroInstalacao, complInstalacao
65–72 cidadeInstalacao, estadoInstalacao, numeroProvisorio, codigoPortabilidade, cotacao, aparelhoCartaoCredito, categoriaAtividade, subCategoriaAtividade
73–80 numeroSimulacao, operadoraCedente, nomeCedente, telefoneCedente, emailCedente, cpfCnpjCedente, claroConvergenciaResposta, claroTabelaRenovacao

Campos sem informação podem retornar null ou texto vazio "", conforme o cadastro. Valores numéricos e booleanos preservam seus tipos no JSON. Se não houver linhas, a API retorna dados: [] e totalRegistros: 0.

Campos sem informação podem retornar null. A carga não acrescenta os complementos calculados do relatório, como formularios, tagsAtividade e variacaoRenovacao.

Na carga, o identificador da linha segue o formato:

painelId:pedidoId:itemId:linhaId:colunaId

Use o campo id para fazer upsert na sua cópia local. Essa orientação se aplica exclusivamente à carga: o relatório de exportação não retorna esse identificador.

Limites de proteção

Os limites abaixo somam as chamadas de carga e exportação.

Regra Limite padrão
Exportações simultâneas globais 2
Exportações simultâneas por estrutura 1
Intervalo mínimo após 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
Registros por resposta 1.000.000
Tamanho máximo do arquivo 1 GiB
Tamanho máximo do payload 16 KiB
Tempo máximo solicitado para a consulta 600 segundos
Tempo máximo de geração da resposta 900 segundos

As tentativas recusadas também entram no controle de tentativas. Quando um limite temporário for atingido, a resposta será 429 e terá o header Retry-After com a quantidade aproximada de segundos para nova tentativa.

Os limites são aplicados por estrutura, mesmo que o cliente altere o período, o painel ou o formato entre chamadas. Enquanto uma exportação estiver em andamento, uma segunda chamada para a mesma estrutura será recusada.

Respostas de erro

HTTP Código comum Situação
400 PAYLOAD_INVALIDO Campo ausente, data inválida ou período incorreto.
401 TOKEN_INVALIDO Token inválido.
403 ACESSO_NEGADO Sem acesso ao painel ou às permissões necessárias.
413 PAYLOAD_GRANDE Payload maior que 16 KiB.
422 LIMITE_REGISTROS ou LIMITE_ARQUIVO Resultado acima dos limites permitidos.
429 LIMITE_API Guard ocupado, cooldown ou excesso de tentativas.
504 TEMPO_EXCEDIDO Consulta ou geração excedeu o tempo permitido.

Exemplo de erro:

{
  "codigo": "LIMITE_API",
  "mensagem": "Aguarde entre exportações da API.",
  "requestId": "d8e4c3c2-0000-0000-0000-000000000000"
}

Guarde o requestId ao registrar uma falha. Ele ajuda o suporte a localizar a execução nos logs.

Boas práticas de integração

Produção

Api do Relatório de exportação

Esse endpoint retorna os campos e cálculos do relatório da tela do Painel de Produção em JSON ou CSV, respeitando o usuário, o painel e a hierarquia autorizada. O retorno é diferente da carga: não inclui os IDs internos e seleciona os campos conforme o tipo da estrutura. Formulários e tags são agrupados em campos próprios na API, em vez de colunas individuais do Excel.

Endereço base

https://api.xeotech.com.br/api/v1/producao/exportacao/SEU_TOKEN

O token é informado na URL. Não envie o token no corpo do payload.

Quer saber como localizar seu TOKEN dentro do sistema? Clique aqui.

Autorização

O token precisa ser um token de integração de usuário ativo. O usuário também precisa ter acesso à estrutura do painel informado e possuir as permissões:

A API respeita a hierarquia do usuário. A permissão IGNORAR_HIERARQUIA é aplicada pelo próprio Xeotech, de acordo com o usuário autorizado.

Painel, estrutura, vínculo ou permissão indisponível retornam 403. Token inválido retorna 401.

Formatos

O campo formato aceita:

Se formato não for informado, o retorno será JSON.

Chamada

A api de exportação reflete exatamente a exportação do painel de produção.

POST /api/v1/producao/exportacao/{token}
Content-Type: application/json

Na exportação, envie dataInicio e dataFim. Não envie dataHoraInicioCarga nem dataHoraFimCarga.

Payload

{
  "painelId": 123,
  "dataInicio": "2026-09-01",
  "dataFim": "2026-09-30",
  "formato": "csv"
}
Campo Obrigatório Descrição
painelId Sim ID do Painel de Produção.
dataInicio Sim Data inicial no formato yyyy-MM-dd.
dataFim Sim Data final no formato yyyy-MM-dd.
formato Não json ou csv. O padrão é json.

O período máximo é de três meses, contando as duas datas. Por exemplo, 01/01 a 31/03 é válido; 01/01 a 01/04 ultrapassa o limite.

Para saber o ID do painel (painelId) acesse MENU -> PRODUÇÃO -> PAINEL DE PRODUÇÃOimage.png

cURL — CSV

curl --fail-with-body --location \
  --request POST \
  'https://api.xeotech.com.br/api/v1/producao/exportacao/SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --output exportacao-producao.csv \
  --data '{
    "painelId": 123,
    "dataInicio": "2026-09-01",
    "dataFim": "2026-09-30",
    "formato": "csv"
  }'

cURL — JSON

curl --fail-with-body --location \
  --request POST \
  'https://api.xeotech.com.br/api/v1/producao/exportacao/SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --output exportacao-producao.json \
  --data '{
    "painelId": 123,
    "dataInicio": "2026-09-01",
    "dataFim": "2026-09-30",
    "formato": "json"
  }'

Retornos da API

A api retorna um objeto JSON com meta, dados e totalRegistros. Cada elemento de dados representa uma linha do resultado. Os campos da linha dependem da operação.

Campo Descrição
meta Versão, painel, operação, fuso, horário de recebimento (recebidoEm) e período utilizado.
dados Lista de registros. Retorna [] quando não houver resultados.
totalRegistros Quantidade de linhas retornadas, não a soma do campo quantidade.

Datas são retornadas como yyyy-MM-dd; data e hora, como yyyy-MM-ddTHH:mm:ss, podendo conter frações de segundo. Os exemplos abaixo são fictícios. Considere o fuso America/Sao_Paulo; os valores não incluem um deslocamento UTC.

Retorno do relatório de exportação

A exportação retorna os campos do relatório aplicáveis à estrutura. Campos que não se aplicam são omitidos do JSON e do cabeçalho CSV; campos aplicáveis sem informação podem retornar null ou texto vazio.

Condição Campos retornados
Todas as estruturas nomeLinha, nomeColuna, numeroPedido, nomeCliente, cpfCnpj, tipoPessoa, cidade, estado, nomeUsuario, usuarioTags, nomeUsuarioAdm, nomeEquipe, nomeEtapa, categoriaAtividade, subCategoriaAtividade, dataCadastro, dataHoraAtualizacao, solicitacao, nomeEtapaItem, nomeProduto, valor, quantidade, valorDesconto, dataReferencia, formularios, tagsAtividade
Estruturas de telefonia numeroVinculado, loginOperadora, ddd, nomeConsultorOperadora, possuiAudio, tipoNegociacao, notasFiscais, revisao, atividades, item, numeroTelefoneItem, dataPortabilidade, operadoraCedente, nomeCedente, cpfCnpjCedente, telefoneCedente, emailCedente, nomeOrigem, dataInstalacao, periodo, cepInstalacao, logradouroInstalacao, numeroInstalacao, bairroInstalacao, complInstalacao, cidadeInstalacao, estadoInstalacao
Vivo cotacao, numeroPedidoOrigem, codigoPortabilidade, numeroProvisorio, rpon, instancia
Claro percentualDesconto, variacaoRenovacao, faixaRenovacao, valorBaseAtual, valorAgregado, percentualTroca, clusterOrigem, aparelhoCartaoCredito, claroConvergenciaResposta, claroTabelaRenovacao

Os grupos são cumulativos: uma estrutura Vivo de telefonia recebe os campos comuns, os de telefonia e os de Vivo; uma estrutura Claro de telefonia recebe os comuns, os de telefonia e os de Claro. TIM e demais estruturas recebem os campos comuns e, quando classificadas como telefonia no Xeotech, os campos de telefonia. A classificação é definida pelo sistema.

Ordem das colunas: siga a lista abaixo, desconsiderando os campos que não se aplicarem. No JSON, leia os campos pelo nome; no CSV, utilize o cabeçalho do arquivo recebido.

nomeLinha;nomeColuna;numeroPedido;numeroVinculado;cotacao;numeroPedidoOrigem;codigoPortabilidade;loginOperadora;nomeCliente;cpfCnpj;tipoPessoa;cidade;estado;ddd;nomeUsuario;usuarioTags;nomeUsuarioAdm;nomeConsultorOperadora;nomeEquipe;nomeEtapa;categoriaAtividade;subCategoriaAtividade;dataCadastro;dataHoraAtualizacao;solicitacao;possuiAudio;tipoNegociacao;notasFiscais;revisao;atividades;item;numeroTelefoneItem;numeroProvisorio;nomeEtapaItem;dataPortabilidade;operadoraCedente;nomeCedente;cpfCnpjCedente;telefoneCedente;emailCedente;nomeProduto;valor;quantidade;valorDesconto;dataReferencia;nomeOrigem;dataInstalacao;periodo;cepInstalacao;logradouroInstalacao;numeroInstalacao;bairroInstalacao;complInstalacao;cidadeInstalacao;estadoInstalacao;rpon;instancia;percentualDesconto;variacaoRenovacao;faixaRenovacao;valorBaseAtual;valorAgregado;percentualTroca;clusterOrigem;aparelhoCartaoCredito;claroConvergenciaResposta;claroTabelaRenovacao;formularios;tagsAtividade

Campos calculados e formatos especiais da exportação

Campo Regra
numeroVinculado Primeiro valor preenchido entre número do pedido vinculado, cotação e número da simulação. Retorna texto vazio quando nenhum estiver preenchido.
tipoPessoa PJ quando CPF/CNPJ tiver 14 caracteres; PF nos demais casos preenchidos. Retorna null quando CPF/CNPJ for nulo.
ddd DDD informado; quando ausente ou igual a zero, tenta localizar pelo estado e cidade. Sem resultado, retorna texto vazio.
quantidade Quantidade considerada na produção. Retorna zero quando o item não deve somar quantidade.
solicitacao Nome da solicitação do item, em vez do ID.
possuiAudio Texto SIM ou NAO, sem acento. Não é um booleano.
valor / valorDesconto Valores numéricos. Na ausência de valor, retornam zero.
variacaoRenovacao / faixaRenovacao Cálculo e faixa de renovação conforme as regras da estrutura Claro. Variação sem resultado retorna zero; a faixa é obtida pelo cálculo do Xeotech.
percentualDesconto / valorBaseAtual / valorAgregado / percentualTroca Valores numéricos específicos da Claro; quando nulos na origem, retornam zero.
aparelhoCartaoCredito Texto SIM, NÃO ou texto vazio quando não informado. Específico da Claro.
claroConvergenciaResposta / claroTabelaRenovacao Valores registrados na estrutura Claro, ou texto vazio quando não informados.
usuarioTags Tags do usuário, em texto.
formularios Objeto cujas chaves são os nomes dos campos dos formulários e cujos valores são as respostas. Sem respostas: {}.
tagsAtividade Lista de textos obtida das tags da atividade. Sem tags: [].

A exportação utiliza numeroVinculado, ddd, quantidade e solicitacao. Não retorna os nomes antigos numeroVinculadoExibicao, dddExibicao, quantidadeProducao e solicitacaoExibicao.

Exemplo completo de uma linha de exportação

Exemplo para uma estrutura sem campos de telefonia, Vivo ou Claro. Os campos condicionais são acrescentados nas estruturas correspondentes.

{
  "meta": {
    "versao": "v1",
    "painelId": 123,
    "operacao": "exportacao",
    "fusoHorario": "America/Sao_Paulo",
    "recebidoEm": "2026-09-30T10:00:00",
    "dataInicio": "2026-09-01",
    "dataFim": "2026-09-30"
  },
  "dados": [
    {
      "nomeLinha": "Serviços",
      "nomeColuna": "Vendas",
      "numeroPedido": "PED-1001",
      "nomeCliente": "Empresa Exemplo",
      "cpfCnpj": null,
      "tipoPessoa": null,
      "cidade": "São Paulo",
      "estado": "SP",
      "nomeUsuario": "Usuário Exemplo",
      "usuarioTags": "#COMERCIAL",
      "nomeUsuarioAdm": null,
      "nomeEquipe": "Equipe Comercial",
      "nomeEtapa": "Concluído",
      "categoriaAtividade": "Venda",
      "subCategoriaAtividade": null,
      "dataCadastro": "2026-09-10",
      "dataHoraAtualizacao": "2026-09-30T09:30:00",
      "solicitacao": null,
      "nomeEtapaItem": "Concluído",
      "nomeProduto": "Serviço Exemplo",
      "valor": 149.9,
      "quantidade": 1,
      "valorDesconto": 0.0,
      "dataReferencia": "2026-09-30",
      "formularios": {
        "Observação": "Instalação agendada",
        "Data combinada": "2026-10-01",
        "Aceite": "SIM",
        "Valor informado": "150,50"
      },
      "tagsAtividade": [
        "VENDA",
        "PRIORIDADE"
      ]
    }
  ],
  "totalRegistros": 1
}

Formulários e tags

Na API, as respostas de formulário ficam dentro de formularios. Texto permanece texto; datas usam formato ISO; respostas decimais são textos com vírgula, como "150,50"; respostas booleanas são textos "SIM" ou "NÃO". Os nomes dos campos dependem dos formulários do pedido.

tagsAtividade é uma lista separada das tags do usuário (usuarioTags). No CSV, tanto o objeto formularios quanto a lista tagsAtividade são serializados como JSON dentro de uma única célula cada. Eles não viram várias colunas, como no Excel do painel.

Retorno CSV

O CSV contém o cabeçalho e as linhas, sem o envelope meta/dados/totalRegistros. A carga possui cabeçalho fixo; o relatório possui cabeçalho conforme a estrutura.

Exemplo correspondente à linha JSON acima:

nomeLinha;nomeColuna;numeroPedido;nomeCliente;cpfCnpj;tipoPessoa;cidade;estado;nomeUsuario;usuarioTags;nomeUsuarioAdm;nomeEquipe;nomeEtapa;categoriaAtividade;subCategoriaAtividade;dataCadastro;dataHoraAtualizacao;solicitacao;nomeEtapaItem;nomeProduto;valor;quantidade;valorDesconto;dataReferencia;formularios;tagsAtividade
"Serviços";"Vendas";"PED-1001";"Empresa Exemplo";;;"São Paulo";"SP";"Usuário Exemplo";"#COMERCIAL";;"Equipe Comercial";"Concluído";"Venda";;"2026-09-10";"2026-09-30T09:30:00";;"Concluído";"Serviço Exemplo";"149.9";"1";"0.0";"2026-09-30";"{""Observação"":""Instalação agendada"",""Data combinada"":""2026-10-01"",""Aceite"":""SIM"",""Valor informado"":""150,50""}";"[""VENDA"",""PRIORIDADE""]"

Use um leitor CSV com separador ;, codificação UTF-8 e suporte a aspas escapadas. Depois de ler a célula de formulário ou tags, interprete seu conteúdo como JSON. Valores nulos viram células vazias. Textos que possam ser interpretados como fórmulas recebem um apóstrofo inicial de proteção.

Limites de proteção

Os limites abaixo somam as chamadas de carga e exportação.

Regra Limite padrão
Exportações simultâneas globais 2
Exportações simultâneas por estrutura 1
Intervalo mínimo após 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
Registros por resposta 1.000.000
Tamanho máximo do arquivo 1 GiB
Tamanho máximo do payload 16 KiB
Tempo máximo solicitado para a consulta 600 segundos
Tempo máximo de geração da resposta 900 segundos

As tentativas recusadas também entram no controle de tentativas. Quando um limite temporário for atingido, a resposta será 429 e terá o header Retry-After com a quantidade aproximada de segundos para nova tentativa.

Os limites são aplicados por estrutura, mesmo que o cliente altere o período, o painel ou o formato entre chamadas. Enquanto uma exportação estiver em andamento, uma segunda chamada para a mesma estrutura será recusada.

Respostas de erro

HTTP Código comum Situação
400 PAYLOAD_INVALIDO Campo ausente, data inválida ou período incorreto.
401 TOKEN_INVALIDO Token inválido.
403 ACESSO_NEGADO Sem acesso ao painel ou às permissões necessárias.
413 PAYLOAD_GRANDE Payload maior que 16 KiB.
422 LIMITE_REGISTROS ou LIMITE_ARQUIVO Resultado acima dos limites permitidos.
429 LIMITE_API Guard ocupado, cooldown ou excesso de tentativas.
504 TEMPO_EXCEDIDO Consulta ou geração excedeu o tempo permitido.

Exemplo de erro:

{
  "codigo": "LIMITE_API",
  "mensagem": "Aguarde entre exportações da API.",
  "requestId": "d8e4c3c2-0000-0000-0000-000000000000"
}

Guarde o requestId ao registrar uma falha. Ele ajuda o suporte a localizar a execução nos logs.

Boas práticas de integração

Pedidos (Atividades)

Pedidos (Atividades)

Api de Movimentação de Pedidos

A API de Movimentação de Pedidos permite consultar o histórico de movimentações dos pedidos de uma estrutura autorizada.

Use a API para:

Endereço

POST https://api.xeotech.com.br/api/v1/pedidos/movimentacao/{token}

O token é informado na URL. Não envie o token dentro do payload.

Para localizar seu token no Xeotech, acesse a página Meu token.

Autorização

O token precisa pertencer a um usuário ativo. O usuário também precisa possuir um vínculo ativo com uma estrutura ativa.

A estrutura usada na consulta é obtida pelo vínculo do usuário autenticado. O cliente não informa estruturaId no payload.

A consulta sempre aplica a estrutura do usuário:

eu.estrutura_id = estruturaIdDoUsuario

Mesmo que sejam enviados IDs de pedidos de outra estrutura, eles não serão retornados.

Payload

{
  "dataHoraInicio": "2026-09-30 09:00:00",
  "dataHoraFim": "2026-09-30 10:00:00",
  "pedidoTipo": "COMERCIAL",
  "pedidoIds": [1001, 1002],
  "formato": "json"
}
Campo Obrigatório Descrição
dataHoraInicio Sim Início do período no formato yyyy-MM-dd HH:mm:ss.
dataHoraFim Sim Fim do período no formato yyyy-MM-dd HH:mm:ss. Deve ser posterior ao início.
pedidoTipo Sim Aceita COMERCIAL ou POS_VENDA.
pedidoIds Não Lista de IDs de pedidos. Quando omitida ou vazia, consulta todos os pedidos da estrutura. Limite de 10.000 IDs.
formato Não Aceita json ou csv. O padrão é json.

Regras dos filtros

Payload Resultado
Período + pedidoTipo Todas as movimentações do período para o tipo informado, dentro da estrutura do usuário.
Período + pedidoTipo + pedidoIds Somente as movimentações do período dos pedidos informados e pertencentes à estrutura do usuário.

O início do período é inclusivo e o fim é exclusivo:

pedido.data_hora_atualizacao >= dataHoraInicio
pedido.data_hora_atualizacao < dataHoraFim

As datas usam o fuso America/Sao_Paulo.

Exemplos cURL

JSON — todos os pedidos do período

curl --fail-with-body --location \
  --request POST \
  'https://api.xeotech.com.br/api/v1/pedidos/movimentacao/SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --output movimentacoes-pedidos.json \
  --data '{
    "dataHoraInicio": "2026-09-30 09:00:00",
    "dataHoraFim": "2026-09-30 10:00:00",
    "pedidoTipo": "COMERCIAL",
    "formato": "json"
  }'

JSON — somente pedidos selecionados

curl --fail-with-body --location \
  --request POST \
  'https://api.xeotech.com.br/api/v1/pedidos/movimentacao/SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --output movimentacoes-pedidos.json \
  --data '{
    "dataHoraInicio": "2026-09-30 09:00:00",
    "dataHoraFim": "2026-09-30 10:00:00",
    "pedidoTipo": "POS_VENDA",
    "pedidoIds": [1001, 1002, 1003],
    "formato": "json"
  }'

CSV

curl --fail-with-body --location \
  --request POST \
  'https://api.xeotech.com.br/api/v1/pedidos/movimentacao/SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --output movimentacoes-pedidos.csv \
  --data '{
    "dataHoraInicio": "2026-09-30 09:00:00",
    "dataHoraFim": "2026-09-30 10:00:00",
    "pedidoTipo": "COMERCIAL",
    "pedidoIds": [1001, 1002],
    "formato": "csv"
  }'

Retorno JSON

{
  "meta": {
    "versao": "v1",
    "operacao": "movimentacao",
    "fusoHorario": "America/Sao_Paulo",
    "recebidoEm": "2026-09-30T10:00:00",
    "dataHoraInicio": "2026-09-30T09:00:00",
    "dataHoraFim": "2026-09-30T10:00:00",
    "pedidoTipo": "COMERCIAL",
    "pedidoIdsInformados": [1001, 1002]
  },
  "dados": [
    {
      "id": "123456789",
      "pedidoId": 1001,
      "euEntrouId": 20,
      "euSaiuId": 21,
      "etapaId": 8,
      "cpfCnpjCliente": "12345678000199",
      "nomeCliente": "Empresa Exemplo Ltda.",
      "numeroAtividade": "PED-1001",
      "nomeEtapa": "Em análise",
      "usuarioEntrou": "Usuário Entrada",
      "usuarioSaiu": "Usuário Saída",
      "dataHoraEntrou": "2026-09-30T09:10:00",
      "dataHoraSaiu": "2026-09-30T09:45:00",
      "tempo": "00:35:00",
      "slaHoras": 24,
      "tagsAtividade": "#PRIORIDADE,#CLIENTE",
      "movimentacao": "Avanço de etapa",
      "nomeConsultor": "Consultor Exemplo",
      "total": 149.90,
      "compromissoMensal": 99.90,
      "pedidoTipo": "COMERCIAL",
      "controlaBko": true
    }
  ],
  "totalRegistros": 1
}

O objeto dados utiliza os 22 campos do PedidoStatusDTO. Campos sem valor podem retornar null.

Campo Descrição
id Identificador gerado para a linha retornada.
pedidoId ID do pedido.
euEntrouId / euSaiuId IDs dos vínculos de estrutura dos usuários que entraram e saíram.
etapaId / nomeEtapa Etapa relacionada à movimentação.
cpfCnpjCliente / nomeCliente Identificação do cliente.
numeroAtividade Número da atividade/pedido.
usuarioEntrou / usuarioSaiu Usuários associados à entrada e à saída.
dataHoraEntrou / dataHoraSaiu Datas e horas da movimentação.
tempo / slaHoras Tempo calculado e SLA da etapa.
tagsAtividade / movimentacao Tags e descrição da movimentação.
nomeConsultor Consultor associado ao pedido.
total / compromissoMensal Valores financeiros do pedido.
pedidoTipo / controlaBko Tipo de pedido e indicador de controle BKO.

O campo id retornado pela consulta não deve ser usado como chave permanente de upsert. Para uma cópia local, use uma chave composta com os campos de negócio necessários, como pedidoId, etapaId, dataHoraEntrou, dataHoraSaiu e movimentacao.

Retorno CSV

O CSV usa UTF-8 com BOM, separador ;, cabeçalho e quebra de linha CRLF.

id;pedidoId;euEntrouId;euSaiuId;etapaId;cpfCnpjCliente;nomeCliente;numeroAtividade;nomeEtapa;usuarioEntrou;usuarioSaiu;dataHoraEntrou;dataHoraSaiu;tempo;slaHoras;tagsAtividade;movimentacao;nomeConsultor;total;compromissoMensal;pedidoTipo;controlaBko

Datas e horas seguem o formato ISO no JSON e são gravadas como texto no CSV. Valores nulos geram células vazias.

Limites e guard

A API de movimentação utiliza os mesmos limites da API de produção, com guard próprio para os pedidos:

Regra Limite padrão
Execuções simultâneas globais 2
Execuções simultâneas por estrutura 1
Intervalo mínimo após 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
Registros por resposta 1.000.000
Tamanho máximo do payload 16 KiB
IDs no campo pedidoIds 10.000

As tentativas recusadas também entram no controle. Quando um limite for atingido, a resposta será 429 com o header Retry-After.

Respostas de erro

HTTP Código Situação
400 PAYLOAD_INVALIDO Campo ausente, data inválida, lista inválida ou tipo de pedido incorreto.
401 TOKEN_INVALIDO Token inexistente ou inválido.
403 ACESSO_NEGADO Usuário ou estrutura inativos.
413 PAYLOAD_GRANDE Payload acima de 16 KiB.
422 LIMITE_REGISTROS Resultado acima de 1.000.000 de movimentações.
429 LIMITE_API Guard ocupado, cooldown ou excesso de tentativas.

Exemplo:

{
  "codigo": "LIMITE_API",
  "mensagem": "Aguarde entre exportações da API.",
  "requestId": "d8e4c3c2-0000-0000-0000-000000000000"
}

Boas práticas

Pedidos (Atividades)

Api Consulta Pedido

A API de Consulta de Pedido permite buscar os dados completos de um pedido pertencente à estrutura autorizada pelo token.

Use esta API para consultar:

Endereço

GET https://api.xeotech.com.br/api/v1/pedidos/{pedidoId}/{token}

O pedidoId é o identificador interno do pedido. O token é informado na URL e não deve ser enviado em cabeçalho ou payload.

Para localizar seu token no Xeotech, acesse a página Meu token.

Autorização e segurança

O token precisa pertencer a um usuário ativo. O usuário também precisa possuir um vínculo ativo com uma estrutura ativa.

A API obtém a estrutura diretamente do usuário autenticado. O cliente não envia estruturaId.

pedido.id = pedidoId
AND estrutura_usuario.estrutura_id = estruturaIdDoUsuario

Se o pedido não existir ou pertencer a outra estrutura, a API retorna 404. Essa resposta evita revelar a existência de pedidos de outras estruturas.

Payload

O GET não possui payload. Todos os dados necessários estão na URL:

Parâmetro Obrigatório Descrição
pedidoId Sim ID interno numérico do pedido.
token Sim Novo token de integração do usuário, informado na URL.

Exemplo cURL

curl --fail-with-body --location \
  --request GET \
  'https://api.xeotech.com.br/api/v1/pedidos/123456/SEU_TOKEN' \
  --header 'Accept: application/json' \
  --output pedido-123456.json

Retorno JSON

O retorno utiliza o formato PedidoApiDTO. A entidade JPA não é serializada diretamente.

{
  "id": 123456,
  "numero": "49565585",
  "pedidoTipo": "COMERCIAL",
  "tipoNegociacao": "NOVO",
  "dataCadastro": "2026-09-30",
  "dataHoraAtualizacao": "2026-09-30T14:32:10",
  "dataHoraUltimaMov": "2026-09-30T14:31:55",
  "total": 149.90,
  "compromissoMensal": 99.90,
  "nomeConsultorOperadora": "Consultor Exemplo",
  "numeroPedidoOrigem": null,
  "numeroPedidoVinculado": null,
  "numeroSimulacao": "SIM-10001",
  "complementos": null,
  "notasFiscais": null,
  "loginOperadora": null,
  "percentualTroca": null,
  "tags": "#PRIORIDADE",
  "clusterOrigem": null,
  "cotacao": null,
  "codigoPortabilidade": null,
  "observacaoProposta": null,
  "dataRetornoFuturo": null,
  "percentualDesconto": null,
  "observacao": null,
  "aparelhoCartaoCredito": false,
  "cliente": {
    "id": 9876,
    "cpfCnpj": "12345678000199",
    "nome": "Empresa Exemplo Ltda.",
    "cep": "89800000",
    "logradouro": "Rua Principal",
    "numero": "100",
    "complemento": null,
    "bairro": "Centro",
    "cidade": "Balneário Camboriú",
    "estado": "SC",
    "tags": null
  },
  "etapa": {
    "id": 44501,
    "nome": "ENVIADO BKO",
    "ativo": true,
    "sincronizavel": true,
    "editavel": false,
    "pedidoTipo": "COMERCIAL",
    "slaHoras": 0
  },
  "usuarioProprietario": {
    "id": 321,
    "nome": "Consultor Exemplo",
    "login": "consultor",
    "tags": "#PRIORIDADE,#VIP",
    "equipe": {
      "id": 12,
      "nome": "Equipe Comercial"
    },
    "ativo": true
  },
  "itens": [
    {  
      "id": 629534248,
      "numero": "47991370111",
      "quantidade": 1,
      "valorUnitario": 99.99,
      "dataReferencia": "2026-09-30",
      "dataPortabilidade": "2026-09-30",
      "dataInstalacao": "2026-09-30",
      "cepInstalacao": "88330484",
      "logradouroInstalacao": "R 1822",
      "numeroInstalacao": "400",
      "bairroInstalacao": "Centro",
      "complInstalacao": "sl 1901",
      "cidadeInstalacao": "Balneario Camboriu",
      "estadoInstalacao": "SC",
      "operadoraCedente": "TIM",
      "nomeCedente": "Sebastião Barbosa",
      "cpfCnpjCedente": "45935282917",
      "telefoneCedente": "47991917979",
      "emailCedente": "xeotechoficial@gmail.com",
      "produto": {
        "id": 18272,
        "nome": "iPHONE 18",
        "descricao": "iPHONE 18",
        "valor": 12319.00,
        "categoria": "APARELHO"
      }
    }      
  ]
}

Campos do pedido

Grupo Campos
Identificação id, numero, pedidoTipo, tipoNegociacao, numeroPedidoOrigem, numeroPedidoVinculado, numeroSimulacao
Datas dataCadastro, dataHoraAtualizacao, dataHoraOperadora, dataHoraUltimaMov, dataRetornoFuturo
Valores total, compromissoMensal, valorFaturaOrigem, percentualTroca, percentualDesconto
Operação nomeConsultorOperadora, loginOperadora, atividades, clusterOrigem, cotacao, codigoPortabilidade, leadSistema
Observações complementos, notasFiscais, observacao, observacaoProposta, tags, aparelhoCartaoCredito, revisao

Cliente, etapa e consultor

O objeto cliente retorna identificação e endereço comercial. Campos de senha, login de conta online e demais credenciais não fazem parte do retorno.

O objeto etapa informa somente id, nome, ativo, sincronizavel, editavel, pedidoTipo e slaHoras. O objeto origem informa a origem do pedido. O objeto usuarioProprietario informa o usuário proprietário, suas tags, equipe e o indicador ativo do vínculo com a estrutura.

Itens e produtos

O campo itens retorna uma lista dos itens associados ao pedido. Os campos podem variar conforme o tipo de item, mas somente campos públicos e controlados são exportados, como:

Limites e guard

O GET utiliza o mesmo guard da API de pedidos. Embora a consulta retorne somente um pedido, a autenticação e o controle de concorrência continuam protegidos.

Regra Limite padrão
Execuções simultâneas globais 2
Execuções simultâneas por estrutura 1
Intervalo mínimo após 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

As tentativas recusadas também entram no controle. Quando um limite for atingido, a resposta será 429 com o header Retry-After.

Respostas de erro

HTTP Código Situação
401 TOKEN_INVALIDO Token inexistente, vazio ou inválido.
403 ACESSO_NEGADO Usuário ou estrutura inativos.
404 PEDIDO_NAO_ENCONTRADO Pedido inexistente ou que não pertence à estrutura do token.
429 LIMITE_API Guard ocupado, cooldown ou excesso de tentativas.

Exemplo de erro:

{
  "codigo": "PEDIDO_NAO_ENCONTRADO",
  "mensagem": "Pedido não encontrado para esta estrutura.",
  "requestId": "d8e4c3c2-0000-0000-0000-000000000000"
}

Boas práticas

Pedidos (Atividades)

Api Movimentação de Etapa de Atividade

A API de movimentação de etapa permite mover uma ou várias atividades para outra etapa do funil, respeitando as mesmas regras de segurança, permissões, hierarquia e histórico utilizadas no Xeotech.

Essa operação não altera diretamente o pedido sem controle. Ela executa o processo de movimentação, registra o histórico e valida as regras da atividade.

Endereço

POST https://api.xeotech.com.br/api/v1/pedidos/alterar-etapa/{token}

O token é informado na URL. Não envie o token no payload.

Autorização e estrutura

O token precisa pertencer a um usuário ativo, com vínculo ativo em uma estrutura ativa. A estrutura é obtida automaticamente pelo vínculo do usuário; não é possível informar estruturaId no payload.

A etapa de destino é localizada pelo Xeotech usando:

Payload

{
  "numerosAtividades": ["49565585", "49565586"],
  "pedidoTipo": "COMERCIAL",
  "nomeEtapa": "ATIVO"
}
Campo Obrigatório Descrição
numerosAtividades Sim Lista com 1 a 50 números de atividades. Envie os números como texto, mesmo quando forem numéricos. Não pode haver repetição.
pedidoTipo Sim Aceita COMERCIAL ou POS_VENDA.
nomeEtapa Sim Nome exato da etapa ativa cadastrada para o tipo de pedido e estrutura do token.

O payload aceita somente esses três campos. Campos desconhecidos, números vazios, duplicados ou acima de 50 atividades são rejeitados.

Header obrigatório

Idempotency-Key: alteracao-etapa-20261001-0001

A chave deve conter de 16 a 64 caracteres usando letras, números, hífen ou sublinhado.

Use a mesma chave somente para repetir exatamente a mesma operação. A chave é controlada por usuário, atividade e payload. Não reutilize uma chave para outra etapa ou outro pedido.

Regras de processamento

Permissões

Permissão Quando é necessária
PAINEL_ATIVIDADE_ETAPA_CHANGE Obrigatória em todas as chamadas, inclusive para uma única atividade. A permissão KANBAN_ETAPA_CHANGE sozinha não autoriza esta API.
ATIVIDADE_ALTERACAO_EM_LOTE Obrigatória quando o payload contém mais de uma atividade.
ATIVIDADE_MOVER_NAO_EDITAVEIS Necessária para sair de uma etapa não editável.
MOVER_ATIVIDADE_PARA_NAO_EDITAVEIS Necessária para entrar em uma etapa não editável que não esteja no Kanban do solicitante.
MOVER_SEM_ESTAR_NO_KANBAN Necessária quando a etapa atual da atividade não está no Kanban do solicitante.
MOVER_ATIVIDADE_FORA_KANBAN Necessária quando a etapa de destino não está no Kanban do solicitante.
IGNORAR_HIERARQUIA Permite ignorar a validação de hierarquia, conforme as regras do usuário.

As permissões de Kanban e de etapas não editáveis são cumulativas. Por exemplo, mover uma atividade de uma etapa não editável fora do Kanban para outro destino não editável fora do Kanban exige as quatro permissões específicas, além das permissões gerais da operação.

Exemplo cURL

curl --fail-with-body --location \
  --request POST \
  'https://api.xeotech.com.br/api/v1/pedidos/alterar-etapa/SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: alteracao-etapa-20261001-0001' \
  --data '{
    "numerosAtividades": ["49565585", "49565586"],
    "pedidoTipo": "COMERCIAL",
    "nomeEtapa": "ATIVO"
  }'

Retorno

A resposta informa o resultado individual de cada atividade. O HTTP 200 indica que o lote foi processado; verifique os campos sucessos, falhas e resultados.

{
  "requestId": "d8e4c3c2-0000-0000-0000-000000000000",
  "total": 2,
  "sucessos": 1,
  "falhas": 1,
  "resultados": [
    {
      "numeroAtividade": "49565585",
      "pedidoId": 49565585,
      "sucesso": true,
      "codigo": "ETAPA_ALTERADA",
      "mensagem": "Etapa alterada com sucesso."
    },
    {
      "numeroAtividade": "49565586",
      "pedidoId": null,
      "sucesso": false,
      "codigo": "FORMULARIO_VINCULADO",
      "mensagem": "Esta atividade possui formulário vinculado à etapa atual. Realize a movimentação pela tela do sistema."
    }
  ]
}
Campo Descrição
requestId Identificador da requisição para rastreamento no suporte.
total Total de atividades recebidas.
sucessos Quantidade de atividades alteradas ou processadas sem erro.
falhas Quantidade de atividades recusadas ou com erro.
numeroAtividade Número enviado no payload.
pedidoId ID interno do pedido, quando localizado.
sucesso Indica se a atividade foi processada com sucesso.
codigo Código estável do resultado, como ETAPA_ALTERADA, SEM_ALTERACAO ou FORMULARIO_VINCULADO.
mensagem Descrição do resultado.

Limites e guard

A alteração de etapa reutiliza o pedidoApiGuard da API de pedidos. Os limites são aplicados antes da autenticação e durante o processamento.

Regra Limite padrão
Execuções simultâneas globais 2
Execuções simultâneas por estrutura 1
Intervalo mínimo após 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
Tamanho máximo do payload 16 KiB
Atividades por requisição 50

Quando um limite for atingido, a API retorna 429 e informa o tempo de espera no header Retry-After. O guard em memória é controlado por instância da aplicação; a idempotência é garantida pelo banco de dados.

Principais erros

HTTP Código Situação
400 PAYLOAD_INVALIDO ou CHAVE_INVALIDA Payload inválido ou ausência de uma chave de idempotência válida.
401 TOKEN_INVALIDO Token inexistente ou inválido.
403 ACESSO_NEGADO ou SEM_PERMISSAO Usuário, vínculo, estrutura ou permissão indisponível.
404 PEDIDO_NAO_ENCONTRADO Atividade não encontrada na estrutura e no tipo informados.
409 IDEMPOTENCIA_CONFLITO ou NUMERO_AMBIGUO Chave reutilizada com outro payload ou número não exclusivo.
413 PAYLOAD_GRANDE Payload acima de 16 KiB.
422 ETAPA_INVALIDA ou FORMULARIO_VINCULADO Etapa inexistente, ambígua, inativa ou bloqueada por formulário.
429 LIMITE_API Guard ocupado, cooldown ou excesso de tentativas.

Falhas específicas de uma atividade são retornadas dentro de resultados, com HTTP 200 para o lote. Isso inclui ETAPA_ATUAL_FORA_KANBAN, ETAPA_DESTINO_FORA_KANBAN, SEM_PERMISSAO, FORMULARIO_VINCULADO e demais recusas da atividade. Os números HTTP da tabela representam as categorias de erro; não substituem a análise de cada resultado.

Boas práticas

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

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