Todo cadastro que o Acelerador Implantação Bee IT gera precisa parar no Protheus do cliente pra virar realidade fiscal. Essa integração é feita pelo motor U_BEEITSYNC — uma User Function AdvPL homologada que roda dentro do próprio Protheus do cliente, com retry exponencial, circuit breaker stateful, idempotency-key padrão Stripe e o detector de "ok-fake" que a Bee IT desenvolveu ao vivo em produção. Este post é o walk-through do motor + do Painel de Integração que orquestra tudo.

O que é U_BEEITSYNC

Uma User Function (u_BEEITSYNC()) homologada instalada no Repositório do Protheus do cliente. Publicada como WebService REST via rest.h, escuta em endpoint próprio (/BEEIT/sync).

A função é 100% dinâmica — não tem alias hard-coded, não tem campo hard-coded. Ela recebe:

• JSON com alias, filial, campos (dict de field → valor) e flags (dry_run, force_mvc, etc)
• Header Idempotency-Key (evita duplicata)
• Body compatível com qualquer tabela do Protheus

E devolve:

• status (success / error / warning)
• recno (RECNO real gravado)
• message (human-readable)
• raw_body do erro se houver

Como grava — MVC ou RecLock direct

O motor decide a arquitetura de gravação por alias, configurada em protheus_alias_config:

• MVC — usa FwLoadModel, FwFormStruct, SetValue, Commit. Serve pra tabelas modernas com MVC (SF4, SB1, F2A-CJG)
• Direct — usa RecLock + Replace + MsUnlock. Serve pra tabelas mais antigas ou pra rotinas com PE crash-prone (SA1 em versões antigas, SB6)

A escolha de arquitetura foi decidida por Bee IT baseado em testes reais em ambiente do cliente — algumas tabelas parecem MVC mas na verdade tem PE que crasha. Configuração fica em protheus_alias_config no banco Supabase, editável sem redeploy.

Retry exponencial

Em caso de erro, o motor tenta de novo com backoff:

• Tentativa 1 — imediata
• Tentativa 2 — 500ms depois
• Tentativa 3 — 1500ms depois
• Após 3 falhas — abre circuit breaker

Circuit breaker stateful

O CB é persistido no banco (não em memória do worker). 3 estados:

• CLOSED — tudo OK, requests normais
• OPEN — 3 falhas seguidas no mesmo alias, para de enviar por 5 min
• HALF_OPEN — depois de 5 min, envia 1 request de teste. Se sucede, volta pra CLOSED. Se falha, fica OPEN por mais 10 min

Fallback gracioso — usuário vê "aguardando reconexão com Protheus", não erro genérico. E os cadastros pendentes ficam em fila esperando a próxima janela HALF_OPEN.

Idempotency-Key (padrão Stripe)

Toda request tem Idempotency-Key no header (UUID gerado pelo frontend). TTL de 24h no banco. Se o mesmo request chega 2 vezes com mesma key:

• Primeira request: processa normal, salva resultado com a key
• Segunda request: retorna o mesmo resultado da primeira, sem processar de novo

Isso evita duplicar TES/produto/cliente quando o usuário aperta 2× no botão de enviar. Se o body divergir da primeira request (mesmo key mas payload diferente), retorna HTTP 422.

Detector de "ok-fake"

Esse é o detalhe mais valioso do motor. Descoberto em produção real: algumas rotinas do Protheus retornam sucesso mas não gravam. O RECNO vem -1 ou vem repetido de gravação anterior. Sem detecção, o Acelerador achava que tinha enviado 100 TES quando na verdade tinha enviado 0.

O detector faz 2 checks:

• RECNO deve ser > 0
• RECNO não pode ser igual ao RECNO da gravação anterior no mesmo batch

Se detecta ok-fake, marca a request como falha silenciosa e sinaliza no Painel — o consultor sabe que precisa investigar o cliente antes de continuar.

Painel de Integração

O Painel é a tela que orquestra tudo. Você vê:

• Lista de cadastros pendentes de envio (SA1, SA2, SB1, SF4, F2A-CJG, etc)
• Checkbox por linha pra selecionar quais enviar
• Botão "Enviar Selecionados" — batch
• Barra de progresso com contagem (enviados / total)
• Log de erro por linha (se tem)
• Detector de ok-fake ativo

Modo Múltiplo

Você pode selecionar todos os 43 aliases ao mesmo tempo. O motor processa em ordem de dependência (SA1 antes de SF4 se SF4 tem foreign key pra SA1, etc). Envio pode levar 15 a 30 minutos em batch grande, mas é robusto — pode fechar aba e voltar depois.

Dashboard de saúde

Aba Saúde por cliente mostra:

• Uptime do Protheus do cliente nas últimas 24h/7d
• Taxa de sucesso de envio (ideal ≥ 98%)
• Latência média das requests
• Últimos erros por tipo
• Ok-fake detectados

Se tem cliente com Painel amarelo/vermelho, você sabe antes do cliente ligar reclamando.

43 aliases homologados

O motor conhece 43 aliases do Protheus, todos testados em ambiente real:

Novos aliases entram na configuração protheus_alias_config conforme demanda. Adicionar novo alias leva ~1h de trabalho da Bee IT.

Auditoria completa

Cada envio vira entrada em audit_log:

• actor_user_id — quem apertou o botão
• tenant_id — de qual cliente
• alias — qual tabela
• payload_before — dado antes (se atualização)
• payload_after — dado depois
• recno — o RECNO real gravado
• elapsed_ms — quanto tempo levou
• Timestamp + IP

Retenção 5 anos. Cliente enterprise usa isso pra provar em fiscalização que cadastros vieram de origem legítima e foram gravados no momento X.

Um caso real

Migração de cadastro de tenant grande: 300 clientes SA1, 180 fornecedores SA2, 4.200 produtos SB1, 65 TES SF4, 9 cadastros RT (F2A-CJG). Total: ~4750 registros.

Sem motor:

• Envio manual por rotina do Protheus: ~2 h por 100 registros × 48 = ~96 h
• Retrabalho por duplicata ou ok-fake: ~15 h
• Total: ~111 h

Com motor:

• Envio Modo Múltiplo: ~28 min de processamento
• Revisão de exceções: ~2 h
• Total: ~2h 30min — redução de 97,8%

Como testar

Cria conta gratuita em implantacao.com.br/signup:

1. Configura conexão Protheus
2. Compila U_BEEITSYNC.PRW no Repositório do cliente (documentação inclusa)
3. Testa envio simples de 1 SA1 pelo Painel
4. Aumenta pra batch de 100

Trial de 14 dias sem cartão. Veja também: Cadastros base do Protheus e Configurador RT 2026.

← Voltar pro blog