Como integrar o TOTVS Protheus com o Power BI
Existem três caminhos para integrar o Protheus ao Power BI: leitura direta no banco, API REST do Protheus e uma camada intermediária que copia os dados para um banco analítico. A leitura direta é a mais rápida de montar e a mais fácil de errar, porque as tabelas do Protheus guardam registros excluídos, filial e datas em formato de texto.
Por que o número do Power BI não bate com o do Protheus
Quase todo relatório novo nasce com o valor errado, e a causa costuma ser uma das três abaixo. Elas não são bug do Power BI nem do Protheus: são características do modelo de dados do Protheus que quem vem do mundo SQL não espera.
- Exclusão lógica. O Protheus não apaga a linha: ele marca a coluna D_E_L_E_T_ com um asterisco. Um SELECT sem filtro soma registros que o usuário já excluiu no sistema.
- Filial. Toda tabela carrega o código da filial no primeiro campo (A1_FILIAL, E2_FILIAL). Sem filtrar ou agrupar por filial, o relatório soma empresas diferentes na mesma linha.
- Data como texto. Datas ficam em colunas CHAR no formato AAAAMMDD, não em colunas DATE. Ordenação e comparação funcionam por acaso, mas qualquer cálculo de intervalo precisa de conversão explícita.
- Espaço à direita. Campos são CHAR de tamanho fixo e vêm preenchidos com espaço. Um JOIN entre chaves sem TRIM simplesmente não casa e devolve tabela vazia.
Qual caminho escolher
A escolha real não é técnica, é de suporte. A TOTVS não dá garantia sobre leitura direta no banco: se um upgrade mudar a estrutura de uma tabela, o problema é seu. A API REST é o caminho homologado, mas expõe menos dados e é bem mais lenta para volume analítico.
Na prática, empresa com um punhado de relatórios e time interno de BI costuma partir para leitura direta com view de leitura. Empresa com muitos consumidores de dado, ou com política de não abrir o banco do ERP, precisa da camada intermediária. Esse padrão de camada é o mesmo que descrevemos em integração de sistemas legados com APIs modernas.
Import ou DirectQuery
Use Import como padrão. As tabelas do Protheus não são modeladas para consulta analítica, então DirectQuery joga cada interação do usuário direto no banco de produção do ERP, e o setor financeiro sente.
DirectQuery só se justifica quando o requisito é dado do minuto atual e o volume da consulta é pequeno. Se o dado de ontem resolve, Import com atualização agendada é mais barato, mais rápido e não compete com o ERP por recurso.
Se o Protheus roda em servidor local e o Power BI é o serviço em nuvem, a atualização agendada exige um gateway de dados instalado na rede. Isso costuma aparecer só na hora de publicar o relatório.
Ambiente com mais de um grupo de empresas
O Protheus sufixa o nome da tabela com o número do grupo de empresas: SA1010 e SA1020 são a mesma tabela de clientes em grupos diferentes. Um relatório que aponta para SA1010 e depois precisa incluir outro grupo não é ajuste de filtro, é query nova.
Se existe chance de o segundo grupo entrar depois, vale parametrizar o sufixo desde o começo em vez de escrever o nome da tabela fixo na consulta.
Passo a passo da leitura direta
- Confirme o banco e peça acesso somente leitura. Descubra se o Protheus roda em SQL Server, Oracle ou Postgres e peça um usuário com permissão apenas de leitura, restrito às tabelas do relatório. Nunca use o usuário da aplicação.
- Identifique as tabelas certas. Mapeie os dados que o relatório precisa para as tabelas do módulo correspondente (clientes, contas a receber, contas a pagar, notas). Confirme o dicionário com quem opera o ERP, porque campos customizados são comuns.
- Escreva a consulta com os filtros obrigatórios. Filtre a exclusão lógica (D_E_L_E_T_ vazio) e a filial em toda tabela da consulta. Aplique TRIM nas chaves de junção e converta as colunas de data de texto AAAAMMDD para tipo data.
- Publique a consulta como view. Guarde a consulta como view no banco em vez de colar SQL dentro do Power BI. Isso concentra a regra num lugar só e evita que cada relatório recrie a mesma lógica com uma variação sutil.
- Conecte o Power BI em modo Import. No Power BI Desktop, conecte no banco pela view criada e escolha Import. Confira o total contra um relatório nativo do Protheus antes de modelar qualquer coisa em cima.
- Instale o gateway e agende a atualização. Se o banco está na rede local, instale o gateway de dados no ambiente, registre a fonte e defina a janela de atualização fora do horário de pico do ERP.
- Valide de novo depois do primeiro fechamento. Compare os números do relatório com o fechamento do mês. Divergência que só aparece no fechamento costuma ser lançamento de filial não incluída ou registro excluído sendo contado.
Comparação dos três caminhos
Custo e prazo abaixo consideram a primeira integração, com dois a três relatórios. Relatório adicional sobre uma integração que já existe é sempre mais barato.
| Abordagem | Custo | Prazo | Onde para de servir |
|---|---|---|---|
| Leitura direta no banco | Baixo: só o trabalho de montar a query e o gateway | Dias | Sem garantia da TOTVS. Upgrade pode mudar estrutura e quebrar o relatório sem aviso. Consulta pesada compete com o ERP. |
| API REST do Protheus | Médio: exige publicar e configurar os serviços no ambiente | 1 a 2 semanas | Caminho homologado, porém expõe menos dados e é lento para volume analítico. Endpoint que falta vira desenvolvimento no ERP. |
| Camada intermediária (banco analítico) | Alto na primeira vez, baixo por relatório depois | 2 a 4 semanas | Dado tem a latência da última carga. Vira infraestrutura própria, com custo de manutenção contínuo. |
| Exportação manual para planilha | Zero em software, alto em hora de pessoa | Imediato | Não escala e não tem histórico confiável. Serve para validar se o relatório é útil antes de investir na integração. |
Perguntas frequentes
Referências
Quer isso rodando na sua operação?
O primeiro passo é um Diagnóstico: mapeamos o processo na sua operação e devolvemos escopo, prazo e preço antes de qualquer proposta.
Conhecer o Diagnóstico