pypix-api Documentation

Biblioteca em Python para comunicação com APIs bancárias focada na integração com o PIX.

Overview

pypix-api é uma biblioteca Python que simplifica a integração com APIs bancárias brasileiras para operações PIX. Atualmente suporta Banco do Brasil e Sicoob, com planos de expansão para outros bancos.

Principais funcionalidades:

🏦 Bancos suportados: Banco do Brasil, Sicoob
🔐 Autenticação: OAuth2 com certificados mTLS
💰 PIX: Cobranças imediatas e com vencimento
🔄 Recorrência: Gestão de cobranças recorrentes
🪝 Webhooks: Configuração e gerenciamento
🔍 Consultas: PIX, devoluções e relatórios

Quick Start

Installation

pip install pypix-api

Basic Usage

from pypix_api.auth.oauth2 import OAuth2Client
from pypix_api.banks.bb import BBPixAPI

# Configure OAuth2 authentication
oauth_client = OAuth2Client(
    client_id='your-client-id',
    client_secret='your-client-secret',
    cert_path='path/to/certificate.p12',
    cert_password='cert-password',
    scope='cob.write cob.read'
)

# Create PIX API instance
api = BBPixAPI(oauth=oauth_client)

# Create a PIX charge
charge_data = {
    'calendario': {'expiracao': 3600},
    'devedor': {
        'cpf': '12345678901',
        'nome': 'João Silva'
    },
    'valor': {'original': '100.00'},
    'chave': 'your-pix-key',
    'solicitacaoPagador': 'Pagamento do produto X'
}

result = api.criar_cob('txid123', charge_data)
print(f"Charge created: {result}")

API Reference

Contents:

Authentication

class pypix_api.auth.oauth2.OAuth2Client(token_url, client_id=None, cert=None, pvk=None, cert_pfx=None, pwd_pfx=None, sandbox_mode=False)[source]

Bases: object

Cliente OAuth2 para autenticação com a API

__init__(token_url, client_id=None, cert=None, pvk=None, cert_pfx=None, pwd_pfx=None, sandbox_mode=False)[source]

Inicializa o cliente OAuth2

Parameters:

token_url (str) – URL de autenticação OAuth2
client_id (str | None) – Client ID para autenticação OAuth2
cert (str | None) – Path para o certificado PEM (opcional)
pvk (str | None) – Path para a chave privada PEM (opcional)
cert_pfx (str | bytes | BinaryIO | None) – Path ou dados do certificado PFX (opcional)
pwd_pfx (str | None) – Senha do certificado PFX (opcional)
sandbox_mode (bool) – Se True, não requer certificado (default: False)

get_token(scope=None)[source]

Obtém ou renova o token de acesso para o escopo especificado

Parameters:: scope (str | None) – Escopo(s) necessário(s) para a API. Exemplos: - Cobrança por Boleto: “boletos_inclusao boletos_consulta boletos_alteracao webhooks_alteracao webhooks_consulta webhooks_inclusao” - Conta Corrente: “cco_consulta cco_transferencias openid” - Recebimento no PIX: “cob.write cob.read cobv.write cobv.read lotecobv.write lotecobv.read pix.write pix.read webhook.read webhook.write payloadlocation.write payloadlocation.read”
Returns:: Token de acesso válido para o escopo solicitado
Return type:: str

Banks

Banco do Brasil

class pypix_api.banks.bb.BBPixAPI(oauth, sandbox_mode=False)[source]

Bases: PixBBMethods, BankPixAPIBase

Implementação da API PIX do Banco do Brasil.

Parameters:

oauth (OAuth2Client) – Instância configurada de OAuth2Client para autenticação
sandbox_mode (bool) – Se True, usa ambiente de sandbox (default: False)

BASE_URL: URL da API de produção

SANDBOX_BASE_URL: URL da API de sandbox

TOKEN_URL: URL para obtenção de token OAuth2

SCOPES: Scopes necessários para autenticação

BASE_URL: str | None = 'https://api-pix.bb.com.br/pix/v2'

SANDBOX_BASE_URL = 'https://api-pix.hm.bb.com.br/pix/v2'

TOKEN_URL: str | None = 'https://oauth.bb.com.br/oauth/token'

get_bank_code()[source]

Return type:: str

get_base_url()[source]

Obtém a URL base da API de acordo com o modo de operação.

Returns:: URL base da API (produção ou sandbox)
Return type:: str

Note

O modo sandbox é controlado pelo parâmetro sandbox_mode passado no construtor

Sicoob

class pypix_api.banks.sicoob.SicoobPixAPI(oauth, sandbox_mode=False)[source]

Bases: BankPixAPIBase

Implementação da API PIX do Sicoob.

Parameters:

oauth (OAuth2Client) – Instância configurada de OAuth2Client para autenticação
sandbox_mode (bool) – Se True, usa ambiente de sandbox (default: False)

BASE_URL: URL da API de produção

SANDBOX_BASE_URL: URL da API de sandbox

TOKEN_URL: URL para obtenção de token OAuth2

SCOPES: Scopes necessários para autenticação

BASE_URL: str | None = 'https://api.sicoob.com.br/pix/api/v2'

SANDBOX_BASE_URL = 'https://sandbox.sicoob.com.br/sicoob/sandbox/pix/api/v2'

TOKEN_URL: str | None = 'https://auth.sicoob.com.br/auth/realms/cooperado/protocol/openid-connect/token'

get_bank_code()[source]

Return type:: str

get_base_url()[source]

Obtém a URL base da API de acordo com o modo de operação.

Returns:: URL base da API (produção ou sandbox)
Return type:: str

Note

O modo sandbox é controlado pelo parâmetro sandbox_mode passado no construtor

Examples

Examples:

Contributing

See our Contributing Guide for information on how to contribute to this project.

Security

For security vulnerabilities, please see our Security Policy.

Changelog

See the Changelog for a detailed history of changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

pypix-api Documentation

Overview

Quick Start

Installation

Basic Usage

API Reference

Authentication

Banks

Banco do Brasil

Sicoob

Examples

Contributing

Security

Changelog

License

Indices and tables