Laboratório: Pipeline de Extração do Bluesoft ERP para Dashboard no Metabase via PostgreSQL

Roteiro para estudo em ambiente de laboratório ou de teste. Execute apenas em equipamentos, redes e contas que você tenha autorização para usar, com backup e homologação próprios. Comandos podem causar indisponibilidade ou perda de dados. Software e marcas citados pertencem aos seus titulares. Termos de Uso.

Duração estimada

120 min

Passos

10

Validações

4

Versões da documentação consultada

PostgreSQL a versão estável atual · Python a versão estável atual · Metabase a versão estável atual · requests a versão estável atual

Topologia

O laboratório usa três componentes principais em uma rede local: uma máquina (ou VM) executa o extrator Python, que acessa a API do Bluesoft ERP pela internet (usando token x-CustomToken), processa os dados e insere no PostgreSQL local (192.168.56.10). O Metabase (192.168.56.20) conecta-se ao PostgreSQL para montar dashboards. O usuário interage via navegador com o Metabase.

      [Internet]
          |
  [Extrator Python]
       |      \
       |       \---[API Bluesoft ERP]
       |
[PostgreSQL 192.168.56.10]
       |
[Metabase 192.168.56.20]
       |
    [Navegador Usuário]

Equipamentos e software

Roteiro

1. Preparar ambiente do PostgreSQL

   Instale o PostgreSQL na máquina 192.168.56.10. O banco será o destino dos dados extraídos. Crie o banco bi_varejo e um usuário dedicado.

   sudo apt update && sudo apt install postgresql
   sudo -u postgres psql -c "CREATE DATABASE bi_varejo;"
   sudo -u postgres psql -c "CREATE USER extrator WITH PASSWORD 'extrator123';"
   sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE bi_varejo TO extrator;"Copiar

   O que você deve ver: Banco bi_varejo criado e acessível pelo usuário extrator.

2. Criar esquema de estudo no PostgreSQL

   Implemente o modelo de estudo com tabelas fato_venda, fato_venda_item, dim_produto, dim_cliente, dim_loja, dim_campanha. Não é o modelo do fabricante.

   psql -U extrator -d bi_varejo -h 192.168.56.10
   
   CREATE TABLE dim_produto (
     id SERIAL PRIMARY KEY,
     codigo VARCHAR(50),
     descricao VARCHAR(255)
   );
   CREATE TABLE dim_cliente (
     id SERIAL PRIMARY KEY,
     codigo VARCHAR(50),
     nome VARCHAR(255)
   );
   CREATE TABLE dim_loja (
     id SERIAL PRIMARY KEY,
     codigo VARCHAR(50),
     nome VARCHAR(255)
   );
   CREATE TABLE dim_campanha (
     id SERIAL PRIMARY KEY,
     codigo VARCHAR(50),
     nome VARCHAR(255)
   );
   CREATE TABLE fato_venda (
     id SERIAL PRIMARY KEY,
     data DATE,
     id_loja INTEGER REFERENCES dim_loja(id),
     id_cliente INTEGER REFERENCES dim_cliente(id),
     id_campanha INTEGER REFERENCES dim_campanha(id),
     valor_total NUMERIC
   );
   CREATE TABLE fato_venda_item (
     id SERIAL PRIMARY KEY,
     id_venda INTEGER REFERENCES fato_venda(id),
     id_produto INTEGER REFERENCES dim_produto(id),
     quantidade NUMERIC,
     preco_unitario NUMERIC
   );Copiar

   O que você deve ver: Tabelas criadas no banco bi_varejo.

3. Instalar Python e dependências

   O extrator será feito em Python. Instale Python 3.x e o pacote requests.

   sudo apt update && sudo apt install python3 python3-pip
   pip3 install requests psycopg2-binaryCopiar

   O que você deve ver: Python 3.x, requests e psycopg2-binary instalados.

4. Configurar variáveis do extrator

   Crie um arquivo config.json com as credenciais do banco, token do Bluesoft e URLs dos recursos. Não coloque endpoints literais; consulte o api-docs do seu tenant.

   {
     "db_host": "192.168.56.10",
     "db_name": "bi_varejo",
     "db_user": "extrator",
     "db_pass": "extrator123",
     "token": "SEU_TOKEN_X_CUSTOMTOKEN",
     "url_produtos": "URL_RECURSO_PRODUTOS",
     "url_clientes": "URL_RECURSO_CLIENTES",
     "url_vendas": "URL_RECURSO_VENDAS"
   }Copiar

   O que você deve ver: Arquivo config.json criado com parâmetros reais.

5. Implementar extrator Python

   Implemente um script Python que leia config.json, autentique na API do Bluesoft ERP usando x-CustomToken, extraia produtos, clientes e vendas, e insira nas tabelas. Use requests para HTTP e psycopg2 para PostgreSQL.

   Consulte a documentação de requests (https://requests.readthedocs.io/) e psycopg2 (https://www.psycopg.org/docs/).
   
   Exemplo de cabeçalho:
   headers = {'x-CustomToken': config['token']}
   
   Exemplo de requisição:
   resp = requests.get(config['url_produtos'], headers=headers)
   
   Consulte o api-docs do seu tenant para parâmetros e paginação.
   
   Exemplo de inserção:
   cur.execute('INSERT INTO dim_produto (codigo, descricao) VALUES (%s, %s)', (codigo, descricao))Copiar

   O que você deve ver: Script extrai dados da API e popula as tabelas do PostgreSQL.

6. Executar extração inicial

   Rode o script Python para realizar a primeira carga. Observe logs e mensagens de erro.

   python3 extrator_bluesoft.pyCopiar

   O que você deve ver: Mensagens indicando progresso da extração e inserção. Tabelas populadas.

7. Instalar e configurar Metabase

   No host 192.168.56.20, instale o Metabase via Docker. O Metabase será a interface de BI.

   sudo apt update && sudo apt install docker.io
   sudo docker run -d -p 3000:3000 --name metabase metabase/metabaseCopiar

   O que você deve ver: Container Metabase rodando na porta 3000.

8. Conectar Metabase ao PostgreSQL

   No primeiro acesso ao Metabase (http://192.168.56.20:3000), configure o acesso ao banco bi_varejo usando as credenciais criadas.

   Acesse via navegador e preencha:
   Host: 192.168.56.10
   Porta: 5432
   Banco: bi_varejo
   Usuário: extrator
   Senha: extrator123Copiar

   O que você deve ver: Metabase conectado ao banco e reconhecendo as tabelas.

9. Criar dashboards básicos

   No Metabase, crie pelo menos um dashboard com gráficos de vendas por loja, curva ABC de produtos e vendas por campanha. Use o editor visual ou SQL.

   No Metabase, clique em "Nova Consulta", selecione a tabela fato_venda, agrupe por id_loja, some valor_total, e salve como gráfico.Copiar

   O que você deve ver: Dashboards visuais mostrando os dados extraídos.

10. Agendar extração periódica (opcional)

    Use cron (Linux) para agendar o script Python e manter os dados atualizados.

    crontab -e
    0 * * * * /usr/bin/python3 /caminho/para/extrator_bluesoft.py >> /var/log/extrator_bluesoft.log 2>&1Copiar

    O que você deve ver: Script executa automaticamente a cada hora.

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca compartilhe o token x-CustomToken fora do ambiente controlado
• Restrinja o acesso ao banco PostgreSQL apenas aos hosts necessários
• Use firewall para limitar acesso às portas 5432 (PostgreSQL) e 3000 (Metabase)
• Armazene config.json com permissões restritas (chmod 600)
• Revogue tokens não utilizados no ERP
• Considere usar SSL/TLS nas conexões, conforme a documentação das ferramentas

Checklist final

• PostgreSQL instalado e acessível
• Banco bi_varejo criado com tabelas do modelo de estudo
• Python e dependências instalados
• Arquivo config.json com URLs e token válidos
• Script Python executado com sucesso
• Metabase instalado e acessando o banco
• Dashboards criados e mostrando dados