Pular para conteúdo

Como enviar planilhas para processamento

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-16

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 ou de TRR ao ler o conteúdo de cada arquivo.

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.

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.

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