Validador de Pedidos — GoCase

Automação que atua como filtro de qualidade entre a captação de pedidos e o chão de fábrica: lê a planilha de pedidos, barra o que está inconsistente explicando o motivo, prioriza o que é válido pelo aperto do prazo e ainda tenta recuperar automaticamente, com IA, os pedidos que foram barrados.

Business case para o processo seletivo de Estágio em RPA na GoCase (GoGroup). Área de negócio: Operações de Fábrica.

Serviço no ar: https://validador-pedidos-gocase.onrender.com

O problema

Na produção sob demanda, cada pedido vira uma ordem de produção física. Um pedido com dado quebrado não é só um registro errado — é material personalizado gasto, hora-máquina perdida e cliente sem receber.

Os pedidos chegam de vários canais (site, marketplace, B2B, loja física), cada um com um nível diferente de validação na origem. O resultado é uma planilha onde convivem pedidos perfeitos e pedidos com cliente sem nome, e-mail quebrado, quantidade zerada, valor que não fecha, prazo vencido ou duplicidade.

Conferir isso à mão é lento, cansativo e deixa passar erro sutil — uma diferença de centavos, uma duplicata separada por dezenas de linhas.

Related MCP server: fcp-sheets

Como o operador usa

1. Abre o formulário no navegador.

2. Sobe a planilha .xlsx.

3. Recebe de volta um .zip com as três planilhas prontas.

Nada é instalado na máquina de ninguém: o processamento roda no servidor e o resultado volta pelo navegador.

O formulário é publicado pelo fluxo n8n, que acompanha o projeto em integracoes/ e é importado uma única vez. Quem não utiliza n8n pode consumir a API diretamente — o contrato está no mesmo guia.

Para experimentar sem preparar dados, o repositório inclui exemplo/pedidos_exemplo.xlsx: 50 pedidos, dos quais 10 contêm defeitos representativos dos que ocorrem na operação.

Primeira execução do dia. O serviço está hospedado em plano gratuito e hiberna após alguns minutos sem uso. A primeira chamada leva cerca de 50 segundos para acordar o servidor; as seguintes respondem em menos de 1 segundo. Se o fluxo acusar tempo esgotado na primeira tentativa, basta repetir.

Resultado medido

Lote de 50 pedidos, com 10 problemas reais:

Regras de validação

Cada pedido é avaliado contra todas as regras. Um pedido pode acumular vários motivos, concatenados na coluna motivo_rejeicao — a gestão vê a lista completa de problemas de uma vez, não um erro por reprocessamento.

Prioridade de produção

Os aprovados recebem dias_restantes e entram numa fila ordenada por urgência — os mais apertados primeiro.

O que é entregue

Camada de IA — recuperação de pedidos reprovados

Barrar pedido resolve metade do problema. A outra metade é recuperá-lo.

A divisão de trabalho é explícita:

• Erro mecânico (valor que não fecha, espaço sobrando, e-mail a normalizar) → resolvido por regra, sem IA.

• Erro semântico (nome faltando, e-mail incompleto) → a IA infere cruzando os outros campos do próprio pedido.

• Dado impossível de deduzir → sinalizado para revisão humana, nunca inventado.

O que a IA corrigiu na execução real

O que ela corretamente não resolveu

Dos 10 reprovados, 5 permaneceram — e é assim que deve ser:

• 2 duplicatas — exigem decisão humana sobre qual pedido vale.

• 1 prazo vencido — não é erro de dado, é problema operacional.

• 2 valores incoerentes — a IA ajustou a quantidade, mas o valor_total não fechou, então o pedido continuou reprovado. A validação não abre exceção para a IA.

Trilha de auditoria

Correção automática só é confiável se for auditável. A IA assina o que fez, dentro das planilhas entregues:

• Coluna corrigido_por_ia marca os pedidos recuperados.

• Coluna correcao_ia registra o antes → depois de cada campo alterado.

• O resumo traz a linha "Pedidos recuperados pela IA".

Deduzir o nome a partir do e-mail é uma inferência plausível, não um dado confirmado. Por isso a trilha existe: a IA acelera a recuperação e a decisão final continua conferível por uma pessoa.

Arquitetura

Responsabilidade única por módulo — cada arquivo faz uma coisa e é testável isoladamente.

Fonte única de verdade. O fluxo vive em executar_pipeline; as métricas são montadas uma vez e reaproveitadas pelo relatório, pelo log e pela API. Nomes, ordem e cores das faixas de prioridade existem apenas no config.yaml.

Tecnologias

Python 3.10+ · pandas e openpyxl (planilhas) · FastAPI e uvicorn (API HTTP) · PyYAML (configuração externa) · httpx (chamada à IA) · MCP (integração com clientes de IA) · Anthropic Claude (correção assistida) · n8n (orquestração low-code) · Render (hospedagem).

Formas de consumo

Uma lógica de validação, três superfícies — sem regra duplicada.

Conectando o MCP a um cliente de IA

O n8n executa a automação em lote; o MCP permite interrogá-la em linguagem natural — "quantos pedidos foram barrados e por quê?". Para habilitar num cliente compatível (Claude Desktop, por exemplo), aponte-o para o servidor:

{
  "mcpServers": {
    "validador-gocase": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "caminho/para/validador-pedidos-gocase"
    }
  }
}

Ferramentas expostas: validar_pedidos, consultar_resumo, analisar_rejeitados, revalidar_com_correcoes e gerar_dados_exemplo, mais um prompt guia. As duas do meio formam o ciclo de correção assistida: o modelo do próprio cliente propõe as correções e o servidor revalida.

A integração não amarra a ferramenta: por ser HTTP puro, Make, Power Automate ou código próprio consomem a mesma API. O n8n é o caminho documentado e testado, por ser o padrão na GoCase.

Configuração sem código

Regras de negócio ficam fora do código, em config.yaml: tolerância de valor, padrão de e-mail, colunas obrigatórias e as faixas de prioridade (nomes, intervalos e cores). Um gestor ajusta limites sem abrir Python.

Há ainda o mapa_colunas, que traduz os cabeçalhos de um export real do e-commerce/ERP para os nomes esperados — planilha diferente não exige código novo.

Configuração ausente ou inválida não derruba nada: o sistema avisa e usa os padrões embutidos.

Qualidade

testar.py executa 13 verificações de ponta a ponta: geração da planilha, execução do fluxo, existência e conteúdo das 3 planilhas e do log, consistência (aprovados + reprovados = total), presença de motivo em todos os reprovados e o comportamento da API — validação, download do pacote e recusa de planilha fora do formato com erro legível em vez de falha genérica — e o MCP Server, que é exercitado pelo protocolo real: handshake, catálogo de ferramentas e uma ferramenta executada de ponta a ponta.

Outras salvaguardas embutidas: relatório aberto no Excel é tratado com novas tentativas e mensagem clara; correção malformada vinda da IA é descartada sem derrubar o lote; arquivos temporários do servidor expiram sozinhos em 1 hora.

Escopo e evolução

Escopo desta entrega. A API está publicada sem autenticação, por decisão de escopo do business case. A URL deve ser usada apenas com a planilha de demonstração (dados sintéticos); pedidos reais contêm dados pessoais e exigem autenticação por chave antes de trafegar por uma URL aberta. É um passo consciente do roadmap, não um esquecimento.

Evolução natural. Ler os pedidos direto do ERP em vez de planilha; escrever o status de volta no sistema de origem; notificação ativa para a gestão quando o índice de reprovação subir; histórico entre lotes para detectar duplicidade que atravessa execuções.