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:
fazer uma carga inicial da base;
buscar somente registros atualizados em intervalos posteriores;
receber os dados em JSON ou CSV.
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:
PAINEL_PRODUCAO_VIEW
PAINEL_PRODUCAO_EXPORTACAO
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:
json — recomendado para integrações e sincronização;
csv — UTF-8 com BOM, separador 
;, cabeçalho e quebra de linha CRLF. Na carga, o cabeçalho é fixo e segue os 80 campos listados nesta página.
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
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
Use JSON quando precisar preservar tipos, datas, nulos e valores numéricos.
Use CSV quando a carga for consumida por ferramentas de análise ou planilhas.
Salve o arquivo em uma área temporária e só confirme a carga depois de validar o HTTP 200, o 
Content-Length e o 
X-Total-Registros.
Na carga, faça 
upsert usando o ID estável da linha. A exportação é um relatório sem esse ID.
Na carga, mantenha o último intervalo confirmado e use pequenas sobreposições entre chamadas.
Faça uma reconciliação completa periódica para tratar exclusões e mudanças que não atualizaram o pedido.
Respeite o 
Retry-After e não repita imediatamente uma resposta 
429.
Nunca registre o token completo em logs.