# 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:

- 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.](https://ajuda.xeotech.com.br/books/apis-de-integracao/page/meu-token-para-proprietarios)

## 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"
}
```

<table id="bkmrk-campo-obrigat%C3%B3rio-de"><thead><tr class="header"><th>Campo</th><th style="text-align: right;">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr class="odd"><td>`painelId`</td><td style="text-align: right;">Sim</td><td>ID do Painel de Produção que será consultado.</td></tr><tr class="even"><td>`dataHoraInicioCarga`</td><td style="text-align: right;">Sim</td><td>Início do período, no formato `yyyy-MM-dd HH:mm:ss`.</td></tr><tr class="odd"><td>`dataHoraFimCarga`</td><td style="text-align: right;">Não</td><td>Fim do período. Se omitido, o Xeotech usa o horário de recebimento da requisição.</td></tr><tr class="even"><td>`formato`</td><td style="text-align: right;">Não</td><td>`json` ou `csv`. O padrão é `json`.</td></tr></tbody></table>

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

[![image.png](https://ajuda.xeotech.com.br/uploads/images/gallery/2026-09/scaled-1680-/oYeimage.png)](https://ajuda.xeotech.com.br/uploads/images/gallery/2026-09/oYeimage.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.

<table id="bkmrk-campo-descri%C3%A7%C3%A3o-meta"><thead><tr><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr><td>`meta`</td><td>Versão, painel, operação, fuso, horário de recebimento (`recebidoEm`) e período utilizado.</td></tr><tr><td>`dados`</td><td>Lista de registros. Retorna `[]` quando não houver resultados.</td></tr><tr><td>`totalRegistros`</td><td>Quantidade de linhas retornadas, não a soma do campo `quantidade`.</td></tr></tbody></table>

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:

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

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**.

<table id="bkmrk-regra-limite-padr%C3%A3o-"><thead><tr class="header"><th>Regra</th><th style="text-align: right;">Limite padrão</th></tr></thead><tbody><tr class="odd"><td>Exportações simultâneas globais</td><td style="text-align: right;">2</td></tr><tr class="even"><td>Exportações simultâneas por estrutura</td><td style="text-align: right;">1</td></tr><tr class="odd"><td>Intervalo mínimo após uma execução</td><td style="text-align: right;">120 segundos</td></tr><tr class="even"><td>Execuções por estrutura</td><td style="text-align: right;">3 a cada 10 minutos</td></tr><tr class="odd"><td>Tentativas por token</td><td style="text-align: right;">20 a cada 60 segundos</td></tr><tr class="even"><td>Tentativas globais</td><td style="text-align: right;">600 a cada 60 segundos</td></tr><tr class="odd"><td>Autenticações simultâneas</td><td style="text-align: right;">8</td></tr><tr class="even"><td>Registros por resposta</td><td style="text-align: right;">1.000.000</td></tr><tr class="odd"><td>Tamanho máximo do arquivo</td><td style="text-align: right;">1 GiB</td></tr><tr class="even"><td>Tamanho máximo do payload</td><td style="text-align: right;">16 KiB</td></tr><tr class="odd"><td>Tempo máximo solicitado para a consulta</td><td style="text-align: right;">600 segundos</td></tr><tr class="even"><td>Tempo máximo de geração da resposta</td><td style="text-align: right;">900 segundos</td></tr></tbody></table>

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

<table id="bkmrk-http-c%C3%B3digo-comum-si"><thead><tr class="header"><th style="text-align: right;">HTTP</th><th>Código comum</th><th>Situação</th></tr></thead><tbody><tr class="odd"><td style="text-align: right;">`400`</td><td>`PAYLOAD_INVALIDO`</td><td>Campo ausente, data inválida ou período incorreto.</td></tr><tr class="even"><td style="text-align: right;">`401`</td><td>`TOKEN_INVALIDO`</td><td>Token inválido.</td></tr><tr class="odd"><td style="text-align: right;">`403`</td><td>`ACESSO_NEGADO`</td><td>Sem acesso ao painel ou às permissões necessárias.</td></tr><tr class="even"><td style="text-align: right;">`413`</td><td>`PAYLOAD_GRANDE`</td><td>Payload maior que 16 KiB.</td></tr><tr class="odd"><td style="text-align: right;">`422`</td><td>`LIMITE_REGISTROS` ou `LIMITE_ARQUIVO`</td><td>Resultado acima dos limites permitidos.</td></tr><tr class="even"><td style="text-align: right;">`429`</td><td>`LIMITE_API`</td><td>Guard ocupado, cooldown ou excesso de tentativas.</td></tr><tr class="odd"><td style="text-align: right;">`504`</td><td>`TEMPO_EXCEDIDO`</td><td>Consulta ou geração excedeu o tempo permitido.</td></tr></tbody></table>

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 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.](https://ajuda.xeotech.com.br/books/apis-de-integracao/page/meu-token-para-proprietarios)

## 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"
}
```

<table id="bkmrk-campo-obrigat%C3%B3rio-de-1"><thead><tr class="header"><th>Campo</th><th style="text-align: right;">Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr class="odd"><td>`painelId`</td><td style="text-align: right;">Sim</td><td>ID do Painel de Produção.</td></tr><tr class="even"><td>`dataInicio`</td><td style="text-align: right;">Sim</td><td>Data inicial no formato `yyyy-MM-dd`.</td></tr><tr class="odd"><td>`dataFim`</td><td style="text-align: right;">Sim</td><td>Data final no formato `yyyy-MM-dd`.</td></tr><tr class="even"><td>`formato`</td><td style="text-align: right;">Não</td><td>`json` ou `csv`. O padrão é `json`.</td></tr></tbody></table>

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 -&gt; PRODUÇÃO -&gt; PAINEL DE PRODUÇÃO[![image.png](https://ajuda.xeotech.com.br/uploads/images/gallery/2026-09/scaled-1680-/h8Oimage.png)](https://ajuda.xeotech.com.br/uploads/images/gallery/2026-09/h8Oimage.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.

<table id="bkmrk-campo-descri%C3%A7%C3%A3o-meta"><thead><tr><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr><td>`meta`</td><td>Versão, painel, operação, fuso, horário de recebimento (`recebidoEm`) e período utilizado.</td></tr><tr><td>`dados`</td><td>Lista de registros. Retorna `[]` quando não houver resultados.</td></tr><tr><td>`totalRegistros`</td><td>Quantidade de linhas retornadas, não a soma do campo `quantidade`.</td></tr></tbody></table>

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.

<table id="bkmrk-condi%C3%A7%C3%A3o-campos-reto"><thead><tr><th>Condição</th><th>Campos retornados</th></tr></thead><tbody><tr><td>Todas as estruturas</td><td>`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`</td></tr><tr><td>Estruturas de telefonia</td><td>`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`</td></tr><tr><td>Vivo</td><td>`cotacao`, `numeroPedidoOrigem`, `codigoPortabilidade`, `numeroProvisorio`, `rpon`, `instancia`</td></tr><tr><td>Claro</td><td>`percentualDesconto`, `variacaoRenovacao`, `faixaRenovacao`, `valorBaseAtual`, `valorAgregado`, `percentualTroca`, `clusterOrigem`, `aparelhoCartaoCredito`, `claroConvergenciaResposta`, `claroTabelaRenovacao`</td></tr></tbody></table>

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

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

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**.

<table id="bkmrk-regra-limite-padr%C3%A3o-"><thead><tr class="header"><th>Regra</th><th style="text-align: right;">Limite padrão</th></tr></thead><tbody><tr class="odd"><td>Exportações simultâneas globais</td><td style="text-align: right;">2</td></tr><tr class="even"><td>Exportações simultâneas por estrutura</td><td style="text-align: right;">1</td></tr><tr class="odd"><td>Intervalo mínimo após uma execução</td><td style="text-align: right;">120 segundos</td></tr><tr class="even"><td>Execuções por estrutura</td><td style="text-align: right;">3 a cada 10 minutos</td></tr><tr class="odd"><td>Tentativas por token</td><td style="text-align: right;">20 a cada 60 segundos</td></tr><tr class="even"><td>Tentativas globais</td><td style="text-align: right;">600 a cada 60 segundos</td></tr><tr class="odd"><td>Autenticações simultâneas</td><td style="text-align: right;">8</td></tr><tr class="even"><td>Registros por resposta</td><td style="text-align: right;">1.000.000</td></tr><tr class="odd"><td>Tamanho máximo do arquivo</td><td style="text-align: right;">1 GiB</td></tr><tr class="even"><td>Tamanho máximo do payload</td><td style="text-align: right;">16 KiB</td></tr><tr class="odd"><td>Tempo máximo solicitado para a consulta</td><td style="text-align: right;">600 segundos</td></tr><tr class="even"><td>Tempo máximo de geração da resposta</td><td style="text-align: right;">900 segundos</td></tr></tbody></table>

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

<table id="bkmrk-http-c%C3%B3digo-comum-si"><thead><tr class="header"><th style="text-align: right;">HTTP</th><th>Código comum</th><th>Situação</th></tr></thead><tbody><tr class="odd"><td style="text-align: right;">`400`</td><td>`PAYLOAD_INVALIDO`</td><td>Campo ausente, data inválida ou período incorreto.</td></tr><tr class="even"><td style="text-align: right;">`401`</td><td>`TOKEN_INVALIDO`</td><td>Token inválido.</td></tr><tr class="odd"><td style="text-align: right;">`403`</td><td>`ACESSO_NEGADO`</td><td>Sem acesso ao painel ou às permissões necessárias.</td></tr><tr class="even"><td style="text-align: right;">`413`</td><td>`PAYLOAD_GRANDE`</td><td>Payload maior que 16 KiB.</td></tr><tr class="odd"><td style="text-align: right;">`422`</td><td>`LIMITE_REGISTROS` ou `LIMITE_ARQUIVO`</td><td>Resultado acima dos limites permitidos.</td></tr><tr class="even"><td style="text-align: right;">`429`</td><td>`LIMITE_API`</td><td>Guard ocupado, cooldown ou excesso de tentativas.</td></tr><tr class="odd"><td style="text-align: right;">`504`</td><td>`TEMPO_EXCEDIDO`</td><td>Consulta ou geração excedeu o tempo permitido.</td></tr></tbody></table>

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.