Pular para conteúdo

Como enviar planilhas para processamento

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-10-02

As planilhas Excel do comercial chegam ao sistema por uma chamada de API — em geral disparada por um job agendado, um script ou o próprio ERP. O envio é sempre um arquivo .zip com as planilhas do ciclo dentro: o .zip é o lote. Você não escolhe o tipo de cada planilha nem informa o período: o sistema reconhece automaticamente se é um relatório de faturamento, de margem, de metas, de postos, de TRR, de compras, a cota Petrobrás ou o FluxoPagarReceber ao ler o conteúdo de cada arquivo.

A Relação de Compras, a Cota Petrobrás e o FluxoPagarReceber também podem ser enviados pela página "Importar XLS", aberta pelo botão de mesmo nome do BI Comercial — veja Pela página Importar XLS.

O que você precisa

  • A URL base do serviço (ex.: https://excel.onpetro.xadm.biz).
  • O token de acesso (Bearer) combinado com o suporte — exigido apenas no envio.
  • Um arquivo .zip contendo de 1 a N planilhas .xlsx. Não é preciso informar período, tipo nem identificação de lote: tudo vem do conteúdo.

Enviando o lote

O envio é um POST para /api/xls/processar, com o .zip no campo arquivo (formato multipart/form-data). É um único envio, mesmo quando o lote tem vários arquivos.

BASE="https://excel.onpetro.xadm.biz"
TOKEN="cole-o-token-combinado-com-o-suporte"

# Monte o .zip com as planilhas do ciclo
zip -j fechamento.zip ./relatorio18_fev2026.xlsx ./postos_fev2026.xlsx

curl -sS -X POST "$BASE/api/xls/processar" \
  -H "Authorization: Bearer $TOKEN" \
  -F "arquivo=@./fechamento.zip;type=application/zip"

O sistema responde na hora dizendo que recebeu o lote (o processamento continua em segundo plano) e devolve, por arquivo do .zip, o número do processamento, o tipo detectado e o que aconteceu com ele:

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

O httpStatus de cada item diz o que houve com aquele arquivo: 202 enfileirado, 200 duplicado (já processado antes), 400/409 não processado. Um arquivo com problema não derruba os outros do lote.

Quando o processamento de todos os arquivos termina, sai uma única notificação do lote — não uma por arquivo. Depois, acompanhe o resultado na tela Processamentos — veja Como acompanhar os processamentos.

Quando der erro, faça isso

O .zip foi recusado: confira se ele tem pelo menos um .xlsx dentro. Um zip vazio, corrompido ou só com outros formatos é rejeitado inteiro.

Um arquivo do lote veio com erro na resposta: confira se é um .xlsx de verdade (não um .xls antigo nem um arquivo temporário do Excel, cujo nome começa com ~$ ou #) e se ele tem uma das planilhas reconhecidas pelo sistema. Um arquivo sem nenhuma coluna reconhecível é rejeitado — mas os demais do lote seguem normalmente.

Um item respondeu "conflito": aquele arquivo já está na fila ou sendo processado. Aguarde terminar e consulte o resultado na tela Processamentos; não é preciso reenviar.

Um arquivo terminou com erro ou foi ignorado: pode reenviar o mesmo arquivo como está. Ele é processado de novo (o item responde 202) — útil depois que o suporte corrige a causa.

O envio respondeu "indisponível" (temporário): o armazenamento de arquivos teve uma indisponibilidade passageira. Aguarde alguns instantes e reenvie o mesmo .zip.

Reenviei um lote que já tinha mandado: sem problema. O sistema reconhece tanto o .zip idêntico quanto cada planilha repetida e não duplica os dados — reenviar só reprocessa o que mudou.

Pela página Importar XLS

No BI Comercial, o botão "Importar XLS" abre a página de importação já com o seu usuário identificado. Escolha um ou mais .xlsx (Relação de Compras, Cota Petrobrás ou FluxoPagarReceber) e clique em Enviar — no máximo uma Cota e um FluxoPagarReceber por envio.

Compras e Cota entram na fila e a página só confirma o recebimento. O FluxoPagarReceber é diferente: a página espera o processamento (até 30 segundos) e mostra o resultado para você conferir com o Excel:

  • "Posição 28/09/2026 — passou a ser a posição atual" — o arquivo virou a foto que o BI mostra. Também pode aparecer "entrou no histórico (já existe posição mais recente de …)", quando você envia um arquivo mais antigo que o atual, ou "substituiu a importação anterior desta posição".
  • "A pagar: N títulos · R$ X · vencido R$ Y" e o mesmo para a receber — confira com os totais do relatório.
  • Avisos, quando houver: centros de custo novos, filiais cadastradas sem município (peça ao suporte para completar o cadastro) ou "Total a receber … difere do Total do ERP (aba Grupo)" — o arquivo foi gravado, mas vale avisar o suporte.

Se o arquivo tiver problema, nada é gravado e a página diz o motivo:

"Arquivo recusado — nada foi gravado." Vem com a causa: a aba Fluxo Pagar-Receber-SemQuebras não está no arquivo, a data de posição não foi encontrada, ou a lista das linhas com problema (ex.: linha 312: vencimento '31/02/26' inválido). Gere o relatório de novo no ERP e reenvie; se o arquivo estiver certo, chame o suporte.

"Falha ao processar o arquivo — a equipe foi avisada": problema do nosso lado. Tente reenviar mais tarde — o mesmo arquivo pode ser enviado de novo.

"Ainda processando": o arquivo demorou mais que o normal. Ele continua sendo processado; a posição nova aparece no BI assim que terminar.

Reenviei o mesmo arquivo: a página mostra o resultado da importação original, com "(importado em …)", sem gravar de novo.

Para o contrato técnico completo (todos os campos, códigos de resposta e exemplos em outras linguagens), veja a Referência da API.