Trust-Code
diff --git a/‎LGPD.md‎
Lines changed: 304 additions & 0 deletions b/‎LGPD.md‎
Lines changed: 304 additions & 0 deletions
@@ -0,0 +1,304 @@
+# Funcionalidade LGPD - Lei Geral de Proteção de Dados
+
+## Visão Geral
+
+O PyBoleto agora inclui funcionalidade de mascaramento de dados pessoais para conformidade com a **LGPD (Lei Geral de Proteção de Dados - Lei nº 13.709/2018)**.
+
+Esta funcionalidade permite mascarar automaticamente dados sensíveis como CPF, CNPJ, nomes e endereços ao gerar boletos, sendo especialmente útil para:
+
+- 🔒 **Boletos de teste e desenvolvimento** - Evitar exposição de dados reais no código
+- 📚 **Documentação e exemplos** - Gerar documentação sem dados pessoais
+- 🔐 **Repositórios Git** - Proteger dados sensíveis versionados
+- ✅ **Conformidade legal** - Atender requisitos da LGPD
+
+## Como Usar
+
+### Uso Básico
+
+Para habilitar o mascaramento LGPD, basta definir o parâmetro `lgpd_habilitar=True` ao criar o boleto:
+
+```python
+import datetime
+from pyboleto.bank.bancodobrasil import BoletoBB
+from pyboleto.pdf import BoletoPDF
+
+# Cria o boleto
+boleto = BoletoBB(7, 2)
+
+# Dados normais do beneficiário
+boleto.cedente = 'João da Silva Santos'
+boleto.cedente_documento = '123.456.789-01'
+boleto.cedente_endereco = 'Rua das Flores, 123 - Centro - SP - 12345-678'
+
+# Dados normais do pagador
+boleto.sacado_nome = 'Maria Oliveira Costa'
+boleto.sacado_documento = '987.654.321-00'
+boleto.sacado_endereco = 'Av Paulista, 1000'
+
+# ... outros dados do boleto ...
+
+# HABILITA LGPD - Mascara automaticamente os dados sensíveis
+boleto.lgpd_habilitar = True
+
+# Gera o PDF (dados serão mascarados automaticamente)
+boleto_pdf = BoletoPDF('boleto-mascarado.pdf')
+boleto_pdf.drawBoleto(boleto)
+boleto_pdf.save()
+```
+
+### Mascaramento Seletivo
+
+Você pode escolher quais campos deseja mascarar:
+
+```python
+# Mascara apenas CPF/CNPJ
+boleto.lgpd_habilitar = True
+boleto.lgpd_campos = ['cedente_documento', 'sacado_documento']
+
+# Mascara apenas nomes
+boleto.lgpd_habilitar = True
+boleto.lgpd_campos = ['cedente', 'sacado_nome']
+
+# Mascara apenas endereços
+boleto.lgpd_habilitar = True
+boleto.lgpd_campos = ['cedente_endereco', 'sacado_endereco']
+```
+
+## Campos Mascarados
+
+### Dados do Beneficiário/Cedente
+
+| Campo Original | Exemplo Mascarado | Descrição |
+|----------------|-------------------|-----------|
+| `cedente` | João d. *** | Nome mascarado |
+| `cedente_documento` (CPF) | 123.***.***-01 | CPF mascarado |
+| `cedente_documento` (CNPJ) | 12.***.***/****-90 | CNPJ mascarado |
+| `cedente_logradouro` | Rua ***, *** - *** | Endereço mascarado |
+| `cedente_bairro` | C*** | Bairro mascarado |
+| `cedente_cidade` | S*** *** | Cidade mascarada |
+| `cedente_cep` | 12***-*** | CEP mascarado |
+
+### Dados do Pagador/Sacado
+
+| Campo Original | Exemplo Mascarado | Descrição |
+|----------------|-------------------|-----------|
+| `sacado_nome` | Maria O. *** | Nome mascarado |
+| `sacado_documento` (CPF) | 987.***.***-00 | CPF mascarado |
+| `sacado_documento` (CNPJ) | 98.***.***/****-00 | CNPJ mascarado |
+| `sacado_endereco` | Avenida ***, *** - *** | Endereço mascarado |
+| `sacado_bairro` | B*** | Bairro mascarado |
+| `sacado_cidade` | S*** *** | Cidade mascarada |
+| `sacado_cep` | 01***-*** | CEP mascarado |
+
+**Nota:** A UF (estado) **não** é mascarada por não ser considerada dado sensível.
+
+## Regras de Mascaramento
+
+### CPF
+- **Formato:** XXX.***.***-YY
+- **Mantém:** 3 primeiros dígitos e 2 últimos
+- **Exemplo:** 123.456.789-01 → 123.***.***-01
+
+### CNPJ
+- **Formato:** XX.***.***/****-YY
+- **Mantém:** 2 primeiros dígitos e 2 últimos
+- **Exemplo:** 12.345.678/0001-90 → 12.***.***/****-90
+
+### Nome
+- **Formato:** PrimeiroNome P. ***
+- **Mantém:** Primeiro nome e primeira letra do segundo nome
+- **Exemplo:** João da Silva Santos → João d. ***
+
+### Endereço
+- **Formato:** TipoLogradouro ***, *** - ***
+- **Mantém:** Tipo de logradouro (Rua, Avenida, etc.)
+- **Exemplo:** Rua das Flores, 123 → Rua ***, *** - ***
+
+### CEP
+- **Formato:** XX***-***
+- **Mantém:** 2 primeiros dígitos
+- **Exemplo:** 12345-678 → 12***-***
+
+### Cidade/Bairro
+- **Formato:** X*** ***
+- **Mantém:** Primeira letra
+- **Exemplo:** São Paulo → S*** ***
+
+## Exemplos Completos
+
+### Exemplo 1: Boleto Completo com LGPD
+
+```python
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+import datetime
+from pyboleto.bank.bancodobrasil import BoletoBB
+from pyboleto.pdf import BoletoPDF
+
+# Cria o boleto
+boleto = BoletoBB(7, 2)
+boleto.nosso_numero = '87654'
+boleto.numero_documento = '27030195'
+boleto.convenio = '7777777'
+boleto.carteira = '18'
+
+# Dados do Beneficiário
+boleto.cedente = 'João da Silva Santos'
+boleto.cedente_documento = '123.456.789-01'
+boleto.cedente_logradouro = 'Rua das Flores, 123'
+boleto.cedente_bairro = 'Centro'
+boleto.cedente_cidade = 'São Paulo'
+boleto.cedente_uf = 'SP'
+boleto.cedente_cep = '12345-678'
+boleto.agencia_cedente = '9999'
+boleto.conta_cedente = '99999'
+
+# Datas
+boleto.data_vencimento = datetime.date(2026, 3, 27)
+boleto.data_documento = datetime.date(2025, 2, 12)
+boleto.data_processamento = datetime.date(2025, 2, 12)
+
+# Dados do Pagador
+boleto.sacado_nome = 'Maria Oliveira Costa'
+boleto.sacado_documento = '987.654.321-00'
+boleto.sacado_endereco = 'Avenida Paulista, 1000'
+boleto.sacado_bairro = 'Bela Vista'
+boleto.sacado_cidade = 'São Paulo'
+boleto.sacado_uf = 'SP'
+boleto.sacado_cep = '01310-100'
+
+# Valor e instruções
+boleto.valor_documento = 1250.00
+boleto.instrucoes = ["- Pagamento de serviços"]
+boleto.demonstrativo = ["- Serviço prestado"]
+
+# HABILITA LGPD
+boleto.lgpd_habilitar = True
+
+# Gera o PDF
+boleto_pdf = BoletoPDF('boleto-mascarado.pdf')
+boleto_pdf.drawBoleto(boleto)
+boleto_pdf.save()
+
+print("Boleto gerado com dados mascarados!")
+```
+
+### Exemplo 2: Ver Dados Mascarados
+
+```python
+# Visualizar como os dados serão mascarados antes de gerar o boleto
+boleto.lgpd_habilitar = True
+dados_mascarados = boleto.obter_dados_lgpd()
+
+print("Dados originais vs mascarados:")
+print(f"Nome: {boleto.cedente} → {dados_mascarados['cedente']}")
+print(f"CPF: {boleto.cedente_documento} → {dados_mascarados['cedente_documento']}")
+```
+
+### Exemplo 3: HTML com LGPD
+
+```python
+from pyboleto.html import BoletoHTML
+
+# Cria boleto com LGPD habilitada
+boleto.lgpd_habilitar = True
+
+# Gera HTML
+boleto_html = BoletoHTML('boleto-mascarado.html')
+boleto_html.drawBoleto(boleto)
+boleto_html.save()
+```
+
+## Quando Usar
+
+### ✅ Recomendado Usar LGPD
+
+- Boletos de teste e desenvolvimento
+- Exemplos e documentação
+- Screenshots e tutoriais
+- Repositórios públicos no Git
+- Demonstrações e apresentações
+
+### ❌ NÃO Usar LGPD
+
+- Boletos de produção reais
+- Boletos que serão efetivamente pagos
+- Quando o destinatário precisa dos dados completos
+- Boletos para impressão e uso oficial
+
+## Testes
+
+O projeto inclui testes completos para a funcionalidade LGPD:
+
+```bash
+# Rodar testes
+python -m unittest tests.test_lgpd -v
+
+# Rodar exemplo
+python bin/exemplo_lgpd.py
+```
+
+## API Reference
+
+### Parâmetros do BoletoData
+
+```python
+BoletoData(
+    lgpd_habilitar=False,  # Habilita mascaramento (padrão: False)
+    lgpd_campos=None,      # Lista de campos a mascarar (None = todos)
+    # ... outros parâmetros ...
+)
+```
+
+### Método obter_dados_lgpd()
+
+```python
+dados_mascarados = boleto.obter_dados_lgpd()
+# Retorna: dict com dados mascarados ou {} se LGPD desabilitada
+```
+
+### Funções do Módulo lgpd
+
+```python
+from pyboleto.lgpd import (
+    mascara_cpf,           # Mascara CPF
+    mascara_cnpj,          # Mascara CNPJ
+    mascara_documento,     # Mascara CPF ou CNPJ automaticamente
+    mascara_nome,          # Mascara nome
+    mascara_endereco,      # Mascara endereço
+    mascara_cep,           # Mascara CEP
+    mascara_cidade,        # Mascara cidade
+    mascara_bairro,        # Mascara bairro
+    aplicar_lgpd,          # Aplica LGPD em um BoletoData
+)
+```
+
+## Conformidade Legal
+
+Esta implementação segue as diretrizes da **Lei nº 13.709/2018 (LGPD)**, especificamente:
+
+- **Art. 6º** - Princípio da segurança e prevenção
+- **Art. 46** - Proteção de dados pessoais
+- **Art. 48** - Comunicação de incidente de segurança
+
+O mascaramento ajuda a:
+1. Minimizar exposição de dados pessoais
+2. Reduzir riscos de vazamento de informações
+3. Proteger privacidade em ambientes de desenvolvimento
+4. Facilitar demonstrações sem expor dados reais
+
+## Contribuindo
+
+Contribuições são bem-vindas! Se você encontrar bugs ou tiver sugestões de melhorias para a funcionalidade LGPD, por favor:
+
+1. Abra uma issue no GitHub
+2. Envie um pull request com testes
+3. Documente as mudanças
+
+## Licença
+
+Esta funcionalidade está sob a mesma licença BSD do projeto PyBoleto.
+
+---
+
+**Importante:** O mascaramento LGPD é uma ferramenta para proteger dados em ambientes de teste e desenvolvimento. Para boletos de produção, os dados devem estar completos e corretos conforme especificações da FEBRABAN.