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:

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; na exportação, depende do tipo da estrutura.

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ÇÃO

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

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 do Relatório de exportação

Endereço base

Autorização

Formatos

Chamada

Payload

cURL — CSV

cURL — JSON

Retornos da API

Retorno do relatório de exportação

Campos calculados e formatos especiais da exportação

Exemplo completo de uma linha de exportação

Formulários e tags

Retorno CSV

Limites de proteção

Respostas de erro

Boas práticas de integração