csc-cia-stne 0.0.43__py3-none-any.whl

csc_cia_stne/bc_sta.py

@@ -0,0 +1,416 @@
+from requests.auth import HTTPBasicAuth
+import requests
+import xml.etree.ElementTree as ET
+import hashlib
+from pydantic import BaseModel, ValidationError, field_validator
+from typing import Literal, Dict, Union, Optional
+
+# Validações dos inputs
+class InitParamsValidator(BaseModel):
+    """
+    Classe responsável por validar os parâmetros de inicialização.
+    Atributos:
+        usuario (str): O nome de usuário.
+        senha (str): A senha do usuário.
+        ambiente (Literal["prd", "hml"]): O ambiente, que pode ser "prd" (produção) ou "hml" (homologação).
+    Métodos:
+        check_non_empty_string(value, info): Método de validação para garantir que cada parâmetro é uma string não vazia.
+    """
+        
+    usuario: str
+    senha: str
+    ambiente: Literal["prd", "hml"]  # Aceita apenas "prd" ou "sdx"
+
+    # Validação para garantir que cada parâmetro é uma string não vazia
+    """
+    Método de validação para garantir que cada parâmetro é uma string não vazia.
+    Parâmetros:
+        value (Any): O valor do parâmetro a ser validado.
+        info (FieldInfo): As informações do campo a ser validado.
+    Retorna:
+        value (Any): O valor do parâmetro validado.
+    Lança:
+        ValueError: Se o valor do parâmetro não for uma string não vazia.
+    """
+    @field_validator('usuario', 'senha')
+    def check_non_empty_string(cls, value, info):
+        if not isinstance(value, str) or not value.strip():
+            
+            raise ValueError(f"O parâmetro '{info.field_name}' deve ser uma string não vazia.")
+        
+        return value
+
+class EnviarArquivoValidator(BaseModel):
+    """
+    Classe responsável por validar os parâmetros de envio de arquivo.
+    Args:
+        tipo_arquivo (str): O código do tipo de envio a ser utilizado para o STA.
+            Verificar códigos disponíveis na documentação STA.
+        file_content (bytes): O conteúdo do arquivo a ser enviado, em formato de bytes.
+        nome_arquivo (str): O nome do arquivo a ser enviado.
+            Deve ser uma string não vazia e terminar com uma extensão de arquivo comum.
+        observacao (str): A observação relacionada ao envio do arquivo.
+            Deve ser uma string não vazia.
+        destinatarios (Optional[Union[Dict[str, str], str]], optional): Os destinatários do arquivo.
+            Pode ser um dicionário ou uma string XML. Defaults to None.
+    Raises:
+        ValueError: Se algum dos parâmetros não atender às condições de validação.
+    Returns:
+        O valor de cada parâmetro, se a validação for bem-sucedida.
+    """
+    tipo_arquivo:str
+    file_content:bytes
+    nome_arquivo:str
+    observacao:str
+    destinatarios:Optional[Union[Dict[str, str], str]] = None  # Aceita um dicionário
+    
+    @field_validator("tipo_arquivo")
+    def check_tipo_arquivo(cls, value):
+        if not isinstance(value, str) or not value.strip():
+    
+            raise ValueError("O parâmetro 'tipo_arquivo' deve ser uma string não vazia, com o código do tipo de envio a ser utilizado para o STA, verificar codigos disponíveis na documentação STA")
+    
+        return value
+    
+    # Validador para file_content: deve ter conteúdo em bytes
+    @field_validator("file_content")
+    def check_file_content(cls, value):
+        if not isinstance(value, bytes) or len(value) == 0:
+            raise ValueError("O parâmetro 'file_content' deve ser um byte array não vazio.")
+        return value
+    
+    # Validador para nome_arquivo: deve ser uma string não vazia e terminar com uma extensão de arquivo comum
+    @field_validator("nome_arquivo")
+    def check_nome_arquivo(cls, value):
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError("O nome do arquivo deve ser uma string não vazia.")
+        if not value.lower().endswith(('.zip', '.xpto')):
+            raise ValueError("O nome do arquivo deve ter uma extensão válida.")
+        return value
+    
+    @field_validator("observacao")
+    def check_observacao(cls, value):
+        if not isinstance(value, str) or not value.strip():
+    
+            raise ValueError("O parâmetro 'observacao' deve ser uma string não vazia")
+    
+        return value
+
+    # Validador para destinatarios: aceita um dicionário ou uma string XML opcional
+    @field_validator("destinatarios")
+    def check_destinatarios(cls, value):
+        if value is not None:
+            
+            if not isinstance(value, list):
+            
+                raise ValueError("O parâmetro 'destinatarios' deve ser uma lista de dicionários.")
+            
+            for item in value:
+            
+                if not isinstance(item, dict):
+            
+                    raise ValueError("Cada destinatário deve ser um dicionário.")
+            
+                required_keys = {"unidade", "dependencia", "operador"}
+            
+                if not required_keys.issubset(item.keys()):
+            
+                    raise ValueError("Cada destinatário deve conter as chaves 'unidade', 'dependencia' e 'operador'. Verifique a documentação da API BC STA para entender o que colocar cada campo")
+        
+        return value
+    
+class BC_STA:
+    
+    def __init__(self, usuario:str, senha:str, ambiente:str):
+        """
+        Inicializa uma instância da classe BC_STA.
+        Parâmetros:
+        - usuario (str): O nome de usuário para autenticação.
+        - senha (str): A senha para autenticação.
+        - ambiente (str): O ambiente de execução ('prd' para produção ou qualquer outro valor para ambiente de teste).
+        Raises:
+        - ValueError: Se houver erro na validação dos dados de input da inicialização da instância 'BC_STA'.
+        Exemplo de uso:
+        ```
+        bc_sta = BC_STA(usuario='meu_usuario', senha='minha_senha', ambiente='prd')
+        ```
+        """
+
+        try:
+            
+            InitParamsValidator(usuario=usuario, senha=senha, ambiente=ambiente)
+        
+        except ValidationError as e:
+        
+            raise ValueError("Erro na validação dos dados de input da inicialização da instância 'BC_STA':", e.errors())
+        
+        if ambiente == 'prd':
+            
+            self.base_url = "https://sta.bcb.gov.br/staws"
+        
+        else:
+            
+            self.base_url = "https://sta-h.bcb.gov.br/staws"
+        
+        try:
+
+            self.auth = HTTPBasicAuth(usuario,senha)
+            self.error = None
+            self.headers = {'Content-Type': 'application/xml'}
+            self.is_connected = self.verifica_conexao()
+
+        except Exception as e:
+
+            self.is_connected = False
+            self.error = e
+    
+    def verifica_conexao(self):
+        """
+        Verifica a conexão com o servidor STA do Banco Central do Brasil.
+        Returns:
+            bool: True se a conexão for bem-sucedida, False caso contrário.
+        Raises:
+            Exception: Se ocorrer algum erro durante a verificação da conexão.
+        Example:
+            # Criando uma instância da classe
+            bc_sta = BCSTA()
+            # Verificando a conexão
+            conexao = bc_sta.verifica_conexao()
+        """
+        try:
+
+            response = requests.get("https://sta.bcb.gov.br/staws/arquivos?tipoConsulta=AVANC&nivelDetalhe=RES", auth=self.auth)
+            
+            # Verificando o status e retornando a resposta
+            if response.status_code == 200:
+
+                return True
+
+            else:
+
+                return False
+
+
+        except Exception as e:
+
+            raise e
+
+    def enviar_arquivo(self, tipo_arquivo:str, file_content:bytes, nome_arquivo:str, observacao:str, destinatarios:dict=None):
+        """
+        Envia um arquivo para um determinado destino.
+            tipo_arquivo (str): O tipo de arquivo a ser enviado.
+            nome_arquivo (str): O nome do arquivo.
+            observacao (str): Uma observação opcional.
+            destinatarios (dict, optional): Um dicionário contendo informações sobre os destinatários do arquivo. 
+                O dicionário deve ter a seguinte estrutura:
+                {
+                    'unidade': 'nome_da_unidade',
+                    'dependencia': 'nome_da_dependencia',  # opcional
+                    'operador': 'nome_do_operador'  # opcional
+                O campo 'dependencia' e 'operador' são opcionais.
+                - 'enviado': Um valor booleano indicando se o arquivo foi enviado com sucesso.
+                - 'protocolo': O protocolo gerado, caso o arquivo tenha sido enviado com sucesso.
+                - 'link': O link do arquivo, caso tenha sido enviado com sucesso.
+                - 'erro': Uma mensagem de erro, caso ocorra algum problema no envio do arquivo.
+            ValueError: Se ocorrer um erro na validação dos dados de entrada.
+            Exception: Se ocorrer um erro durante o envio do arquivo.
+            # Exemplo de chamada da função
+            tipo_arquivo = 'documento'
+            nome_arquivo = 'arquivo.txt'
+            observacao = 'Este é um arquivo de teste'
+            destinatarios = {
+                'unidade': 'unidade_destino',
+                'dependencia': 'dependencia_destino',
+                'operador': 'operador_destino'
+            resposta = enviar_arquivo(tipo_arquivo, file_content, nome_arquivo, observacao, destinatarios)
+        """
+        try:
+            
+            EnviarArquivoValidator(tipo_arquivo=tipo_arquivo, file_content=file_content, nome_arquivo=nome_arquivo, observacao=observacao, destinatarios=destinatarios)
+        
+        except ValidationError as e:
+        
+            raise ValueError("Erro na validação dos dados de input do método 'enviar_arquivo':", e.errors())
+
+        def generate_sha256_hash(file_content):
+            """
+            Gera o hash SHA-256 do conteúdo de um arquivo.
+            Args:
+                file_content (bytes): O conteúdo do arquivo como uma sequência de bytes.
+            Returns:
+                str: O hash SHA-256 do conteúdo do arquivo.
+            Example:
+                file_content = b'Lorem ipsum dolor sit amet'
+                hash_value = generate_sha256_hash(file_content)
+                print(hash_value)
+            """
+            
+            # Gera o hash SHA-256 do arquivo
+            sha256_hash = hashlib.sha256()
+            sha256_hash.update(file_content)
+            return sha256_hash.hexdigest()
+
+        def process_response(xml_content):
+            """
+            Processa o conteúdo XML de resposta e retorna um dicionário com as informações relevantes.
+            Args:
+                xml_content (str): O conteúdo XML de resposta.
+            Returns:
+                dict: Um dicionário contendo as seguintes chaves:
+                    - 'enviado': Um valor booleano indicando se o XML foi enviado com sucesso.
+                    - 'protocolo': O protocolo extraído do XML, caso tenha sido enviado com sucesso.
+                    - 'link': O link extraído do XML, caso tenha sido enviado com sucesso.
+                    - 'erro': Uma mensagem de erro, caso ocorra algum problema no processamento do XML.
+            Raises:
+                None
+            Exemplo de uso:
+                xml = "<root>...</root>"
+                resposta = process_response(xml)
+                print(resposta)
+            """
+
+            try:
+
+                root = ET.fromstring(xml_content)
+
+                # Verifica se há um elemento <Erro> no XML
+                erro = None
+                erro_elem = root.find('Erro')
+                
+                if erro_elem is not None:
+                
+                    codigo_erro = erro_elem.find('Codigo').text
+                    descricao_erro = erro_elem.find('Descricao').text
+                    erro = f"Erro {codigo_erro}: {descricao_erro}"
+                    resposta = {
+                        'enviado':False,
+                        'protocolo': None,
+                        'link': None,
+                        'erro': erro
+                        }                                    
+
+                else:
+
+                    protocolo = root.find('Protocolo').text
+                    link = root.find('.//atom:link', namespaces={'atom': 'http://www.w3.org/2005/Atom'}).attrib['href']
+                    resposta = {
+                        'enviado':True,
+                        'protocolo': protocolo,
+                        'link': link,
+                        'erro': None
+                        }
+
+                return resposta
+
+            except ET.ParseError as e:
+
+                resposta = {
+                    'enviado': False,
+                    'protocolo': None,
+                    'link': None,
+                    'erro': f"Error processing XML: {str(e)}"
+                }
+                return resposta
+        
+        url = self.base_url + '/arquivos'
+
+        # Calcula o hash SHA-256 do conteúdo do arquivo
+        hash_sha256 = generate_sha256_hash(file_content)
+        tamanho_arquivo = len(file_content)  # Tamanho do arquivo em bytes
+
+        # Constrói o XML de requisição
+        parametros = ET.Element('Parametros')
+        ET.SubElement(parametros, 'IdentificadorDocumento').text = tipo_arquivo
+        ET.SubElement(parametros, 'Hash').text = hash_sha256
+        ET.SubElement(parametros, 'Tamanho').text = str(tamanho_arquivo)
+        ET.SubElement(parametros, 'NomeArquivo').text = nome_arquivo
+        
+        # Campo observação é opcional
+        if observacao:
+            ET.SubElement(parametros, 'Observacao').text = observacao
+
+        # Campo destinatários é opcional
+        if destinatarios:
+
+            destinatarios_elem = ET.SubElement(parametros, 'Destinatarios')
+
+            for dest in destinatarios:
+
+                destinatario_elem = ET.SubElement(destinatarios_elem, 'Destinatario')
+                ET.SubElement(destinatario_elem, 'Unidade').text = dest['unidade']
+
+                if 'dependencia' in dest:
+
+                    ET.SubElement(destinatario_elem, 'Dependencia').text = dest['dependencia']
+
+                if 'operador' in dest:
+
+                    ET.SubElement(destinatario_elem, 'Operador').text = dest['operador']
+
+        # Converte o XML para string
+        xml_data = ET.tostring(parametros, encoding='utf-8', method='xml')
+
+        # Envia a requisição POST
+        response = requests.post(url, headers=self.headers, data=xml_data, auth=self.auth, timeout=60)
+
+        if response.status_code == 201:  # Verifica se o protocolo foi criado com sucesso
+            
+            resultado_protocolo = process_response(response.text)
+            
+            # Protocolo gerado, prosseguir com envio do arquivo
+            if resultado_protocolo["enviado"]:
+                
+                try:
+                    
+                    # Solicita o envio
+                    protocolo = resultado_protocolo["protocolo"]
+                    # URL do endpoint, incluindo o protocolo
+                    url = url + f"/{protocolo}/conteudo"
+
+                    # Envia a requisição PUT com o conteúdo binário do arquivo
+                    response = requests.put(url, data=file_content, auth=self.auth, timeout=60)
+                    
+                    if response.status_code == 200:
+                    
+                        return resultado_protocolo
+                    
+                    else:
+                    
+                        resposta = {
+                            'enviado':False,
+                            'protocolo': None,
+                            'link': None,
+                            'erro': f"Falha ao enviar arquivo. Status code: {response.status_code}, Text: {response.text}, Reason: {response.reason}"
+                            }
+                        return resposta
+
+                except Exception as e:
+                    
+                    erro = str(e)
+                    resposta = {
+                        'enviado':False,
+                        'protocolo': None,
+                        'link': None,
+                        'erro': erro
+                        }
+                    return resposta
+
+
+
+            # Protocolo não foi gerado, retornar erro
+            else:
+            
+                return resultado_protocolo
+
+        else:
+
+            print(response.text)
+            resposta = {
+                'enviado': False,
+                'protocolo': None,
+                'link': None,
+                'erro': f"Failed to create protocol. Status code: {response.status_code}, Reason: {response.reason}"
+            }
+            #return f"Failed to create protocol. Status code: {response.status_code}, Reason: {response.reason}"
+            return resposta
+

csc_cia_stne/email.py

@@ -0,0 +1,239 @@
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from email.mime.base import MIMEBase
+from email import encoders
+from pydantic import BaseModel, ValidationError, field_validator
+
+class InitParamsValidator(BaseModel):
+    """
+    Classe para validar os parâmetros de inicialização.
+    Atributos:
+    - email_sender (str): O endereço de e-mail do remetente.
+    - email_password (str): A senha do e-mail.
+    Métodos:
+    - check_str_input(value, info): Valida se o valor é uma string não vazia.
+    """
+    email_sender: str
+    email_password: str
+
+    """
+    Valida se o valor é uma string não vazia.
+    Parâmetros:
+    - value: O valor a ser validado.
+    - info: Informações sobre o campo.
+    Retorna:
+    - value: O valor validado.
+    Lança:
+    - ValueError: Se o valor não for uma string ou estiver vazio.
+    """
+    @field_validator('email_sender','email_password')
+    def check_str_input(cls, value, info):
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError(f"O campo '{info.field_name}' deve ser strings e não {type(value)}")
+        return value
+    
+class SendEmailParamsValidator(BaseModel):
+    """
+    Classe para validar os parâmetros de envio de e-mail.
+    Atributos:
+    - to (list): Lista de destinatários do e-mail.
+    - message (str): Mensagem do e-mail.
+    - title (str): Título do e-mail.
+    - reply_to (str): Endereço de e-mail para resposta.
+    - attachments (list, opcional): Lista de anexos do e-mail.
+    - cc (list, opcional): Lista de destinatários em cópia do e-mail.
+    - cco (list, opcional): Lista de destinatários em cópia oculta do e-mail.
+    """
+
+    to: list
+    message: str
+    title: str
+    reply_to:str
+    attachments: list = []
+    cc: list = []
+    cco: list = []
+
+    """
+    Valida se o valor é uma string não vazia.
+    Parâmetros:
+    - value (str): Valor a ser validado.
+    - info (FieldInfo): Informações sobre o campo.
+    Retorna:
+    - str: O valor validado.
+    Lança:
+    - ValueError: Se o valor não for uma string ou estiver vazio.
+    """
+    @field_validator('message','title','reply_to')
+    def check_str_input(cls, value, info):
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError(f"O campo '{info.field_name}' deve ser strings e não {type(value)}")
+        return value
+    
+    """
+    Valida se o valor é uma lista.
+    Parâmetros:
+    - value (list): Valor a ser validado.
+    - info (FieldInfo): Informações sobre o campo.
+    Retorna:
+    - list: O valor validado.
+    Lança:
+    - ValueError: Se o valor não for uma lista.
+    """
+    @field_validator('to','attachments','cc','cco')
+    def check_list_input(cls, value, info):
+        if not isinstance(value, list):
+            raise ValueError(f"O parametro '{info.field_name}' deve ser uma lista")
+        
+        return value
+
+class Email():
+
+    def __init__(self, email_sender, email_password):
+        """
+        Inicializa uma instância da classe Email.
+        Args:
+            email_sender (str): O endereço de e-mail do remetente.
+            email_password (str): A senha do e-mail do remetente.
+        Raises:
+            ValueError: Se houver um erro na validação dos dados de entrada da inicialização da instância.
+        Returns:
+            None
+        """
+
+        self.email_sender = email_sender
+        self.email_password = email_password
+
+        try:
+        
+            InitParamsValidator(email_sender=email_sender, email_password=email_password)
+
+        except ValidationError as e:
+        
+            raise ValueError("Erro na validação dos dados de input da inicialização da instância:", e.errors())
+
+
+        self.server = self.login_email()
+
+        if not isinstance(self.server, smtplib.SMTP) and 'status' in self.server and not self.server['status']:
+
+            raise ValueError("Erro na validação dos dados de input da inicialização da instância:", self.server['error'])
+
+
+    def login_email(self):
+        """
+        Realiza o login no servidor de e-mail.
+        Returns:
+            smtplib.SMTP: Objeto que representa a conexão com o servidor de e-mail.
+        Raises:
+            dict: Dicionário contendo o status de erro caso ocorra uma exceção durante o login.
+        Example:
+            email_sender = 'seu_email@gmail.com'
+            email_password = 'sua_senha'
+            email = Email(email_sender, email_password)
+            server = email.login_email()
+        """
+
+        try:
+
+            server = smtplib.SMTP('smtp.gmail.com', 587)
+            server.starttls()
+            server.login(self.email_sender, self.email_password)
+
+            return server
+
+        except Exception as e:
+
+            return {
+                'status':False,
+                'error':str(e)
+            }
+
+    
+    def send_email( self, to : list , message : str , title : str , reply_to: str, attachments : list = [] , cc : list = [] , cco : list = [] ) -> dict:
+        """
+        Envia um email com os parâmetros fornecidos.
+        Args:
+            to (list): Lista de destinatários do email.
+            message (str): Corpo do email.
+            title (str): Título do email.
+            reply_to (str): Endereço de email para resposta.
+            attachments (list, optional): Lista de caminhos dos arquivos anexos. Defaults to [].
+            cc (list, optional): Lista de destinatários em cópia. Defaults to [].
+            cco (list, optional): Lista de destinatários em cópia oculta. Defaults to [].
+        Returns:
+            dict: Dicionário com o status do envio do email. Se o envio for bem-sucedido, o dicionário terá a chave 'status' com valor True. Caso contrário, terá a chave 'status' com valor False e a chave 'error' com a descrição do erro.
+        Raises:
+            ValueError: Se houver erro na validação dos dados para o envio do email.
+        Example:
+            email = EmailSender()
+            to = ['example1@example.com', 'example2@example.com']
+            message = 'Olá, isso é um teste de email.'
+            title = 'Teste de Email'
+            reply_to = 'noreply@example.com'
+            attachments = ['/path/to/file1.txt', '/path/to/file2.txt']
+            cc = ['cc1@example.com', 'cc2@example.com']
+            cco = ['cco1@example.com', 'cco2@example.com']
+            result = email.send_email(to, message, title, reply_to, attachments, cc, cco)
+            print(result)
+        """
+
+        try:
+        
+            SendEmailParamsValidator(to=to, message=message, title=title, reply_to=reply_to, attachments=attachments, cc=cc, cco=cco)
+
+        except ValidationError as e:
+        
+            raise ValueError("Erro na validação dos dados para o envio do email:", e.errors())
+
+        try:
+
+            msg = MIMEMultipart()
+            
+            msg["From"] = self.email_sender
+            
+            msg["To"] = (",").join(to)
+            
+            msg["cc"] = (",").join(cc)
+            
+            msg['Reply-To'] = reply_to
+
+            msg["Subject"] = title
+
+            for file in attachments:
+
+                try:
+
+                    attachment = open(file, "rb")
+                    
+                    part = MIMEBase("application", "octet-stream")
+                    
+                    part.set_payload(attachment.read())
+                    
+                    encoders.encode_base64(part)
+                    
+                    part.add_header("Content-Disposition", f"attachment; filename={file.split('/')[-1]}")
+                    
+                    msg.attach(part)
+
+                    attachment.close()
+
+                except Exception as e:
+
+                    return {
+                        'status':False,
+                        'error':str(e)
+                    }
+
+            msg.attach(MIMEText(message, 'html'))
+
+            self.server.sendmail(self.email_sender, to + cc + cco, msg.as_string())
+
+            return True
+
+        except Exception as e:
+
+            return {
+                'status':False,
+                'error':str(e)
+            }