pypix_api package

pypix-api: Biblioteca Python para integracao com APIs bancarias do PIX.

Esta biblioteca facilita a integracao com APIs de bancos brasileiros, fornecendo uma interface simples e consistente para operacoes PIX.

class pypix_api.BBPixAPI(oauth, sandbox_mode=False, timeout=None, scopes=None)[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

class pypix_api.InterPixAPI(oauth, sandbox_mode=False, timeout=None, scopes=None, *, conta_corrente=None, homologacao=False)[source]

Bases: PixInterMethods, BankPixAPIBase

Implementação da API PIX do Banco Inter.

Uma única versão (/pix/v2) cobre o Pix comum e o Pix Automático. A autenticação exige mTLS + OAuth2 client_credentials com client_id e client_secret no corpo do form — construa o OAuth2Client com client_secret e client_auth='body'.

Parameters:

  • oauth (OAuth2Client) – Instância configurada de OAuth2Client para autenticação

  • sandbox_mode (bool) – Se True, usa as URLs do Sandbox com token fixo, sem OAuth — útil só para testes locais; o Sandbox do Inter recusa o token fixo. Para o Sandbox real, use homologacao (default: False)

  • timeout (float | tuple[float, float] | tuple[float, None] | None) – Tempo limite das requisições (ver BankPixAPIBase)

  • scopes (str | ScopeGroup | list[str | ScopeGroup] | None) – Escopos OAuth2 a solicitar (ver BankPixAPIBase)

  • conta_corrente (str | int | None) – Conta corrente da operação, enviada no header x-conta-corrente. Necessária só quando a integração estiver associada a mais de uma conta. Apenas números, incluindo o dígito; hífen, ponto, espaços e zeros à esquerda são removidos

  • homologacao (bool) – Se True, usa as URLs do Sandbox do Inter com OAuth e mTLS reais — o Sandbox do Inter exige certificado e credenciais da integração de testes. Use com token_url=InterPixAPI.SANDBOX_TOKEN_URL. Libera os métodos sandbox_* (default: False)

BASE_URL

URL da API de produção

SANDBOX_BASE_URL

URL da API do Sandbox

TOKEN_URL

URL para obtenção de token OAuth2 (produção)

SANDBOX_TOKEN_URL

URL para obtenção de token OAuth2 (Sandbox)

Raises:

ValueError – Se conta_corrente não contiver um número válido

BASE_URL: str | None = 'https://cdpj.partners.bancointer.com.br/pix/v2'
SANDBOX_BASE_URL = 'https://cdpj-sandbox.partners.uatinter.co/pix/v2'
TOKEN_URL: str | None = 'https://cdpj.partners.bancointer.com.br/oauth/v2/token'
SANDBOX_TOKEN_URL = 'https://cdpj-sandbox.partners.uatinter.co/oauth/v2/token'
PARAM_TXID_CONSULTA_PIX = 'txId'

Nome do filtro de txid na query de GET /pix. A especificação do BACEN usa txid; bancos que divergem (Inter: txId) sobrescrevem.

__init__(oauth, sandbox_mode=False, timeout=None, scopes=None, *, conta_corrente=None, homologacao=False)[source]
conta_corrente: str | None
homologacao: bool
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

listar_webhooks(inicio, fim, pagina_atual=0, itens_por_pagina=100)[source]

Não suportado: o Inter não oferece GET /webhook.

Raises:

NotImplementedError – Sempre. Use consultar_webhook(chave)

Return type:

dict[str, Any]

class pypix_api.OAuth2Client(token_url, client_id=None, cert=None, pvk=None, cert_pfx=None, pwd_pfx=None, sandbox_mode=False, client_secret=None, timeout=None, client_auth='basic')[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, client_secret=None, timeout=None, client_auth='basic')[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)

  • client_secret (str | None) – Client Secret para autenticação via HTTP Basic (opcional). Quando informado, o token é solicitado com o header Authorization: Basic base64(client_id:client_secret), como exigido por PSPs como o Sicredi. Quando omitido, mantém o fluxo padrão (client_id no corpo, autenticação de cliente via mTLS). Mantido como último parâmetro para preservar a ordem posicional histórica da assinatura.

  • timeout (float | tuple[float, float] | tuple[float, None] | None) – Tempo limite da requisição de token, no formato aceito pelo requests: um número ou a tupla (conexão, leitura). None usa DEFAULT_TIMEOUT. Para leitura sem limite, use (5.0, None).

  • client_auth (str) – Como o client_secret é apresentado ao PSP, quando informado. 'basic' (padrão) usa o header Authorization: Basic (Sicredi); 'body' envia client_id e client_secret no corpo do form, como exige o Banco Inter. Sem client_secret, não tem efeito.

Raises:

ValueError – Se client_auth não for 'basic' nem 'body'

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

class pypix_api.PixCobranca(txid, valor, status, chave)[source]

Bases: object

txid: str
valor: float
status: str
chave: str
__init__(txid, valor, status, chave)
class pypix_api.PoliticaRetentativa(value)[source]

Bases: str, Enum

Política de retentativa de uma recorrência ou cobrança recorrente.

Corresponde aos schemas RecConfiguracao e CobRConfiguracao.

Valores:

  • NAO_PERMITE: não é permitida retentativa de liquidação.

  • PERMITE_3R_7D: permite até 3 retentativas em até 7 dias.

Uma CobR só aceita POST /cobr/{txid}/retentativa/{data} se a recorrência estiver configurada com PERMITE_3R_7D.

NAO_PERMITE = 'NAO_PERMITE'
PERMITE_3R_7D = 'PERMITE_3R_7D'
class pypix_api.SicoobPixAPI(oauth, sandbox_mode=False, timeout=None, scopes=None)[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

class pypix_api.SicrediPixAPI(oauth, sandbox_mode=False, timeout=None, scopes=None)[source]

Bases: BankPixAPIBase

Implementação da API PIX do Sicredi.

Diferentemente de BB e Sicoob, a API Pix do Sicredi usa o prefixo /api com versionamento por recurso: a cobrança imediata por identificador (/cob/{txid}) está em v3, os demais recursos do Pix comum (cobv, pix, webhook, loc, lotecobv) em v2 e todo o Pix Automático (cobr, rec, locrec, solicrec, webhookcobr, webhookrec) em v1. Por isso BASE_URL aponta apenas para a raiz /api e a versão é injetada em _endpoint_url.

A autenticação exige mTLS + OAuth2 client_credentials com Authorization: Basic base64(client_id:client_secret). Passe o client_secret ao construir o OAuth2Client para ativar o fluxo Basic (ver OAuth2Client).

Parameters:

  • oauth (OAuth2Client) – Instância configurada de OAuth2Client para autenticação

  • sandbox_mode (bool) – Se True, usa ambiente de sandbox (default: False)

BASE_URL

Raiz da API de produção (sem versão)

SANDBOX_BASE_URL

Raiz da API de homologação (sem versão)

TOKEN_URL

URL para obtenção de token OAuth2 (produção)

SANDBOX_TOKEN_URL

URL para obtenção de token OAuth2 (homologação)

Note

O sandbox_mode da biblioteca usa token fixo e não faz mTLS. A homologação real do Sicredi exige mTLS + OAuth; para testá-la, use sandbox_mode=False com token_url=SicrediPixAPI.SANDBOX_TOKEN_URL e o certificado de homologação.

BASE_URL: str | None = 'https://api-pix.sicredi.com.br/api'
SANDBOX_BASE_URL = 'https://api-pix-h.sicredi.com.br/api'
TOKEN_URL: str | None = 'https://api-pix.sicredi.com.br/oauth/token'
SANDBOX_TOKEN_URL = 'https://api-pix-h.sicredi.com.br/oauth/token'
RESOURCE_VERSIONS: ClassVar[dict[str, str]] = {'cob': 'v2', 'cobr': 'v1', 'cobv': 'v2', 'loc': 'v2', 'locrec': 'v1', 'lotecobv': 'v2', 'pix': 'v2', 'rec': 'v1', 'solicrec': 'v1', 'webhook': 'v2', 'webhookcobr': 'v1', 'webhookrec': 'v1'}
RESOURCE_ITEM_VERSIONS: ClassVar[dict[str, str]] = {'cob': 'v3'}
DEFAULT_VERSION = 'v2'
get_bank_code()[source]
Return type:

str

get_base_url()[source]

Obtém a raiz da API (sem versão) de acordo com o modo de operação.

Returns:

Raiz da API (produção ou homologação)

Return type:

str

class pypix_api.StatusCob(value)[source]

Bases: str, Enum

Status do registro de uma cobrança imediata (cob) ou com vencimento (cobv).

Corresponde ao schema CobrancaStatus da especificação.

Escrivível em PATCH /cob/{txid} e PATCH /cobv/{txid}:

  • REMOVIDA_PELO_USUARIO_RECEBEDOR

Somente leitura (retornados pelo PSP ou usados como filtro em listagens):

  • ATIVA, CONCLUIDA, REMOVIDA_PELO_PSP

ATIVA = 'ATIVA'
CONCLUIDA = 'CONCLUIDA'
REMOVIDA_PELO_USUARIO_RECEBEDOR = 'REMOVIDA_PELO_USUARIO_RECEBEDOR'
REMOVIDA_PELO_PSP = 'REMOVIDA_PELO_PSP'
class pypix_api.StatusCobR(value)[source]

Bases: str, Enum

Status do registro de uma cobrança recorrente (CobR / Pix Automático).

Corresponde ao schema CobRStatus da especificação.

Escrivível em PATCH /cobr/{txid} (schema CobRStatusRevisada):

  • CANCELADA — único valor aceito.

Somente leitura (retornados pelo PSP ou usados como filtro em listagens):

  • CRIADA, ATIVA, CONCLUIDA, EXPIRADA, REJEITADA

Cancelar uma CobR encerra apenas aquela cobrança do ciclo; a recorrência (rec) permanece ativa. Para encerrar a recorrência inteira, use StatusRec com PATCH /rec/{idRec}.

CRIADA = 'CRIADA'
ATIVA = 'ATIVA'
CONCLUIDA = 'CONCLUIDA'
EXPIRADA = 'EXPIRADA'
REJEITADA = 'REJEITADA'
CANCELADA = 'CANCELADA'
class pypix_api.StatusRec(value)[source]

Bases: str, Enum

Status do registro de uma recorrência (Rec / Pix Automático).

Corresponde ao schema RecStatus da especificação.

Escrivível em PATCH /rec/{idRec} (schema RecRevisada):

  • CANCELADA — único valor aceito.

Somente leitura (retornados pelo PSP ou usados como filtro em listagens):

  • CRIADA, APROVADA, REJEITADA, EXPIRADA

Cancelar a recorrência encerra o vínculo por completo, inclusive as cobranças futuras. Para cancelar apenas uma cobrança do ciclo, use StatusCobR.

CRIADA = 'CRIADA'
APROVADA = 'APROVADA'
REJEITADA = 'REJEITADA'
EXPIRADA = 'EXPIRADA'
CANCELADA = 'CANCELADA'
class pypix_api.StatusSolicRec(value)[source]

Bases: str, Enum

Status de uma solicitação de confirmação de recorrência (SolicRec).

Corresponde ao schema SolicRecStatus da especificação.

Escrivível em PATCH /solicrec/{idSolicRec} (schema SolicRecRevisada):

  • CANCELADA — único valor aceito.

Somente leitura (atribuídos pelo PSP do pagador):

  • CRIADA, ENVIADA, RECEBIDA, REJEITADA, ACEITA, EXPIRADA

Atenção: REJEITADA é um status de resposta — nunca deve ser enviado em uma revisão.

CRIADA = 'CRIADA'
ENVIADA = 'ENVIADA'
RECEBIDA = 'RECEBIDA'
REJEITADA = 'REJEITADA'
ACEITA = 'ACEITA'
EXPIRADA = 'EXPIRADA'
CANCELADA = 'CANCELADA'
pypix_api.gerar_id_rec(ispb, politica_retentativa, data_criacao=None, sequencial=None)[source]

Gera um idRec válido para criação de recorrência (Pix Automático).

Monta o identificador conforme a regra de formação do schema RecId:

RAxxxxxxxxyyyyMMddkkkkkkkkkkk   (29 caracteres, case sensitive)

R           fixo, recorrência criada dentro do Pix
A           'R' permite retentativa pós-vencimento, 'N' não permite
xxxxxxxx    ISPB do participante (8 dígitos)
yyyyMMdd    data de criação da recorrência
kkkkkkkkkkk sequencial alfanumérico (11 caracteres)

O segundo caractere é derivado de politica_retentativa, garantindo que o identificador e o campo politicaRetentativa do corpo da recorrência não fiquem contraditórios — uma inconsistência que o schema não detecta.

Parameters:

  • ispb (str) – ISPB do participante direto/indireto ou os 8 primeiros dígitos do CNPJ do prestador de serviço de iniciação. 8 dígitos em [0-9].

  • politica_retentativa (PoliticaRetentativa | str) – Política de retentativa da recorrência. Aceita um membro de PoliticaRetentativa ou a string equivalente. Deve ser o mesmo valor enviado no corpo.

  • data_criacao (date | None) – Data de criação da recorrência. Padrão: data corrente.

  • sequencial (str | None) – Sequencial de 11 caracteres em [a-zA-Z0-9], único dentro da data de criação. Padrão: gerado aleatoriamente.

Returns:

identificador de 29 caracteres.

Return type:

str

Raises:

ValueError – Se o ISPB não tiver 8 dígitos em [0-9], se a política de retentativa for desconhecida ou se o sequencial informado não tiver 11 caracteres em [a-zA-Z0-9].

Nota:

O sequencial gerado automaticamente é aleatório (62^11 combinações), o que torna a colisão dentro de um mesmo dia improvável, mas não impossível. Quando houver controle transacional do lado da aplicação, informe sequencial explicitamente.

exception pypix_api.APIError(message, status_code=None, response_body=None, **kwargs)[source]

Bases: PIXError

Raised when API call fails.

__init__(message, status_code=None, response_body=None, **kwargs)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code – Machine-readable error code

  • details – Additional error context

  • cause – Original exception that caused this error

exception pypix_api.AuthenticationError(message='Authentication failed', **kwargs)[source]

Bases: PIXError

Raised when authentication fails.

__init__(message='Authentication failed', **kwargs)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code – Machine-readable error code

  • details – Additional error context

  • cause – Original exception that caused this error

class pypix_api.MetricsCollector[source]

Bases: object

Coletor central de metricas.

static __new__(cls)[source]

Singleton pattern for metrics collector.

__init__()[source]

Initialize metrics collector.

increment(name, value=1, tags=None)[source]

Increment a counter metric.

Return type:

None

gauge(name, value, tags=None)[source]

Set a gauge metric value.

Return type:

None

histogram(name, value, tags=None)[source]

Record a histogram value.

Return type:

None

timing(name, duration, tags=None)[source]

Record timing metric in seconds.

Return type:

None

record_api_call(method, endpoint, status_code, response_time, bank, error=None)[source]

Record API call metrics.

Return type:

None

get_summary()[source]

Get metrics summary.

Return type:

dict[str, Any]

flush_metrics(export_path=None)[source]

Flush metrics to storage/export.

Return type:

bool

clear_metrics()[source]

Clear all collected metrics.

Return type:

None

exception pypix_api.PIXError(message, error_code=None, details=None, cause=None)[source]

Bases: Exception

Base exception class for pypix-api errors.

__init__(message, error_code=None, details=None, cause=None)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code (str | None) – Machine-readable error code

  • details (dict[str, Any] | None) – Additional error context

  • cause (Exception | None) – Original exception that caused this error

to_dict()[source]

Convert error to dictionary representation.

Return type:

dict[str, Any]

__str__()[source]

String representation of error.

Return type:

str

class pypix_api.PIXLogger(name='pypix_api')[source]

Bases: object

Logger principal para operacoes PIX.

static __new__(cls, name='pypix_api')[source]

Singleton pattern para loggers.

__init__(name='pypix_api')[source]

Initialize PIX logger.

add_context(**kwargs)[source]

Add context to all subsequent log messages.

Return type:

None

clear_context()[source]

Clear logging context.

Return type:

None

debug(message, **kwargs)[source]

Log debug message.

Return type:

None

info(message, **kwargs)[source]

Log info message.

Return type:

None

warning(message, **kwargs)[source]

Log warning message.

Return type:

None

error(message, **kwargs)[source]

Log error message.

Return type:

None

critical(message, **kwargs)[source]

Log critical message.

Return type:

None

exception pypix_api.ValidationError(message='Validation failed', field=None, **kwargs)[source]

Bases: PIXError

Raised when data validation fails.

__init__(message='Validation failed', field=None, **kwargs)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code – Machine-readable error code

  • details – Additional error context

  • cause – Original exception that caused this error

pypix_api.configure_observability(config=None)[source]

Configure global observability settings.

pypix_api.get_metrics_summary()[source]

Get current metrics summary.

Return type:

dict[str, Any]

pypix_api.get_observability_status()[source]

Get current observability system status.

Return type:

dict[str, Any]

pypix_api.setup_logging(level='INFO', log_file=None, structured=False)[source]

Configure global logging for pypix-api.

Parameters:

  • level (str) – Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

  • log_file (str | None) – Optional file path for logging

  • structured (bool) – Use structured JSON logging

Return type:

PIXLogger

Returns:

Configured PIXLogger instance

Subpackages

Submodules

pypix_api.error_handling module

Sistema avancado de tratamento de erros para pypix-api.

Este modulo fornece classes de erro especializadas, context managers para tratamento robusto de erros e utilitarios para debugging avancado.

exception pypix_api.error_handling.APIError(message, status_code=None, response_body=None, **kwargs)[source]

Bases: PIXError

Raised when API call fails.

__init__(message, status_code=None, response_body=None, **kwargs)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code – Machine-readable error code

  • details – Additional error context

  • cause – Original exception that caused this error

exception pypix_api.error_handling.AuthenticationError(message='Authentication failed', **kwargs)[source]

Bases: PIXError

Raised when authentication fails.

__init__(message='Authentication failed', **kwargs)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code – Machine-readable error code

  • details – Additional error context

  • cause – Original exception that caused this error

exception pypix_api.error_handling.AuthorizationError(message='Authorization failed', **kwargs)[source]

Bases: PIXError

Raised when authorization/permission fails.

__init__(message='Authorization failed', **kwargs)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code – Machine-readable error code

  • details – Additional error context

  • cause – Original exception that caused this error

exception pypix_api.error_handling.BankSpecificError(message, bank_code=None, bank_error_code=None, **kwargs)[source]

Bases: PIXError

Raised for bank-specific errors.

__init__(message, bank_code=None, bank_error_code=None, **kwargs)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code – Machine-readable error code

  • details – Additional error context

  • cause – Original exception that caused this error

exception pypix_api.error_handling.CertificateError(message='Certificate error', **kwargs)[source]

Bases: PIXError

Raised when certificate handling fails.

__init__(message='Certificate error', **kwargs)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code – Machine-readable error code

  • details – Additional error context

  • cause – Original exception that caused this error

exception pypix_api.error_handling.ConfigurationError(message='Configuration error', **kwargs)[source]

Bases: PIXError

Raised when configuration is invalid.

__init__(message='Configuration error', **kwargs)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code – Machine-readable error code

  • details – Additional error context

  • cause – Original exception that caused this error

class pypix_api.error_handling.ErrorContext(operation, context=None, handler=None, reraise=True)[source]

Bases: object

Context manager for robust error handling.

__init__(operation, context=None, handler=None, reraise=True)[source]

Initialize error context.

Parameters:

  • operation (str) – Name of operation being performed

  • context (dict | None) – Additional context for error handling

  • handler (ErrorHandler | None) – Custom error handler

  • reraise (bool) – Whether to reraise handled errors

__enter__()[source]

Enter error context.

__exit__(exc_type, exc_val, exc_tb)[source]

Handle any exception that occurred.

class pypix_api.error_handling.ErrorHandler(logger=None)[source]

Bases: object

Advanced error handler with logging and metrics integration.

__init__(logger=None)[source]

Initialize error handler.

classify_error(error, context=None)[source]

Classify a generic exception as a specific PIX error.

Return type:

PIXError

handle_error(error, context=None, reraise=True)[source]

Handle an error with logging and metrics.

Return type:

PIXError | None

class pypix_api.error_handling.ErrorRecovery[source]

Bases: object

Utilities for error recovery and retry logic.

static should_retry(error, max_retries=3)[source]

Determine if an operation should be retried.

Return type:

bool

static get_retry_delay(attempt, base_delay=1.0)[source]

Calculate retry delay using exponential backoff.

Return type:

float

static retry_with_backoff(func, max_retries=3, base_delay=1.0, logger=None)[source]

Retry function with exponential backoff.

Return type:

Any

exception pypix_api.error_handling.NetworkError(message='Network communication failed', **kwargs)[source]

Bases: PIXError

Raised when network communication fails.

__init__(message='Network communication failed', **kwargs)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code – Machine-readable error code

  • details – Additional error context

  • cause – Original exception that caused this error

exception pypix_api.error_handling.PIXError(message, error_code=None, details=None, cause=None)[source]

Bases: Exception

Base exception class for pypix-api errors.

__init__(message, error_code=None, details=None, cause=None)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code (str | None) – Machine-readable error code

  • details (dict[str, Any] | None) – Additional error context

  • cause (Exception | None) – Original exception that caused this error

to_dict()[source]

Convert error to dictionary representation.

Return type:

dict[str, Any]

__str__()[source]

String representation of error.

Return type:

str

exception pypix_api.error_handling.PIXTransactionError(message, txid=None, operation=None, **kwargs)[source]

Bases: PIXError

Raised when PIX transaction fails.

__init__(message, txid=None, operation=None, **kwargs)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code – Machine-readable error code

  • details – Additional error context

  • cause – Original exception that caused this error

exception pypix_api.error_handling.RateLimitError(message='Rate limit exceeded', retry_after=None, **kwargs)[source]

Bases: PIXError

Raised when API rate limit is exceeded.

__init__(message='Rate limit exceeded', retry_after=None, **kwargs)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code – Machine-readable error code

  • details – Additional error context

  • cause – Original exception that caused this error

exception pypix_api.error_handling.ValidationError(message='Validation failed', field=None, **kwargs)[source]

Bases: PIXError

Raised when data validation fails.

__init__(message='Validation failed', field=None, **kwargs)[source]

Initialize PIX error.

Parameters:

  • message (str) – Human-readable error message

  • error_code – Machine-readable error code

  • details – Additional error context

  • cause – Original exception that caused this error

pypix_api.error_handling.create_error_report(error, include_system_info=True)[source]

Create comprehensive error report for debugging.

Return type:

dict[str, Any]

pypix_api.error_handling.handle_errors(operation, context=None, reraise=True, logger=None)[source]

Decorator for automatic error handling.

pypix_api.exceptions module

Hierarquia de exceções da biblioteca.

Toda falha levantada pelo pypix_api — erro devolvido pelo PSP, resposta fora do contrato ou falha de transporte — herda de PixAPIException, de modo que um único except cobre o caminho inteiro, incluindo a requisição de token.

Mora fora de banks/ porque também é usada pelo auth/; o módulo pypix_api.banks.exceptions reexporta tudo para não quebrar imports existentes.

exception pypix_api.exceptions.PixAPIException(type_='', title='', status=None, detail='', violacoes=None)[source]

Bases: Exception

Exceção base para erros da API Pix.

Parameters:

  • type – URI do tipo de erro devolvida pelo PSP

  • title (str) – Título do erro

  • status (int | None) – Código HTTP da resposta. None quando a falha ocorreu antes de haver resposta (timeout, erro de conexão)

  • detail (str) – Descrição detalhada do erro

  • violacoes (list[dict[str, Any]] | None) – Lista de violações devolvida pelo PSP, quando houver. É onde o PSP informa o motivo real de um 400. Itens fora do formato de objeto são descartados — um corpo malformado não pode derrubar a construção da própria exceção que o descreve

__init__(type_='', title='', status=None, detail='', violacoes=None)[source]
exception pypix_api.exceptions.PixAcessoNegadoException(type_='', title='', status=None, detail='', violacoes=None)[source]

Bases: PixAPIException

Erro de acesso negado (403).

exception pypix_api.exceptions.PixRecursoNaoEncontradoException(type_='', title='', status=None, detail='', violacoes=None)[source]

Bases: PixAPIException

Erro de recurso não encontrado (404).

exception pypix_api.exceptions.PixErroValidacaoException(type_='', title='', status=None, detail='', violacoes=None)[source]

Bases: PixAPIException

Erro de validação (400).

exception pypix_api.exceptions.PixNaoAutorizadoException(type_='', title='', status=None, detail='', violacoes=None)[source]

Bases: PixAPIException

Erro de autenticação (401).

Token ausente, expirado ou alterado entre o recebimento e o envio; ou credencial recusada pelo endpoint de token.

exception pypix_api.exceptions.PixErroServicoIndisponivelException(type_='', title='', status=None, detail='', violacoes=None)[source]

Bases: PixAPIException

Erro de serviço indisponível (503).

exception pypix_api.exceptions.PixErroServidorException(type_='', title='', status=None, detail='', violacoes=None)[source]

Bases: PixAPIException

Erro interno do PSP (500).

O corpo da resposta é preservado em detail: os PSPs costumam pedi-lo para abrir chamado.

exception pypix_api.exceptions.PixErroDesconhecidoException(type_='', title='', status=None, detail='', violacoes=None)[source]

Bases: PixAPIException

Erro desconhecido da API Pix.

exception pypix_api.exceptions.PixRespostaInvalidaError(type_='', title='', status=None, detail='', violacoes=None)[source]

Bases: PixAPIException

Erro quando a resposta da API não está no formato esperado

exception pypix_api.exceptions.PixErroTransporteException(detail='', title='Erro de transporte')[source]

Bases: PixAPIException

Falha ocorrida antes de haver resposta HTTP.

Não possui status: a requisição não chegou a ser respondida pelo PSP.

__init__(detail='', title='Erro de transporte')[source]
exception pypix_api.exceptions.PixTimeoutException(detail='')[source]

Bases: PixErroTransporteException

A requisição excedeu o tempo limite.

O resultado da operação é desconhecido: o PSP pode tê-la processado e apenas a resposta ter se perdido. Consulte o recurso antes de recriá-lo em operações que geram identificador no PSP (POST /cob, /cobr, /rec, /solicrec, /loc, /locrec).

__init__(detail='')[source]
exception pypix_api.exceptions.PixConexaoException(detail='')[source]

Bases: PixErroTransporteException

Falha de conexão com o PSP (DNS, TLS, rede).

__init__(detail='')[source]
pypix_api.exceptions.EXCECOES_POR_STATUS: dict[int, type[PixAPIException]] = {400: <class 'pypix_api.exceptions.PixErroValidacaoException'>, 401: <class 'pypix_api.exceptions.PixNaoAutorizadoException'>, 403: <class 'pypix_api.exceptions.PixAcessoNegadoException'>, 404: <class 'pypix_api.exceptions.PixRecursoNaoEncontradoException'>, 500: <class 'pypix_api.exceptions.PixErroServidorException'>, 503: <class 'pypix_api.exceptions.PixErroServicoIndisponivelException'>}

Exceção correspondente a cada status HTTP de erro.

pypix_api.exceptions.excecao_para_status(status)[source]

Resolve a exceção de um status HTTP de erro.

Return type:

type[PixAPIException]

pypix_api.http module

Configurações comuns das requisições HTTP da biblioteca.

pypix_api.http.LIMITE_CORPO_CRU = 500

Quantos caracteres do corpo cru são preservados em detail.

pypix_api.http.texto_do_corpo(response, limite=500)[source]

Decodifica o corpo da resposta preservando a acentuação.

response.text só conhece o encoding quando o Content-Type traz charset; sem ele, o requests adivinha e costuma errar em corpos curtos, transformando “inválida” em “inv√°lida” no log. JSON é UTF-8 por definição (RFC 8259), então é o palpite certo quando o PSP não declara.

Return type:

str

pypix_api.http.Timeout = float | tuple[float, float] | tuple[float, None]

um número aplicado a conexão e leitura, ou a tupla (conexão, leitura). None na posição de leitura significa espera sem limite.

Type:

Tipo aceito no parâmetro timeout, igual ao do requests

pypix_api.http.DEFAULT_TIMEOUT: tuple[float, float] = (5.0, 30.0)

(conexão, leitura), em segundos.

O requests não define timeout algum por padrão — sem isto, uma resposta que nunca chega prende o processo indefinidamente, sem log nem métrica.

Type:

Tempo limite padrão

pypix_api.logging module

Sistema de logging estruturado para pypix-api.

Este modulo fornece funcionalidades de logging estruturado com suporte a diferentes formatos de saida, contexto e metricas de performance.

class pypix_api.logging.APICallLogger(logger=None)[source]

Bases: object

Logger especializado para chamadas de API.

__init__(logger=None)[source]

Initialize API call logger.

log_request(method, url, headers=None, body=None, **kwargs)[source]

Log API request with sanitized data.

Return type:

str

log_response(request_id, status_code, response_time, response_body=None, **kwargs)[source]

Log API response.

Return type:

None

class pypix_api.logging.PIXLogger(name='pypix_api')[source]

Bases: object

Logger principal para operacoes PIX.

static __new__(cls, name='pypix_api')[source]

Singleton pattern para loggers.

__init__(name='pypix_api')[source]

Initialize PIX logger.

add_context(**kwargs)[source]

Add context to all subsequent log messages.

Return type:

None

clear_context()[source]

Clear logging context.

Return type:

None

debug(message, **kwargs)[source]

Log debug message.

Return type:

None

info(message, **kwargs)[source]

Log info message.

Return type:

None

warning(message, **kwargs)[source]

Log warning message.

Return type:

None

error(message, **kwargs)[source]

Log error message.

Return type:

None

critical(message, **kwargs)[source]

Log critical message.

Return type:

None

class pypix_api.logging.StructuredFormatter(include_trace=True)[source]

Bases: Formatter

Formatador para logs estruturados em JSON.

__init__(include_trace=True)[source]

Initialize structured formatter.

Parameters:

include_trace (bool) – Include trace information in logs

format(record)[source]

Format log record as JSON.

Return type:

str

pypix_api.logging.log_authentication(client_id, scope, success, **kwargs)[source]

Log authentication attempt.

Return type:

None

pypix_api.logging.log_bank_operation(operation, bank, **kwargs)[source]

Log bank operation with context.

Return type:

None

pypix_api.logging.log_performance(logger=None, threshold=1.0)[source]

Decorator para medir e logar performance de funcoes.

Parameters:

  • logger (PIXLogger | None) – Logger instance to use

  • threshold (float) – Log warning if execution time exceeds threshold (seconds)

pypix_api.logging.log_pix_transaction(txid, operation_type, amount=None, **kwargs)[source]

Log PIX transaction with context.

Return type:

None

pypix_api.logging.setup_logging(level='INFO', log_file=None, structured=False)[source]

Configure global logging for pypix-api.

Parameters:

  • level (str) – Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

  • log_file (str | None) – Optional file path for logging

  • structured (bool) – Use structured JSON logging

Return type:

PIXLogger

Returns:

Configured PIXLogger instance

pypix_api.metrics module

Sistema de metricas e telemetria para pypix-api.

Este modulo coleta e reporta metricas de uso da biblioteca para monitoramento e otimizacao de performance.

class pypix_api.metrics.APICallMetric(method, endpoint, status_code, response_time, timestamp, bank, error=None)[source]

Bases: object

Metrica para chamadas de API.

method: str
endpoint: str
status_code: int
response_time: float
timestamp: datetime
bank: str
error: str | None = None
__init__(method, endpoint, status_code, response_time, timestamp, bank, error=None)
class pypix_api.metrics.MetricEntry(name, value, timestamp, tags=<factory>, unit='count')[source]

Bases: object

Entrada de metrica individual.

name: str
value: float
timestamp: datetime
tags: dict[str, str]
unit: str = 'count'
__init__(name, value, timestamp, tags=<factory>, unit='count')
class pypix_api.metrics.MetricsCollector[source]

Bases: object

Coletor central de metricas.

static __new__(cls)[source]

Singleton pattern for metrics collector.

__init__()[source]

Initialize metrics collector.

metrics: list[MetricEntry]
api_calls: list[APICallMetric]
counters: dict[str, int]
gauges: dict[str, float]
histograms: dict[str, list[float]]
increment(name, value=1, tags=None)[source]

Increment a counter metric.

Return type:

None

gauge(name, value, tags=None)[source]

Set a gauge metric value.

Return type:

None

histogram(name, value, tags=None)[source]

Record a histogram value.

Return type:

None

timing(name, duration, tags=None)[source]

Record timing metric in seconds.

Return type:

None

record_api_call(method, endpoint, status_code, response_time, bank, error=None)[source]

Record API call metrics.

Return type:

None

get_summary()[source]

Get metrics summary.

Return type:

dict[str, Any]

flush_metrics(export_path=None)[source]

Flush metrics to storage/export.

Return type:

bool

clear_metrics()[source]

Clear all collected metrics.

Return type:

None

class pypix_api.metrics.PerformanceTracker(operation_name, tags=None)[source]

Bases: object

Context manager para tracking de performance.

__init__(operation_name, tags=None)[source]

Initialize performance tracker.

__enter__()[source]

Start tracking.

__exit__(exc_type, exc_val, exc_tb)[source]

End tracking and record metrics.

pypix_api.metrics.clear_metrics()[source]

Clear all metrics.

Return type:

None

pypix_api.metrics.export_metrics(file_path=None)[source]

Export metrics to file or console.

Return type:

bool

pypix_api.metrics.get_metrics_summary()[source]

Get current metrics summary.

Return type:

dict[str, Any]

pypix_api.metrics.timed_function(metric_name=None, tags=None)[source]

Decorator to automatically time function execution.

pypix_api.metrics.track_api_call(method, endpoint)[source]

Track API call performance.

Return type:

PerformanceTracker

pypix_api.metrics.track_bank_operation(bank, operation)[source]

Track bank operation performance.

Return type:

PerformanceTracker

pypix_api.observability module

Modulo de observabilidade integrado para pypix-api.

Este modulo combina logging, metricas e tratamento de erros em uma interface unificada para monitoramento completo da biblioteca.

class pypix_api.observability.HealthCheck[source]

Bases: object

Health check utilities for monitoring system status.

__init__()[source]

Initialize health check.

check_system_health()[source]

Perform comprehensive system health check.

Return type:

dict[str, Any]

class pypix_api.observability.ObservabilityConfig[source]

Bases: object

Configuracao centralizada de observabilidade.

__init__()[source]

Initialize observability configuration.

classmethod from_dict(config)[source]

Create configuration from dictionary.

Return type:

ObservabilityConfig

setup_global_observability()[source]

Setup global observability based on configuration.

class pypix_api.observability.ObservabilityMixin(*args, **kwargs)[source]

Bases: object

Mixin para adicionar observabilidade a classes da API.

__init__(*args, **kwargs)[source]

Initialize observability components.

observe_operation(operation, **context)[source]

Context manager for observing operations with full telemetry.

observe_api_call(method, url, **kwargs)[source]

Decorator/context for observing API calls.

pypix_api.observability.configure_observability(config=None)[source]

Configure global observability settings.

pypix_api.observability.create_observability_report()[source]

Create comprehensive observability report.

Return type:

dict[str, Any]

pypix_api.observability.get_observability_status()[source]

Get current observability system status.

Return type:

dict[str, Any]

pypix_api.observability.observable_method(operation_name=None, track_performance=True)[source]

Decorator para tornar metodos observaveis automaticamente.