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.

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

Api de Carga da Produção

Endereço base

Autorização

Formatos

Chamada

Payload

cURL — JSON

cURL — CSV

Carga inicial e cargas seguintes

Retornos da API

Retorno da carga

Limites de proteção

Respostas de erro

Boas práticas de integração