Metadata-Version: 2.1
Name: pyinterboleto
Version: 0.0.2
Summary: Biblioteca para facilitar o manuseio de boletos de contas PJ no Banco Inter.
Home-page: https://github.com/feslima/pyinterboleto
Author: Felipe Souza Lima
Author-email: feslima93@gmail.com
License: UNKNOWN
Project-URL: Bug Tracker, https://github.com/feslima/pyinterboleto/issues
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# PyInterBoleto
Biblioteca para facilitar o manuseio de boletos de contas PJ no Banco Inter.

***
- [PyInterBoleto](#pyinterboleto)
- [Instalação](#instalação)
- [Documentação](#documentação)
- [Usagem básica](#usagem-básica)
  - [Configuração de autenticação](#configuração-de-autenticação)
  - [Emissão de boleto](#emissão-de-boleto)
  - [Consultas](#consultas)
    - [Consulta detalhada de boletos individuais](#consulta-detalhada-de-boletos-individuais)
    - [Consulta de coleção de boletos](#consulta-de-coleção-de-boletos)
    - [Resgate de PDFs de boletos individuais](#resgate-de-pdfs-de-boletos-individuais)
  - [Baixa de boleto](#baixa-de-boleto)
- [Testagem](#testagem)

# Instalação
Basta executar o comando via pip:
```
pip install pyinterboleto
```

# Documentação
A maioria das classes, métodos, funções e estruturas de dados já contém uma documentação habilitada para uso em IDEs no estilo [numpy docstring](https://numpydoc.readthedocs.io/en/latest/format.html).

Foi optado por não fazer uma documentação exclusiva (no estilo readthedocs) devido a ser uma biblioteca relativamente pequena.

Sendo assim, o pacote está organizado em três submódulos principais: **emissão** (os dados necessários na emissão são organizados em estruturas menores. São elas dados de: [emissão](src/pyinterboleto/emissao/emissor.py), [pagador](src/pyinterboleto/emissao/pagador.py), [desconto](src/pyinterboleto/emissao/desconto.py), [multa](src/pyinterboleto/emissao/multa.py), [mora](src/pyinterboleto/emissao/mora.py) e [mensagem](src/pyinterboleto/emissao/mensagem.py)), **consulta** ([detalhada](src/pyinterboleto/consulta/detalhado.py), [coleção](src/pyinterboleto/consulta/lista.py) e [PDF](src/pyinterboleto/consulta/pdf.py)) e [**baixa**](src/pyinterboleto/baixa/__init__.py) de boletos.

Em cada um desses links se encontram as funções e objetos com suas respectivas documentações, caso seja preciso mais informações.
# Usagem básica
A classe principal que tem todas as funcionalidades requeridas para a API se chama [**`Boleto`**](src/pyinterboleto/boleto.py). Através dela que todas as operações de emissão, consulta e baixa feitas. 

No entanto, como consta na documentação do Banco Inter, para se ter acesso a API é preciso emitir a chave e o certificado de acesso desta. Antes de utilizar este pacote, certifique-se que você já possui estes arquivos.

Feito isto, alguns exemplos de manuseio são mostrados nas seções à seguir.
***

## Configuração de autenticação
Antes de fazer qualquer requisição à API do Inter é preciso antes definir o [objeto de configuração](src/pyinterboleto/utils/requests.py) para autenticação e autorização:

```python
>>> from pathlib import Path
>>> from datetime import date, timedelta
>>> from pprint import pprint
>>> from pyinterboleto import RequestConfigs
>>> 
>>> # definição da configuração de autenticação
>>> direc = Path('caminho/para/pasta/com/certificados')
>>> cert = direc / 'Inter API_Certificado.crt'
>>> key = direc / 'Inter API_Chave.key'
>>> acc = '12345678' # Número da conta PJ
>>> configs = RequestConfigs(conta_inter=acc, certificate=cert, key=key)
```

## Emissão de boleto
_*Os dados a seguir são fictícios. Não os utilize do jeito que estão!*_

```python
>>> from pyinterboleto import Boleto, Emissao, Pagador, RequestConfigs
>>> boleto = Boleto(configs) # configs vem da seção configuração
>>>
>>> pagador = Pagador(
...     tipoPessoa='FISICA',
...     cnpjCpf='123.456.789-09',
...     nome="Pessoa Ficticia da Silva",
...     endereco="Rua Fantasia",
...     numero='300',
...     bairro='Centro',
...     cidade='São Paulo',
...     uf='SP',
...     cep='123456-789'
... )
>>>
>>> emissao = Emissao(
...     pagador=pagador, seuNumero='00001',
...     cnpjCPFBeneficiario='12.345.678/0001-01',
...     valorNominal=0.01,
...     dataEmissao=date.today(),
...     dataVencimento=date.today()+timedelta(days=2)
... )
>>>
>>> result = boleto.emitir(emissao)
>>> print(result)
{'seuNumero': '00001', 'nossoNumero': '00123456789', 
 'codigoBarras': '00000000000000000000000000000000000000000000', 
 'linhaDigitavel': '00000000000000000000000000000000000000000000000'}
>>>
```

## Consultas
Há três categorias de consultas disponíveis: detalhamento individual de boletos, coleção de boletos e resgate de arquivos .pdf.

### Consulta detalhada de boletos individuais
É preciso saber o número de identificação do título antes de fazer esta requisição. Este número pode ser obtido quando a emissão do título é bem sucedida (chave `nossoNumero` do dicionário de resposta na seção anterior)
ou quando se faz a filtragem de coleções de boletos.

```python
>>> boleto = Boleto(configs)
>>> num_boleto = '00123456789' # numero de identificação do título pelo Inter
>>> detail = boleto.consulta_detalhada(num_boleto)
>>> print(detail)
{'cnpjCpfBeneficiario': '00000000000000',
'cnpjCpfPagador': '12345678909',
'codigoBarras': '00000000000000000000000000000000000000000000',
'codigoEspecie': 'OUTROS',
'dataEmissao': '01/05/2021',
'dataHoraSituacao': '01/05/2021 15:22',
'dataLimitePagamento': '11/06/2021',
'dataVencimento': '12/05/2021',
'dddPagador': '',
'desconto1': Desconto(codigoDesconto=<CodigoDescontoEnum.NTD: 'NAOTEMDESCONTO'>, taxa=0.0, valor=0.0, data=''),
'desconto2': Desconto(codigoDesconto=<CodigoDescontoEnum.NTD: 'NAOTEMDESCONTO'>, taxa=0.0, valor=0.0, data=''),
'desconto3': Desconto(codigoDesconto=<CodigoDescontoEnum.NTD: 'NAOTEMDESCONTO'>, taxa=0.0, valor=0.0, data=''),
'emailPagador': '',
'linhaDigitavel': '00000000000000000000000000000000000000000000000',
'mora': Mora(codigoMora=<CodigoMoraEnum.I: 'ISENTO'>, taxa=0.0, valor=0.0, data=''),
'multa': Multa(codigoMulta=<CodigoMultaEnum.NTM: 'NAOTEMMULTA'>, taxa=0.0, valor=0.0, data=''),
'nomeBeneficiario': 'NOME DO BENEFICIARIO CONTA PJ',
'nomePagador': 'Pessoa Ficticia da Silva',
'seuNumero': '00001',
'situacao': 'EMABERTO',
'telefonePagador': '',
'tipoPessoaBeneficiario': 'JURIDICA',
'tipoPessoaPagador': 'FISICA',
'valorAbatimento': 0.0,
'valorNominal': 0.01}
>>>
```

### Consulta de coleção de boletos
As datas de início e final da filtragem são obrigatórias, [há outras definições de elementos de filtragem opcionais](src/pyinterboleto/consulta/lista.py).

```python
>>> from datetime import date, timedelta
>>> boleto = Boleto(configs)
>>> inicial = date.today() - timedelta(days=30)
>>> final = date.today()
>>> lista = boleto.consulta_lista(inicial, final)
>>> print(lista)
{'content': [{'cnpjCpfSacado': '12345678909',
    'dataEmissao': '09/01/2021',
    'dataLimite': '10/02/2021',
    'dataVencimento': '21/01/2021',
    'desconto1': {'codigo': 'NAOTEMDESCONTO',
                'taxa': 0.0,
                'valor': 0.0},
    'desconto2': {'codigo': 'NAOTEMDESCONTO',
                'taxa': 0.0,
                'valor': 0.0},
    'desconto3': {'codigo': 'NAOTEMDESCONTO',
                'taxa': 0.0,
                'valor': 0.0},
    'email': '',
    'linhaDigitavel': '00000000000000000000000000000000000000000000000',
    'mora': {'codigo': 'ISENTO', 'taxa': 0.0, 'valor': 0.0},
    'multa': {'codigo': 'NAOTEMMULTA', 'taxa': 0.0, 'valor': 0.0},
    'nomeSacado': 'Pessoa Ficticia da Silva',
    'nossoNumero': '00000000000',
    'seuNumero': '00001',
    'situacao': 'EMABERTO',
    'telefone': '',
    'valorAbatimento': 0.0,
    'valorJuros': 0.0,
    'valorMulta': 0.0,
    'valorNominal': 0.01}],
    'first': True,
    'last': True,
    'numberOfElements': 1,
    'size': 20,
    'summary': {'baixados': {'quantidade': 0, 'valor': 0},
                'expirados': {'quantidade': 0, 'valor': 0},
                'previstos': {'quantidade': 1, 'valor': 0.01},
                'recebidos': {'quantidade': 0, 'valor': 0}},
    'totalElements': 1,
    'totalPages': 1}
>>>
```

### Resgate de PDFs de boletos individuais
Assim como na consulta detalhada individual, é preciso saber o número de identificação do título antes de fazer a requisição. Há dois modos de como o PDF é armazendo: em memória ou salvo diretamento em um arquivo especificado.

```python
>>> from pathlib import Path
>>> boleto = Boleto(configs)
>>> num_boleto = '00123456789'
>>> # Armazenado em um buffer de bytes na memória
>>> pdf = boleto.consulta_pdf(num_boleto)
>>>
>>> # salva em um arquivo chamado 'boleto.pdf' no diretório atual
>>> filename = Path().resolve() / 'boleto.pdf'
>>> boleto.consulta_pdf(num_boleto, filename)
>>>
```

***

## Baixa de boleto
Também é preciso saber o número de identificação do título. Os tipos de baixas são definidos no enum [`CodigoBaixaEnum`](src/pyinterboleto/baixa/__init__.py).

```python
>>> from pyinterboleto import CodigoBaixaEnum
>>> boleto = Boleto(configs)
>>> num_boleto = '00123456789'
>>> boleto.baixar_boleto(num_boleto, CodigoBaixaEnum.PC)
>>>
```

***

# Testagem

Como a API do Inter não possui ambiente de sandboxing, optei por não implementar rotinas de testes. Isto é, o Inter fornece uma cota sem custo adicional de 100 boletos emitidos por mês. Acima disto, é preciso pagar mais.

Como é um recurso bem limitado, não faz sentido implementar uma suíte de testes para emissão e baixa de boletos. No caso de consultas, é possível sim. So não implementei por pura falta de tempo (~~e preguiça também~~).

