jupiter-subtes 0.2.8

Biblioteca para automatização web nos sistemas do Tesouro do Estado do Rio de Janeiro

🪐 Biblioteca Jupiter

Jupiter é uma biblioteca Python desenvolvida para centralizar e padronizar o ecossistema tecnológico do setor contábil do Tesouro. Seu principal objetivo é simplificar tarefas diárias por meio da automação de processos sistêmicos (Siafe) e da integração fluida com o repositório em nuvem corporativo (SharePoint), com uma arquitetura preparada para abraçar novas integrações no futuro.

---

✨ Principais Funcionalidades

O projeto atualmente é dividido em dois grandes módulos operacionais:

🏛️ 1. Automação Contábil (siafelibrary.py)

Encapsula toda a interação com o Sistema Integrado de Gestão Orçamentária, Financeira e Contábil (Siafe-Rio2).

• Login Automatizado: Suporte para ambientes de Produção e Testes (Beta).
• Geração de Documentos em Lote: Processa grandes volumes de dados a partir de tabelas do pandas (DataFrame).
• Documentos Suportados:
  • Guia de Recolhimento (GR) - Orçamentária e Extra-orçamentária
  • Programação de Desembolso (PDE) - Extra-orçamentária
  • Programação de Desembolso de Transferência (PDT)
  • Nota Patrimonial (NP)
  • Nota de Aplicação e Resgate (NA)
• Resiliência: Possui sistema embutido de tratamento de erros, alertas visuais (tkinter), controle de re-tentativas (até 3 vezes por documento) e inteligência para pular registros com falhas de comunicação e retomá-los posteriormente.

☁️ 2. Integração em Nuvem (apipoint.py)

Gerencia conexões e operações de arquivos com o Microsoft SharePoint.

• Autenticação Inteligente: Utiliza extração automatizada de cookies do navegador para estabelecer uma conexão segura.
• Gestão de Arquivos e Pastas:
  • Upload e Download de arquivos individuais.
  • Upload e Download recursivo de pastas completas.
  • Verificação de existência de caminhos e criação de diretórios estruturados.
  • Exclusão de arquivos e pastas antigas.

🚀 O que vem por aí (Roadmap)

• Integração com o Microsoft Outlook (Disparo e leitura automatizada de e-mails contábeis).
• Integração com o Microsoft Teams (Alertas em canais sobre status de contabilização, como "Rotina X finalizada com sucesso").

---

📦 Dependências

Para que o Jupiter funcione corretamente, seu ambiente Python precisa contar com as seguintes bibliotecas:

• office365-rest-python-client (Comunicação com o ecossistema Microsoft)
• selenium (Controle do navegador para o Siafe)
• pandas (Manipulação dos dados e planilhas)
• automaweb (Biblioteca base interna de automação web)

---

🛠️ Instalação e Configuração do Ambiente

Como o Jupiter utiliza bibliotecas externas e módulos de automação web, siga os passos abaixo para preparar o seu ambiente local:

1. Clone o repositório (ou baixe os arquivos fonte): git clone https://seu-repositorio-interno/jupiter.git cd jupiter

2. Instale as dependências públicas via pip: pip install pandas selenium office365-rest-python-client

3. Instale a biblioteca base automaweb: Como a automaweb é uma biblioteca de uso interno, certifique-se de que ela está no mesmo diretório do seu projeto ou instale-a conforme a documentação da sua equipe (por exemplo, via arquivo .whl ou clonando o repositório respectivo).

4. Webdriver: O Jupiter gerencia o navegador via Selenium. Certifique-se de ter o Google Chrome instalado e atualizado na sua máquina. A biblioteca automaweb deve lidar com o gerenciamento do ChromeDriver automaticamente em segundo plano.

---

💻 Como Usar (Quick Start)

Abaixo estão exemplos básicos de como importar e utilizar os módulos da biblioteca Jupiter nos seus scripts diários.

Manipulando o SharePoint

from jupiter import apipoint

Inicializa a conexão com o site da sua equipe

sp = apipoint.SharePoint(site_url="https://sua-url-sharepoint.com/sites/SetorContabil")

Fazendo o download de um relatório específico

sp.download_arquivo( caminho_sharepoint="/sites/SetorContabil/Shared Documents/Relatorios/balancete_01.xlsx", pasta_local="C:/Users/SeuUsuario/Downloads" )

Fazendo o upload de uma pasta inteira de arquivos processados

sp.upload_pasta( pasta_local="C:/Users/SeuUsuario/Documentos/Processados", pasta_sharepoint="/sites/SetorContabil/Shared Documents/Processados_Mes_Atual" )

Automatizando o Siafe

from jupiter import siafelibrary import pandas as pd

Carrega sua planilha de lançamentos contábeis

df_lancamentos = pd.read_excel("lancamentos.xlsx")

Dicionário mapeando as regras de negócio para as contas

(Permite separar as regras de contabilidade do código da biblioteca)

regras_contabeis = { "TIPO_A": { "TipoDocumento": "01", "UG": "123456", "DomicilioBancario": "0001", "IEF": "1", "Fonte": "100", "FonteRJ": "100", "TipoDetalhamentoFonte": "0", "TipoPatrimonial": "Ativo", "ItemPatrimonial": "Bancos", "OperacaoPatrimonial": "Entrada", # ... outros campos ... } }

Inicializa o robô

robo = siafelibrary.Siafe()

Faz o login no ambiente de produção (1)

if robo.logar_siafe(versaoSiafe=1, usuario="12345678900", senha="sua_senha_segura"):

# Inicia a geração de Guias de Recolhimento
sucesso = robo.gerar_gr(df=df_lancamentos, dict_map=regras_contabeis)

if sucesso:
    print("Lançamentos contabilizados com sucesso!")

---

🧩 Estruturando o Dicionário de Regras (dict_map)

A grande vantagem da biblioteca Jupiter é a separação das regras de negócio do código de automação. Toda a inteligência contábil (qual conta usar, qual fonte, qual UG) é injetada nas funções através do dict_map.

O dict_map é um dicionário Python onde a chave é o ID do tipo de lançamento (que deve bater com a coluna tipo_id da sua planilha/DataFrame) e o valor é outro dicionário contendo os campos que o Siafe exige.

Exemplo Completo e Comentado

Aqui está um modelo de como montar o seu dict_map com as principais chaves suportadas pelas funções (gerar_gr, gerar_pde, gerar_pdt, gerar_np, gerar_na):

regras_contabeis = { # Exemplo 1: Regra para uma GR Orçamentária Padrão (Chave "TIPO_01") "TIPO_01": { # --- Identificação --- "TipoDocumento": "01 - Arrecadação", "UG": "123456", "DomicilioBancario": "0001", "DomicilioBancarioCompleto": "0001 - BANCO EXEMPLO S.A.", # Usado para validação de segurança pelo robô

    # --- Detalhamento ---
    "IEF": "1",
    "Fonte": "100",
    "FonteRJ": "100",
    "TipoDetalhamentoFonte": "0",
    "DetalhamentoFonte": "0000",
    "Convenio": "99999",
    
    # --- Item Patrimonial e Orçamentário ---
    "TipoPatrimonial": "Ativo",
    "ItemPatrimonial": "Bancos Conta Movimento",
    "OperacaoPatrimonial": "Entrada de Recursos",
    "NaturezaReceita": "11180111", # Exclusivo para fluxos Orçamentários
},

# Exemplo 2: Regra para uma GR ou PD Extra-Orçamentária (Chave "TIPO_02")
"TIPO_02": {
    "ExtraOrcamentario": True, # Flag essencial: avisa ao robô para usar o caminho Extra-Orçamentário
    
    "TipoDocumento": "02 - Extra-orçamentário",
    "UG": "654321",
    "DomicilioBancario": "0002",
    "DomicilioBancarioCompleto": "0002 - OUTRO BANCO S.A.",
    
    "IEF": "1", "Fonte": "100", "FonteRJ": "100", "TipoDetalhamentoFonte": "0", "Convenio": "99999",
    
    "TipoPatrimonial": "Passivo",
    "ItemPatrimonial": "Obrigações a Pagar",
    "OperacaoPatrimonial": "Saída de Recursos",
    
    # --- Dados do Credor (Exclusivo Extra-Orçamentário) ---
    "TipoCredor": "PJ", # Pode ser: PJ, CG, PF ou UG
    "Credor": "12345678000199" # CNPJ, CPF ou código da UG
},

# Exemplo 3: Flags e Lógicas Especiais (NP, PDT, NA)
"TIPO_03": {
    # Campos básicos omitidos para brevidade...
    "TipoPatrimonial": "Ativo",
    "ItemPatrimonial": "Ajustes",
    "OperacaoPatrimonial": "899991", # Pode usar o código numérico
    
    # --- Flags Especiais do Jupiter ---
    
    "SelecaoPorValor": True,       # Diz ao robô para selecionar a Operação Patrimonial pelo Value (código) e não pelo texto visível.
    "Estorno": True,               # (Exclusivo para NA) Marca a caixa de Estorno na tela inicial.
    "Regularizacao": "01 - Tipo",  # (Exclusivo para PD) Marca a caixa de Regularização e seleciona o tipo.
    
    # --- Inscrição Genérica (Exclusivo para NP) ---
    "InscricaoGenerica": "12345",
    "TipoInscricaoGenerica": "01",
    "IGCompleta": "12345 - DESCRIÇÃO DA INSCRIÇÃO" # Usado para o robô validar se o Siafe carregou a IG corretamente antes de prosseguir.
}

}

💡 Dicas Importantes:

• Certifique-se de que os textos no dicionário sejam exatamente iguais aos exibidos nas caixas de seleção (dropdowns) do Siafe, pois o robô utiliza o texto exato para clicar, a menos que você utilize a flag "SelecaoPorValor": True.
• A sua planilha (df) só precisa ter as seguintes colunas obrigatórias: id, data, valor, observacao, tipo_id. O robô se encarrega de criar/preencher as colunas num_documento e tempo_contab em tempo de execução.

---

🏗️ Arquitetura e Decisões de Design

• Separação de Preocupações: O módulo do Siafe foi desenhado para não conter regras de negócio (códigos de fontes, UGs, naturezas). Tudo é injetado via dicionários (dict_map), permitindo que a mesma biblioteca atenda a diferentes sub-setores do Tesouro sem precisar de alterações no código-fonte.
• Tratamento de Exceções: Devido à natureza instável de sistemas governamentais, o Jupiter utiliza blocos densos de validação. Ele verifica via XPath se o texto realmente foi digitado/selecionado no Siafe antes de prosseguir. Se algo falha, o robô aperta o botão "Voltar" do próprio sistema, limpa as variáveis e tenta novamente.