Skip to main content

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

Project description

PyInterBoleto

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


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.

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, pagador, desconto, multa, mora e mensagem), consulta (detalhada, coleção e PDF) e baixa 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. 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 para autenticação e autorização:

>>> 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!

>>> 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.

>>> 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.

>>> 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.

>>> 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.

>>> 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).

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyinterboleto-0.0.2.tar.gz (22.6 kB view hashes)

Uploaded Source

Built Distribution

pyinterboleto-0.0.2-py3-none-any.whl (27.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page