ETL SuperlógicaMXM

Este projeto implementa um ETL mensal completo que integra os recebimentos financeiros gerados no sistema Superlógica, no módulo Imobiliárias junto ao ERP MXM WebManager, automatizando o processo de importação de títulos de Contas a Receber

[Open/Close] Table of Contents

• ETL SuperlógicaMXM
  • 📄 Goal
  • 💡 Prerequisites
  • 🚀 Build and Run
    • 🐋 Run on Docker
    • 🐧 Run on Linux
  • 📁 General Settings
  • ⚙️ API Settings
    • 📊 Set on Superlógica
    • ▶️ Set on MXM WebManager
      • User
      • Environment
  • 🚧 Versions

---

📄 Goal

Extrair mensalmente cobranças geradas no sistema Superlógica, do módulo Imobiliárias, via API, transformar os dados em CSV, normalizar os mesmos e inserir em forma de título de recebimento no ERP MXM WebManager, no módulo de Contas a Receber, também via endpoint de API, com rateio por grupo contábil e centro de custos

💡 Prerequisites

• Docker + Docker Compose com uma porta livre para Airflow UI (usualmente a 8080) ou engine Linux com Airflow e Python instalados
• Licença para o módulo Imobiliárias, do Superlógica
• Licença para o módulo Contas a Receber, do MXM WebManager

🚀 Build and Run

🐋 Run on Docker

1. Clone este repositório

2. Siga as etapas com as configurações gerais do projeto

3. Siga as etapas de configuração de API para o Superlógica e MXM WebManager

4. Construa a imagem:

   docker build -t airflow-sienge-sl-mxm:latest .

5. Rode o Airflow:

   docker compose up -d

6. Acesse a interface do Airflow (normalmente em http://localhost:8080)

7. Vá para Admin > Variables > Add new record

8. Crie as variáveis necessárias:

   Variável	Origem
   int_superlogica_app_token	Superlógica
   int_superlogica_access_token	Superlógica
   int_mxm_username	MXM WebManager
   int_mxm_password	MXM WebManager
   int_mxm_hom_enviroment	MXM WebManager

   Defina também a variável pth_depara_superlogica_mxm de acordo com o local onde seu depara está salvo, se usar o modelo do projeto e estiver rodando localmente, vai ser algo como /assets/depara_superlogica_mxm.csv

9. Despause a DAG na interface do Airflow

10. Execute o trigger

🐧 Run on Linux

1. Clone este repositório
2. Crie um ambiente virtual (se ainda não o fez)
3. Mova o arquivo etl_superl_mxm_dag.py para a pasta raiz /dags
4. Crie um diretório para o arquivo depara_supmxm.csv em um local acessível pelo Airflow e mova o arquivo para essa pasta
5. Adicione as variáveis do Airflow

airflow variables set int_superlogica_app_token "..."
airflow variables set int_superlogica_access_token "..."
airflow variables set int_mxm_username "..."
airflow variables set int_mxm_password "..."
airflow variables set int_mxm_hom_environment "..."
airflow variables set pth_depara_superlogica_mxm "/home/airflow/dags/depara_supmxm.csv"

6. Inicie o Airflow ativando o webserver e o scheduler (caso ainda não esteja ativo)
7. Trigger etl_cobsuperlogica_v.1

---

📁 General Settings

1. Preencha o arquivo de depara entre o Superlógica e o MXM caso seus parâmetros entre os dois sistemas não sejam equivalentes

⚙️ API Settings

📊 Set on Superlógica

1. No módulo web, vá em Todos os usuários > API (INTEGRAÇÃO COM OUTROS SISTEMAS) > Aplicativos > Novo App Token

2. Preencha o nome e descrição do aplicativo

3. Salve os valores de App token, Secret e Access token em um lugar seguro, eles serão usados para criar as variáveis no Airflow:

   Variável	Origem
   int_superlogica_app_token	App token
   int_superlogica_access_token	Access token

Em caso de dúvidas, consulte a documentação oficial

▶️ Set on MXM WebManager

1. Consulte o time técnico para obter seu usuário de INTEGRAÇÃO

   Variável	Origem
   int_mxm_username	Usuário de INTEGRAÇÃO
   int_mxm_password	Senha do usuário
   int_mxm_hom_environment	Ambiente usado

2. No ambiente de homologação, faça o login com um usuário padrão
3. Acesse o módulo Integração Padrão > Processos > Importação Modelo > Processar importação de modelo
4. Selecione o processo 035 - TITULOS A RECEBER
5. Escolha o layout XL - PADRAO EXCEL
6. Preencha e faça upload do arquivo modelo_layout.xlsx
7. Grave o processo e consulte o resultado em Dashboard de Integração ou Resultado das importações de modelo; a importação via modelo precisa gerar um título (que pode ser excluído depois) para "ativar" o uso do endpoint

User

O usuário usado para acessar o endpoint precisa ser o usuário de INTEGRAÇÃO, normalmente precisa ser solicitado ao time técnico.

Environment

Recomenda-se usar o ambiente de homologação e aguardar o espelhamento em D-1 para produção. A nomenclatura costuma ser {empresa}hom, mas para evitar erros o ideal é consultar o time de implantação.

Em caso de dúvidas, consulte a documentação oficial

🚧 Versions

[See/Hide] Version: v.1

Stable first version