Integração de vendas com o Protheus

Última atualização: 31/08/2026 Responsável funcional: administração comercial
Responsável técnico: operação da API

Objetivo

Receber os movimentos de venda das lojas, persistir notas e itens sem duplicidade, associar vendedores, atualizar totais diários e identificar alterações que precisam de validação humana.

O administrador pode manter URL, endpoint, usuário e token/senha em Configurações > Integrações. O segredo é criptografado no banco e nunca é devolvido pela API ou exibido após o salvamento. As variáveis de ambiente da API permanecem como fallback. Esta documentação não registra o valor da credencial.

Configuração técnica

Para cada consulta, a API envia CNPJ, data inicial e data final nos cabeçalhos esperados pelo serviço de origem e lê o array Movimentos.

Embora a tela use o rótulo Token / senha, o serviço atual autentica por Basic Auth com usuário:credencial. A chave de criptografia deve ser estável entre reinícios; quando ausente, a API usa JWT_ACCESS_SECRET como fallback técnico.

Atualização da credencial pelo administrador

1. Abra Configurações > Integrações e mantenha a fonte Protheus ativa.
2. Revise URL, endpoint e usuário.
3. Informe o novo token/senha. O valor atual nunca é preenchido no campo.
4. Clique em Testar conexão. O teste consulta um CNPJ ativo sem salvar o valor.
5. Somente após o teste retornar sucesso, clique em Salvar credencial.

Salvar registra auditoria sem incluir o token. Alterar qualquer campo invalida o teste anterior e exige uma nova validação.

Agendamentos

Com a sincronização habilitada, a API verifica o relógio a cada minuto e executa:

Valores padrão:

• revisão diária às 23:30;
• janela retroativa de 7 dias;
• fechamento no dia 1, às 02:15;
• fuso America/Sao_Paulo.

O administrador pode alterar a janela, o horário diário, o dia e o horário de fechamento em Configurações > Parâmetros.

Sincronização manual

Em Configurações > Integrações > Fonte de dados, escolha Protheus, informe o intervalo e, opcionalmente, a lista de CNPJs. A ação chama:

POST /api/v1/integrations/protheus/sync

{
  "dateFrom": "2026-07-01",
  "dateTo": "2026-07-23",
  "cnpjs": ["00000000000000"]
}

Quando cnpjs não é enviado, são usados os CNPJs configurados no ambiente.

Processamento

1. É criado um log de integração com estado em execução.
2. Cada CNPJ é consultado no período solicitado.
3. A loja é localizada por CNPJ ou código; quando necessário, é criada.
4. O vendedor é localizado por CPF e depois por loja + código PDV. Quando não há correspondência, a nota segue para o Validador NF sem criar funcionário.
5. A chave documental da nota identifica a venda.
6. Itens e totais são normalizados e persistidos.
7. A validação diária da loja e do vendedor é recalculada.
8. O log recebe contagens, falhas, horário de conclusão e resultado final.

Uma repetição do mesmo período deve ser idempotente: a nota conhecida é atualizada ou comparada, não criada novamente como outra venda.

Divergências de NF

Quando uma nota conhecida retorna com conteúdo diferente, o sistema compara o snapshot anterior com o recebido. Podem ser sinalizados:

• vendedor ausente;
• valor alterado;
• quantidade alterada;
• vendedor alterado;
• data alterada;
• loja alterada.

A alteração não é aplicada silenciosamente. É criada uma pendência em Auditoria > Validador NF.

O responsável pode:

1. conferir dados anteriores e recebidos;
2. selecionar ou corrigir o vendedor;
3. corrigir data, quantidade e valor;
4. definir se a NF participa de indicadores e metas;
5. registrar uma observação;
6. salvar e validar.

Se a mesma versão já validada voltar da origem, ela é reconhecida e não abre uma nova pendência. Se uma versão pendente for substituída por outra, a anterior fica SUPERSEDED.

Inclusão nos indicadores

• Ativada: a NF compõe vendas, dashboard, atingimento e relatórios.
• Desativada: a NF permanece no histórico analítico, porém com includedInMetrics=false, sem participar das agregações comerciais.

Toda decisão registra usuário, data, estado anterior, estado resolvido e auditoria.

Carga histórica

Períodos longos devem ser divididos em intervalos pequenos para limitar o impacto de falhas na origem:

GV_API_BASE_URL=http://127.0.0.1:3000/api/v1 \
GV_API_EMAIL=usuario@empresa.com \
GV_API_PASSWORD='senha-em-variavel-segura' \
npm run sync:protheus:period -- \
  --from 2026-04-01 \
  --to 2026-07-31 \
  --chunk-days 3 \
  --output reports/protheus-sync-2026-04-01-2026-07-31.json

O script:

• autentica na API do GV - Gestor de Vendas;
• divide o intervalo;
• interrompe se uma janela ou CNPJ falhar;
• registra contagens em JSON;
• permite limitar CNPJs com --cnpjs.

Antes de reset ou carga histórica, faça backup do PostgreSQL e registre o nome do arquivo no chamado ou ata da operação.

Monitoramento

Verificações diárias:

1. Abra Configurações > Integrações.
2. Confirme que o agendador está ativo.
3. Confira a última execução, período, quantidade de movimentos e falhas.
4. Se houver erro de autenticação, teste a credencial antes de salvá-la.
5. Verifique pendências no Validador NF.
6. Compare amostras no Relatório Analítico de vendas.

Endpoints de apoio:

• GET /integrations/protheus/status;
• GET /integrations/protheus/logs;
• POST /integrations/protheus/test-connection;
• POST /integrations/protheus/logs/:id/reprocess;
• POST /integrations/protheus/logs/reprocess-failed;
• GET/PATCH /settings/protheus-credentials;
• GET /integrations/data-source/logs.

Diagnóstico de divergência com relatório externo

Use a mesma janela, CNPJs e regra de inclusão nos dois lados. Compare por chave de nota, série, loja, emissão, vendedor, valor e quantidade, nesta ordem:

1. confirme se a execução terminou sem CNPJ em falha;
2. confirme a quantidade bruta de movimentos;
3. confira notas excluídas de indicadores;
4. confira devoluções e valores negativos;
5. confira pendências e versões substituídas no Validador NF;
6. confira vendedores sem vínculo;
7. compare o Analítico de vendas com o arquivo de origem;
8. registre as notas divergentes e seus payloads.

Uma diferença entre API Protheus e extração direta do ERP deve ser tratada como divergência da origem até que a mesma chave documental seja comparada nos dois retornos.

Reprocessamento e falhas

• Falha de autenticação ou rede: o log fica como FAILED; testar e atualizar a credencial em Configurações antes de reprocessar.
• Falha de um CNPJ: reprocessar somente o log ou CNPJ afetado.
• Falhas acumuladas: use Recuperar períodos com erro. O serviço consolida períodos repetidos, executa os menores primeiro e interrompe o lote após três falhas consecutivas.
• Cobertura: a execução registra quantos CNPJs foram solicitados e quantos responderam. Somente allCnpjsSucceeded=true encerra o período como completo.
• Movimento sem vendedor: tratar no Validador NF ou corrigir cadastro/código.
• Loja não reconhecida: conferir CNPJ e código Protheus no cadastro.
• Duplicidade aparente: comparar chave documental e externalId antes de excluir.
• Valor alterado: validar a pendência; não editar diretamente no banco.