Cenário 2 — dados saindo do X-Adm por relatório¶

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-25

Aplica-se a: equipe X-Adm (ERP/ZIM) e quem opera a nuvem.

O que é¶

O X-Adm gera relatórios em planilha (XLSX; na Thoms, CSV) e os entrega à nuvem, por agenda ou sob demanda. Na nuvem, um app de planilha do cliente recebe o arquivo, lê cada relatório e grava as tabelas de BI no banco do cliente. O PowerSync distribui o resultado aos apps (painéis de BI).

Diferente do cenário 1, aqui o dado chega em lote: o painel mostra a situação do último relatório recebido, não o que foi gravado há um segundo.

Cliente	Relatórios	Quando	Recebe na nuvem
OnPetro	Relatório 18, margem consolidada, margem do dia, metas, postos, TRR, compras, cota Petrobras	todo dia às 4h e sob demanda	`excel.onpetro.xadm.biz`
Vantroba	Resultado de transporte (abas 10, 20 e 30: período, faturamento, movimento de frota)	sob demanda	`excel.vantroba.xadm.biz`
Thoms	`ProdutosSite.csv` (produtos, preço, estoque, promoção)	de hora em hora, em horário comercial	`webstorm.thoms.xadm.biz` → integrador

flowchart TB
    subgraph cliente["Servidor do cliente"]
        erp["ERP X-Adm<br/>gera os relatórios"]
        tar["Tarefa agendada<br/>ou rotina do ERP"]
    end
    subgraph nuvem["Nuvem X-Adm"]
        xls["excel.&lt;cliente&gt;<br/>app de planilha"]
        pg[("banco do cliente<br/>tabelas bi_*")]
        ps["ps.&lt;cliente&gt;"]
    end
    app["App de BI<br/>bi.&lt;cliente&gt;"]
    erp --> tar
    tar -- "novo: POST do .zip (HTTPS)" --> xls
    tar -. "antigo: cópia por SSH" .-> xls
    xls -- "lê e grava" --> pg
    pg --> ps --> app

Pré-requisitos¶

Banco e PowerSync do cliente prontos (Cliente novo na nuvem, passos 1, 2, 3 e 5 — o integrador não é preciso, exceto na Thoms).
O app de planilha do cliente publicado (ver §Na nuvem).
O token do app de planilha, entregue à equipe X-Adm por canal seguro.

Passos¶

1. Definir os relatórios¶

Cada relatório que a nuvem importa tem um layout combinado: nome das abas, posição das colunas, onde fica o período. O app de planilha reconhece o tipo pelo conteúdo do arquivo — não pelo nome — e rejeita o que não reconhece.

Para incluir um relatório novo (ou mudar colunas de um existente):

A equipe X-Adm manda à nuvem um arquivo real do relatório e diz o que ele representa e com que frequência será gerado.
A nuvem mapeia colunas → tabelas no repo do app de planilha do cliente e publica o app.
Só depois o X-Adm passa a enviar o relatório novo. Arquivo com layout que o app ainda não conhece volta com erro por arquivo (os outros do lote seguem).

Mudou o layout, avise antes

Coluna nova, coluna fora de ordem ou aba renomeada no relatório quebra a leitura. Toda mudança de layout no X-Adm precisa de aviso prévio à nuvem.

O mapeamento de cada cliente — relatório, colunas e tabela de destino — está no repo do app: OnPetro · Vantroba · Thoms.

2. Montar o lote¶

O envio é sempre um .zip. O .zip é o lote: tudo o que foi gerado naquele ciclo vai junto.

OnPetro e Vantroba: .zip com 1 ou mais .xlsx (formato .xls antigo não é aceito).
Thoms: .zip com exatamente um ProdutosSite.csv — separador ;, decimal com vírgula, cabeçalho CODIGO;NOME;ATRIBUTO;VALOR;ESTOQUE;STATUS;PESO;PROMOCAO;INI PROMOCAO;FIM PROMOCAO;EAN13.
Limite de 50 MB por .zip.
Não coloque arquivos temporários do Excel (~$…) no .zip.

3. Lado do X-Adm: gerar e enviar os relatórios¶

No servidor do cliente, o ciclo é disparado de dois jeitos:

tarefa agendada (Agendador de Tarefas do Windows), no horário do cliente — 4h na OnPetro, de hora em hora na Thoms;
processo no ERP, que o usuário dispara sob demanda (OnPetro e Vantroba).

Os dois fazem a mesma coisa: o ERP gera os relatórios, e eles seguem para a nuvem por um de dois transportes.

Transporte novo — envio direto por HTTPS (recomendado)¶

Um POST com o .zip para o app de planilha:

curl -sS -X POST "https://excel.<cliente>.xadm.biz/api/xls/processar" \
  -H "Authorization: Bearer <token do app de planilha>" \
  -F "arquivo=@./lote.zip;type=application/zip"

Na Thoms o endereço é https://webstorm.thoms.xadm.biz/api/csv/processar, com o mesmo envio (campo arquivo, Bearer); a resposta é 202 com { "loteId", "recebidos", "status": "processando" }.

Em PowerShell (Windows 10+ já traz o curl.exe):

curl.exe -sS -X POST "https://excel.<cliente>.xadm.biz/api/xls/processar" `
  -H "Authorization: Bearer $env:XLS_TOKEN" `
  -F "arquivo=@C:\xadm\relatorios\lote.zip;type=application/zip"

A resposta chega na hora — o processamento continua em segundo plano — e diz, por arquivo, o que aconteceu:

{
  "conjuntoId": "zip-3f5a…",
  "total": 2,
  "itens": [
    { "nome": "relatorio18.xlsx", "id": 41, "httpStatus": 202, "tipoArquivo": "RELATORIO18", "mensagem": "Processamento agendado" },
    { "nome": "postos.xlsx",      "id": 42, "httpStatus": 200, "tipoArquivo": "POSTOS",      "mensagem": "Duplicado" }
  ]
}

Resposta	Significa	O que fazer
`202` no envio	lote recebido	nada — acompanhar pelo painel
item `202`	arquivo na fila de processamento	—
item `200`	arquivo idêntico já processado antes	nada: reenviar o mesmo arquivo é seguro e não duplica
item `409`	o mesmo arquivo ainda está sendo processado	nada
item `400`	arquivo não reconhecido (layout, formato)	conferir o relatório; ver o passo 1
`400` no envio	`.zip` vazio, corrompido ou sem planilha	refazer o `.zip`
`401`	token ausente ou errado	conferir o token com a nuvem
sem resposta / `5xx`	rede ou nuvem fora	tentar de novo — é seguro

Contrato completo, com exemplos em Python e PowerShell: API do app de planilha — OnPetro · Vantroba · manual de envio (OnPetro).

Transporte antigo — cópia por SSH¶

Ainda em uso onde o processo do ERP copia os relatórios para o servidor da nuvem por SSH. Os clientes devem migrar para o envio direto (acima): ele devolve na hora o resultado por arquivo, e o SSH não.

A preencher

clientes que ainda usam o SSH: <PLACEHOLDER>;
servidor de destino, usuário e forma de autenticação (chave SSH): <PLACEHOLDER>;
pasta de destino e padrão de nome dos arquivos: <PLACEHOLDER>;
quem pega o arquivo na nuvem e o entrega ao app de planilha (serviço, agenda): <PLACEHOLDER>;
o que acontece com o arquivo depois de processado: <PLACEHOLDER>.

Para migrar um cliente do SSH para o envio direto: trocar, no script da tarefa agendada, o comando de cópia pelo curl acima; entregar o token do app de planilha; rodar uma vez manualmente e conferir no painel (§Verificação); só então retirar o acesso SSH do cliente.

4. Na nuvem: o app de planilha¶

Cada cliente tem o seu app (a leitura de cada relatório é específica do cliente):

Cliente	App (slug)	Endereço	Tabelas que grava
OnPetro	`onpetro-xls`	`excel.onpetro.xadm.biz`	`bi_movimento`, `bi_meta`, `bi_compra`, `bi_posto`, `bi_trr`, `bi_cota_petrobras`, `bi_custo_inventario` e cadastros (`bi_filial`, `bi_cliente`, `bi_vendedor`, `bi_produto`, `bi_fornecedor`)
Vantroba	`vantroba-xls`	`excel.vantroba.xadm.biz`	`bi_faturamento`, `bi_movimento`
Thoms	`thoms-webstorm`	`webstorm.thoms.xadm.biz`	compara com o envio anterior e manda só o que mudou ao integrador (`estoque`)

O que o app faz com cada lote:

Guarda o .zip recebido (arquivo de armazenamento arquivo-api.xadm.biz) e registra cada arquivo com a sua impressão digital (SHA-256) — é assim que reconhece arquivo repetido.
Reconhece o tipo de cada planilha pelo conteúdo e lê o período de dentro dela.
Processa um arquivo por vez, em segundo plano, e grava as tabelas bi_* do período.
Ao fechar o lote, manda um resumo no Telegram do cliente.
O PowerSync leva as tabelas bi_* aos painéis.

Apps de planilha não passam pelo integrador: gravam direto no banco do cliente. Criar um app de planilha para cliente novo é projeto de desenvolvimento (novo repo) — siga o checklist de app novo; o deploy segue o mesmo molde dos existentes (deploy do onpetro-xls).

Thoms: CSV de produtos pelo integrador¶

Na Thoms o relatório alimenta o espelho do X-Adm, não tabelas de BI: o app webstorm.thoms compara o CSV com o anterior e envia só os produtos que mudaram ao integrador (PUT/DELETE /api/v1/xadm em int.thoms.xadm.biz, como o cenário 1). O integrador então avisa o app, que publica os produtos na loja virtual do parceiro (WebStorm).

É uma ponte temporária: quando o X-Adm da Thoms passar a enviar em tempo real (cenário 1), o CSV sai. Se o CSV de hora em hora parar de chegar, o app avisa por conta própria (monitor de silêncio, tela /admin/monitor). Runbook: implantação thoms-webstorm.

Verificação¶

Conferir	Como	Esperado
Lote recebido	resposta do `POST`	`202` com um item por arquivo
Arquivo processado	tela Processamentos do app (`https://excel.<cliente>.xadm.biz/processamentos`, login Google) ou `GET /api/comercial/processamentos/{id}` (OnPetro) · `GET /api/transporte/processamentos/{id}` (Vantroba)	`SUCESSO`
Lote fechado	Telegram do cliente	um resumo do lote
Painel atualizado	app `bi.<cliente>.xadm.biz`	números do período enviado
Thoms	tela `https://webstorm.thoms.xadm.biz/admin/monitor`	último CSV recebido há menos de ~60 min, no horário comercial

Problemas comuns¶

Sintoma	Causa provável	O que fazer
Item `400` "tipo não reconhecido"	layout do relatório mudou ou é outro relatório	comparar com o arquivo de referência; ver o passo 1
Item `200` "duplicado" e painel não mudou	o ERP gerou o mesmo arquivo de novo (mesmo conteúdo)	conferir se o relatório foi gerado com o período certo
Processamento `ERRO`	dado inesperado na planilha	abrir o log do processamento na tela Processamentos
Painel com dado antigo, processamento `SUCESSO`	PowerSync atrasado ou app sem sincronizar	resetar a replicação
Nenhum lote chega	tarefa agendada parada ou falhando no servidor do cliente	conferir o Agendador de Tarefas e o log do script