Laboratório: Dashboard de Vendas de Supermercado com Apache Superset e PostgreSQL a partir da API do Bluesoft ERP

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

12

Validações

5

Versões da documentação consultada

PostgreSQL a versão estável atual · Python 3.10 ou superior · requests a versão estável atual · Apache Superset a versão estável atual · Docker a versão estável atual

Topologia

Uma estação de trabalho (real ou VM) executa três componentes principais: um extrator Python acessa a API do Bluesoft ERP (via internet, endereço externo), grava os dados em um PostgreSQL local (localhost, porta 5432), e o Apache Superset (localhost, porta 8088) conecta-se ao PostgreSQL para montar dashboards. O acesso ao Superset é feito pelo navegador, na própria máquina.

+-------------------+
|  Bluesoft ERP API |
| (cloud, internet) |
+--------+----------+
         |
         v
+--------+----------+
|  Extrator Python  |
| (localhost)       |
+--------+----------+
         |
         v
+--------+----------+
| PostgreSQL        |
| (localhost:5432)  |
+--------+----------+
         |
         v
+--------+----------+
| Apache Superset   |
| (localhost:8088)  |
+-------------------+

Equipamentos e software

Roteiro

1. Preparar ambiente e instalar dependências

   Você precisa garantir que Docker, Docker Compose, Python 3.10+ e pip estejam instalados. Docker simplifica a instalação do Superset e do PostgreSQL, isolando os serviços.

   sudo apt update && sudo apt install docker.io docker-compose python3 python3-pip -yCopiar

   O que você deve ver: Docker, docker-compose, python3 e pip instalados sem erros.

2. Subir PostgreSQL com Docker

   O PostgreSQL será o destino dos dados extraídos. Usar Docker facilita o controle e a limpeza do ambiente.

   docker run --name pg-bi-varejo -e POSTGRES_PASSWORD=bi123 -e POSTGRES_DB=bi_varejo -p 5432:5432 -d postgres:latestCopiar

   O que você deve ver: Container do PostgreSQL rodando, visível com docker ps.

3. Criar esquema de estudo no PostgreSQL

   O modelo de dados será simplificado, com tabelas fato_venda, fato_venda_item, dim_produto, dim_cliente, dim_loja, dim_campanha. Isso permite simular um ambiente de BI realista.

   docker exec -it pg-bi-varejo psql -U postgres -d bi_varejoCopiar

   O que você deve ver: Prompt do psql pronto para comandos SQL.

4. Definir tabelas no PostgreSQL

   Crie as tabelas do modelo de estudo. Não copie tabelas do Bluesoft: adapte para o propósito do laboratório.

   CREATE TABLE dim_produto (id SERIAL PRIMARY KEY, nome TEXT, categoria TEXT);
   CREATE TABLE dim_cliente (id SERIAL PRIMARY KEY, nome TEXT, tipo TEXT);
   CREATE TABLE dim_loja (id SERIAL PRIMARY KEY, nome TEXT, cidade TEXT);
   CREATE TABLE dim_campanha (id SERIAL PRIMARY KEY, nome TEXT, data_inicio DATE, data_fim DATE);
   CREATE TABLE fato_venda (id SERIAL PRIMARY KEY, data DATE, id_loja INT, id_cliente INT, id_campanha INT, valor_total NUMERIC);
   CREATE TABLE fato_venda_item (id SERIAL PRIMARY KEY, id_venda INT, id_produto INT, quantidade INT, preco_unitario NUMERIC);Copiar

   O que você deve ver: Tabelas criadas sem erro (mensagem CREATE TABLE para cada uma).

5. Instalar dependências Python

   requests será usado para acessar a API do Bluesoft ERP. psycopg2 conecta ao PostgreSQL.

   pip3 install requests psycopg2-binaryCopiar

   O que você deve ver: Pacotes instalados sem erro.

6. Configurar variáveis de ambiente para o extrator

   Nunca exponha tokens no código. Crie um arquivo .env com as variáveis URL_RECURSO, X_CUSTOM_TOKEN, e as credenciais do PostgreSQL.

   echo 'URL_RECURSO=https://erp.bluesoft.com.br/<tenant>/api/v3/<recurso>' > .env
   echo 'X_CUSTOM_TOKEN=seu_token_aqui' >> .env
   echo 'PG_HOST=localhost' >> .env
   echo 'PG_USER=postgres' >> .env
   echo 'PG_PASSWORD=bi123' >> .env
   echo 'PG_DATABASE=bi_varejo' >> .envCopiar

   O que você deve ver: Arquivo .env criado com as variáveis.

7. Implementar extrator Python

   O extrator conecta à API, lê dados paginados do recurso de pedidos de venda e insere nas tabelas. Use requests para HTTP e psycopg2 para o banco. Não use caminhos literais: leia URL_RECURSO do .env.

   Consulte a documentação oficial do requests (requests.readthedocs.io) e psycopg2 (psycopg.org). Exemplo de estrutura:
   
   import os
   import requests
   import psycopg2
   from dotenv import load_dotenv
   
   load_dotenv()
   url = os.getenv('URL_RECURSO')
   token = os.getenv('X_CUSTOM_TOKEN')
   conn = psycopg2.connect(host=os.getenv('PG_HOST'), user=os.getenv('PG_USER'), password=os.getenv('PG_PASSWORD'), dbname=os.getenv('PG_DATABASE'))
   headers = {'x-CustomToken': token}
   r = requests.get(url, headers=headers)
   # Parseie os dados conforme o schema do recurso e insira nas tabelas
   # Consulte o api-docs do seu tenant para detalhes de campos e paginaçãoCopiar

   O que você deve ver: Execução sem erro, dados inseridos nas tabelas. Consulte o banco para conferir.

8. Agendar extração (opcional)

   Para simular operação real, agende o script Python via cron (Linux) ou Task Scheduler (Windows).

   crontab -e
   # Exemplo de linha para rodar a cada hora:
   0 * * * * /usr/bin/python3 /caminho/para/seu_extrator.pyCopiar

   O que você deve ver: Script executado automaticamente no horário agendado.

9. Subir Apache Superset com Docker

   Superset é pesado para instalar manualmente. O Docker simplifica e isola o ambiente.

   git clone https://github.com/apache/superset.git
   cd superset/docker
   cp .env.example .env
   # Edite .env para definir SUPERSET_LOAD_EXAMPLES=no
   # Suba os containers:
   docker-compose -f docker-compose-non-dev.yml up -dCopiar

   O que você deve ver: Containers do Superset rodando (verifique com docker ps), web UI disponível em http://localhost:8088.

10. Configurar usuário admin no Superset

    Crie o usuário admin para acessar a interface.

    docker exec -it superset_app bash
    superset fab create-admin
    # Siga as instruções para definir usuário e senhaCopiar

    O que você deve ver: Usuário admin criado com sucesso.

11. Conectar Superset ao PostgreSQL

    No Superset, adicione uma nova conexão de banco usando a URI postgresql://postgres:bi123@host.docker.internal:5432/bi_varejo (se Superset e PostgreSQL estão em containers separados, ajuste o host conforme a rede Docker).

    No navegador, acesse http://localhost:8088, faça login, vá em 'Data' > 'Databases' > 'Add Database'. Use a URI: postgresql://postgres:bi123@host.docker.internal:5432/bi_varejoCopiar

    O que você deve ver: Banco conectado, tabelas visíveis em 'Datasets'.

12. Criar dashboard de vendas no Superset

    Monte um dashboard simples: total de vendas por loja, curva ABC de produtos, vendas por campanha. Use os datasets criados a partir das tabelas.

    No Superset, clique em 'Charts' > 'New Chart', selecione a tabela, escolha o tipo de gráfico e configure as métricas.Copiar

    O que você deve ver: Gráficos exibindo dados reais do PostgreSQL.

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca compartilhe o token x-CustomToken publicamente ou em código versionado.
• Restrinja o acesso ao PostgreSQL à máquina local ou rede interna.
• Use variáveis de ambiente para credenciais, nunca hardcode.
• Altere a senha padrão do PostgreSQL após o laboratório.
• Limite o acesso ao Superset com usuário e senha fortes.
• Remova containers e arquivos sensíveis após o laboratório.

Checklist final

• Docker e dependências instalados
• PostgreSQL rodando e acessível
• Tabelas criadas conforme o modelo de estudo
• Arquivo .env configurado sem expor o token
• Script Python executado sem erros
• Superset acessível via navegador
• Banco conectado ao Superset
• Dashboard criado e exibindo dados