Banks

Banco do Brasil

class pypix_api.banks.bb.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

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

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

Sicredi

class pypix_api.banks.sicredi.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.

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

Banco Inter

class pypix_api.banks.inter.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

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]

pypix_api.banks.methods.pix_inter_methods

Este módulo implementa a classe PixInterMethods, com os endpoints exclusivos do Banco Inter, fora da especificação padrão do Banco Central:

Consulta e reenvio de callbacks de webhook (/webhook/callbacks)
Simulações do ambiente Sandbox: pagamento de cobranças (imediata, com vencimento, por QR Code e recorrente) e mudança de status de recorrência, solicitação de recorrência e cobrança recorrente

IMPORTANTE: Esta classe deve ser usada APENAS com a implementação InterPixAPI. Os métodos sandbox_* só existem no ambiente Sandbox do Inter e recusam a chamada quando a instância não foi construída com homologacao=True.

Dependências: - Métodos auxiliares _request(), _json() e _json_opcional(), fornecidos

por BankPixAPIBase

Métodos _exige_sandbox() e _exige_producao(), fornecidos por InterPixAPI

Exemplo de uso:

from pypix_api.banks.inter import InterPixAPI

inter = InterPixAPI(oauth=oauth_client, homologacao=True)
inter.criar_cob('txid...', body)
inter.sandbox_pagar_cob('txid...', valor=10.50)
callbacks = inter.consultar_callbacks_webhook(
    data_hora_inicio='2025-01-01T00:00:00Z',
    data_hora_fim='2025-01-31T23:59:59Z',
)

pypix_api.banks.methods.pix_inter_methods.MAX_TXIDS_REENVIO = 50: Limite de txids por chamada de reenvio de callbacks, segundo a especificação.

class pypix_api.banks.methods.pix_inter_methods.PixInterMethods[source]

Classe que implementa os métodos exclusivos do Banco Inter para operações de PIX. Esta classe é herdada APENAS pela InterPixAPI.

consultar_callbacks_webhook(data_hora_inicio, data_hora_fim, pagina=None, tamanho_pagina=None, txid=None)[source]

Consultar callbacks de webhook (endpoint exclusivo Inter).

Retorna as requisições de callback ordenadas pela data de disparo (decrescente). Útil para investigar falhas na entrega de notificações.

Parameters:

data_hora_inicio (str) – Início do período (formato ISO RFC 3339)
data_hora_fim (str) – Fim do período (formato ISO RFC 3339)
pagina (int | None) – Posição da página na lista (padrão do PSP: 0)
tamanho_pagina (int | None) – Itens por página, entre 10 e 50 (padrão do PSP: 20)
txid (str | None) – Filtra os callbacks de um pagamento específico

Return type:

dict[str, Any]

Returns:

dict com a lista paginada de callbacks

reenviar_callbacks_webhook(txids, chave_pix)[source]

Reenviar callbacks de webhook (endpoint exclusivo Inter).

A especificação documenta este endpoint apenas no servidor de produção, por isso a chamada é recusada no Sandbox.

Parameters:

txids (str | list[str]) – Txid, ou lista de até 50 txids, cujos callbacks serão reenviados
chave_pix (str) – Chave Pix usada nas transações — a mesma para todos os txids

Return type:

dict[str, Any]

Returns:

dict com o retorno do PSP (vazio quando a resposta não tem corpo)

Raises:

ValueError – Se a instância apontar para o Sandbox, se não houver txid ou se houver mais de 50

sandbox_pagar_cob(txid, valor)[source]

Pagar uma cobrança imediata (exclusivo do Sandbox Inter).

Parameters:

txid (str) – Identificador da cobrança
valor (float | Decimal) – Valor a pagar

Return type:

dict[str, Any]

Returns:

dict com o retorno do PSP (vazio quando a resposta não tem corpo)

sandbox_pagar_cobv(txid, valor)[source]

Pagar uma cobrança com vencimento (exclusivo do Sandbox Inter).

Parameters:

txid (str) – Identificador da cobrança
valor (float | Decimal) – Valor a pagar

Return type:

dict[str, Any]

Returns:

dict com o retorno do PSP (vazio quando a resposta não tem corpo)

sandbox_pagar_qrcode(qr_code, valor)[source]

Pagar via QR Code (exclusivo do Sandbox Inter).

Paga uma cobrança imediata ou com vencimento a partir do Pix Copia e Cola; num QR Code de recorrência com cobrança vinculada, também autoriza a recorrência.

Parameters:

qr_code (str) – Conteúdo do Pix Copia e Cola
valor (float | Decimal) – Valor a pagar

Return type:

dict[str, Any]

Returns:

dict com o retorno do PSP (vazio quando a resposta não tem corpo)

sandbox_pagar_cobr(txid, valor, cpf_cnpj, chave)[source]

Pagar uma cobrança recorrente (exclusivo do Sandbox Inter).

Parameters:

txid (str) – Identificador da cobrança recorrente
valor (float | Decimal) – Valor a pagar
cpf_cnpj (str) – CPF ou CNPJ do pagador
chave (str) – Chave Pix do recebedor

Return type:

dict[str, Any]

Returns:

dict com o retorno do PSP (vazio quando a resposta não tem corpo)

sandbox_alterar_status_rec(id_rec, status, razao=None)[source]

Alterar o status de uma recorrência (exclusivo do Sandbox Inter).

A aprovação da recorrência é necessária para criar cobranças recorrentes no Sandbox.

Parameters:

id_rec (str) – Identificador da recorrência
status (str) – 'APROVADA' ou 'CANCELADA'
razao (str | None) – Motivo da mudança (ACCL, CPCL, DCSD, ERSL, FRUD, PCFD, SLCR, SLDB ou NRES)

Return type:

dict[str, Any]

Returns:

dict com o retorno do PSP (vazio quando a resposta não tem corpo)

sandbox_alterar_status_solicrec(id_rec, status)[source]

Simular o aceite ou a rejeição de uma solicitação de recorrência pelo pagador (exclusivo do Sandbox Inter).

Parameters:

id_rec (str) – Identificador informado no caminho /sandbox/solicrec/{idRec}/status — a especificação o nomeia idRec
status (str) – 'ACEITA' ou 'REJEITADA'

Return type:

dict[str, Any]

Returns:

dict com o retorno do PSP (vazio quando a resposta não tem corpo)

sandbox_cancelar_cobr(txid, razao)[source]

Cancelar uma cobrança recorrente por estímulo externo (exclusivo do Sandbox Inter).

Parameters:

txid (str) – Identificador da cobrança recorrente
razao (str) – Motivo (UNSPECIFIED, ACCOUNT_CANCELED, ACCOUNT_BLOCKED, RECURRENCE_CANCELED, SETTLEMENT_FAILED, OTHER, REQUESTED_BY_PAYER ou REQUESTED_BY_RECEIVER)

Return type:

dict[str, Any]

Returns:

dict com o retorno do PSP (vazio quando a resposta não tem corpo)

Base Classes

Base Bank API

class pypix_api.banks.base.BankPixAPIBase(oauth, sandbox_mode=False, timeout=None, scopes=None)[source]

Bases: CobVMethods, CobMethods, CobRMethods, LoteCobVMethods, LocMethods, LocRecMethods, PixMethods, RecMethods, SolicRecMethods, WebHookMethods, WebHookRecMethods, WebHookCobrMethods, ABC

Classe base abstrata para clientes Pix de bancos.

BASE_URL

URL base da API do banco (deve ser definido na subclasse)

Type:: str

TOKEN_URL

URL para obtenção de token OAuth2 (deve ser definido na subclasse)

Type:: str

SCOPES

Lista de scopes OAuth2 necessários (deve ser definido na subclasse)

Type:: list

BASE_URL: str | None = None

TOKEN_URL: str | None = None

__init__(oauth, sandbox_mode=False, timeout=None, scopes=None)[source]

Inicializa o cliente Pix do banco.

Parameters:

oauth (OAuth2Client) – Instância configurada de OAuth2Client para autenticação
sandbox_mode (bool) – Se True, usa modo sandbox com token fixo (default: False)
timeout (float | tuple[float, float] | tuple[float, None] | None) – Tempo limite das requisições, no formato aceito pelo requests: um número (aplicado a conexão e leitura) ou a tupla (conexão, leitura). None usa DEFAULT_TIMEOUT. Para leitura sem limite, use (5.0, None)
scopes (str | ScopeGroup | list[str | ScopeGroup] | None) – Escopos OAuth2 a solicitar, como string, ScopeGroup ou lista de ambos. None (padrão) mantém o comportamento histórico: o grupo Pix completo do banco. Informe este parâmetro quando a credencial tiver apenas parte das modalidades contratadas junto ao PSP — ver pypix_api.scopes.compose_scopes()

Raises:

ValueError – Se BASE_URL ou TOKEN_URL não forem definidos na subclasse, ou se scopes for informado e vazio
TypeError – Se scopes não for str, ScopeGroup nem lista desses tipos

sandbox_mode: bool

oauth: OAuth2Client

session: Session

client_id: str | None

timeout: float | tuple[float, float] | tuple[float, None]

scopes: str | None

get_bank_code()[source]

Return type:: str

Bank Exceptions

Reexporta a hierarquia de exceções, definida em pypix_api.exceptions.

As classes moraram aqui até a 0.10.0 e continuam importáveis deste módulo; a definição foi movida para fora de banks/ porque o auth/ também a usa.

exception pypix_api.banks.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.banks.exceptions.PixAcessoNegadoException(type_='', title='', status=None, detail='', violacoes=None)[source]

Bases: PixAPIException

Erro de acesso negado (403).

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

Bases: PixErroTransporteException

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

__init__(detail='')[source]

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

Bases: PixAPIException

Erro desconhecido da API Pix.

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

Bases: PixAPIException

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

exception pypix_api.banks.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.banks.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.banks.exceptions.PixErroValidacaoException(type_='', title='', status=None, detail='', violacoes=None)[source]

Bases: PixAPIException

Erro de validação (400).

exception pypix_api.banks.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.banks.exceptions.PixRecursoNaoEncontradoException(type_='', title='', status=None, detail='', violacoes=None)[source]

Bases: PixAPIException

Erro de recurso não encontrado (404).

exception pypix_api.banks.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.banks.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]

pypix_api.banks.exceptions.excecao_para_status(status)[source]

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

Return type:: type[PixAPIException]

PIX Methods Mixins

COB Methods

pypix_api.banks.cob_methods

Este módulo implementa a classe CobMethods, que fornece métodos para operações de cobrança imediata (COB) do PIX, conforme especificação do Banco Central do Brasil.

A classe CobMethods é utilizada como base para integração com APIs bancárias que suportam o PIX, permitindo criar, revisar, consultar e listar cobranças imediatas. Os métodos abstraem detalhes de requisições HTTP, tratamento de erros e montagem de parâmetros, facilitando a integração de sistemas Python com provedores bancários.

Principais funcionalidades: - Criação de cobrança imediata (com txid definido ou automático) - Revisão de cobrança existente - Consulta de cobrança por txid - Consulta de múltiplas cobranças por período e filtros

Esta classe é herdada por implementações específicas de bancos (ex: Banco do Brasil, Sicoob).

Dependências: - session HTTP compatível (ex: requests.Session) - Método auxiliar: _request(), fornecido por BankPixAPIBase

Exemplo de uso:

class MeuBanco(CobMethods):: …

banco = MeuBanco() resposta = banco.criar_cob(txid=”meu-txid”, body={…})

class pypix_api.banks.methods.cob_methods.CobMethods[source]

Bases: object

Classe que implementa os métodos para operações de cobrança imediata (COB) do PIX. Esta classe é herdada pela BankPixAPIBase.

criar_cob(txid, body)[source]

Criar cobrança imediata com txid específico.

Endpoint para criar uma cobrança imediata com um txid definido.

Parameters:

txid (str) – Identificador da transação
body (dict[str, Any]) – Dados da cobrança imediata

Return type:

dict[str, Any]

Returns:

dict contendo os dados da cobrança criada

Raises:

HTTPError – Para erros 400, 403, 404, 503

criar_cob_auto_txid(body)[source]

Criar cobrança imediata com txid automático.

Endpoint para criar uma cobrança imediata onde o txid é definido pelo PSP.

Parameters:: body (dict[str, Any]) – Dados da cobrança imediata
Return type:: dict[str, Any]
Returns:: dict contendo os dados da cobrança criada
Raises:: HTTPError – Para erros 400, 403, 503

revisar_cob(txid, body)[source]

Revisar cobrança imediata.

Endpoint para revisar uma cobrança imediata existente. A revisão deve ser incrementada em 1.

Parameters:

txid (str) – Identificador da transação
body (dict[str, Any]) – Dados da cobrança revisada

Return type:

dict[str, Any]

Returns:

dict contendo os dados da cobrança revisada

Raises:

HTTPError – Para erros 400, 403, 404, 503

consultar_cob(txid, revisao=None)[source]

Consultar cobrança imediata.

Endpoint para consultar uma cobrança através de um determinado txid.

Parameters:

txid (str) – Identificador da transação
revisao (int | None) – Número da revisão (opcional)

Return type:

dict[str, Any]

Returns:

dict contendo os dados da cobrança

Raises:

HTTPError – Para erros 403, 404, 503

consultar_cobs(inicio, fim, cpf=None, cnpj=None, location_presente=None, status=None, pagina_atual=None, itens_por_pagina=None)[source]

Consultar lista de cobranças imediatas.

Endpoint para consultar cobranças imediatas através de parâmetros como início, fim, cpf, cnpj e status.

Parameters:

inicio (str) – Data de início da consulta (formato ISO)
fim (str) – Data de fim da consulta (formato ISO)
cpf (str | None) – CPF do devedor (11 dígitos). Não pode ser usado com CNPJ
cnpj (str | None) – CNPJ do devedor (14 dígitos). Não pode ser usado com CPF
location_presente (bool | None) – Filtro por presença de location
status (str | None) – Status da cobrança para filtro
pagina_atual (int | None) – Página atual para paginação
itens_por_pagina (int | None) – Quantidade de itens por página

Return type:

dict[str, Any]

Returns:

dict contendo a lista de cobranças

Raises:

HTTPError – Para erros 403, 503
ValueError – Se CPF e CNPJ forem informados simultaneamente

COB with Due Date Methods

Módulo cobv_methods.py

Este módulo define a classe CobVMethods, que implementa métodos para: integração com cobranças Pix com vencimento (CobV) via API bancária.
Inclui operações para criar, revisar, consultar e listar cobranças com vencimento,: utilizando autenticação OAuth2 e requisições HTTP.

Principais funcionalidades: - Criação de cobrança com vencimento (CobV) - Revisão de cobrança com vencimento - Consulta de cobrança por txid - Listagem de cobranças por período e filtros

Dependências: - OAuth2 para autenticação (self.oauth) - Cliente HTTP de sessão (self.session) - Python 3.10+ (tipos nativos)

Autor: [Fabio Thomaz(fabio@ladder.dev.br)]

class pypix_api.banks.methods.cobv_methods.CobVMethods[source]

Bases: object

Métodos para lidar com cobrança Pix com vencimento (CobV).

criar_cobv(txid, body)[source]

Cria uma cobrança com vencimento (CobV).

Return type:: dict[str, Any]

revisar_cobv(txid, body)[source]

Revisa uma cobrança com vencimento (CobV).

Return type:: dict[str, Any]

consultar_cobv(txid, revisao=None)[source]

Consulta uma cobrança com vencimento (CobV) por txid.

Return type:: dict[str, Any]

listar_cobv(inicio, fim, cpf=None, cnpj=None, location_presente=None, status=None, lote_cob_v_id=None, pagina_atual=None, itens_por_pagina=None)[source]

Consulta lista de cobranças com vencimento (CobV).

Return type:: dict[str, Any]

PIX Methods

pypix_api.banks.pix_methods

Este módulo implementa a classe PixMethods, que fornece métodos para operações de PIX, conforme especificação do Banco Central do Brasil.

A classe PixMethods é utilizada como base para integração com APIs bancárias que suportam o PIX, permitindo consultar PIX recebidos e outras operações relacionadas. Os métodos abstraem detalhes de requisições HTTP, tratamento de erros e montagem de parâmetros, facilitando a integração de sistemas Python com provedores bancários.

Principais funcionalidades: - Consulta de PIX recebidos por período e filtros - Consulta de PIX individual por e2eid - Solicitação de devolução de PIX - Consulta de devolução de PIX

Esta classe é herdada por implementações específicas de bancos (ex: Banco do Brasil, Sicoob).

Dependências: - session HTTP compatível (ex: requests.Session) - Método auxiliar: _request(), fornecido por BankPixAPIBase

Exemplo de uso:

class MeuBanco(PixMethods):: …

banco = MeuBanco() resposta = banco.consultar_pix(inicio=”2023-01-01T00:00:00Z”, fim=”2023-01-31T23:59:59Z”) pix_individual = banco.consultar_pix_por_e2eid(“E12345678202301011200abcdef123456”) devolucao = banco.solicitar_devolucao_pix(“E12345678202301011200abcdef123456”, “devolucao123”, {“valor”: “100.00”}) consulta_devolucao = banco.consultar_devolucao_pix(“E12345678202301011200abcdef123456”, “devolucao123”)

class pypix_api.banks.methods.pix_methods.PixMethods[source]

Bases: object

Classe que implementa os métodos para operações de PIX. Esta classe é herdada pela BankPixAPIBase.

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.

consultar_pix(inicio, fim, txid=None, txid_presente=None, devolucao_presente=None, cpf=None, cnpj=None, pagina_atual=None, itens_por_pagina=None)[source]

Consultar PIX recebidos.

Endpoint para consultar PIX recebidos através de parâmetros como início, fim, txid, cpf, cnpj e outros filtros.

Parameters:

inicio (str) – Data de início da consulta (formato ISO)
fim (str) – Data de fim da consulta (formato ISO)
txid (str | None) – Identificador da transação (opcional)
txid_presente (bool | None) – Filtro por presença de txid (opcional)
devolucao_presente (bool | None) – Filtro por presença de devolução (opcional)
cpf (str | None) – CPF do devedor (11 dígitos). Não pode ser usado com CNPJ
cnpj (str | None) – CNPJ do devedor (14 dígitos). Não pode ser usado com CPF
pagina_atual (int | None) – Página atual para paginação (padrão: 0)
itens_por_pagina (int | None) – Quantidade de itens por página (padrão: 100)

Return type:

dict[str, Any]

Returns:

dict contendo a lista de PIX recebidos

Raises:

HTTPError – Para erros 403, 503
ValueError – Se CPF e CNPJ forem informados simultaneamente

consultar_pix_por_e2eid(e2eid)[source]

Consultar PIX individual.

Endpoint para consultar um PIX através de um e2eid específico.

Parameters:: e2eid (str) – Identificador end-to-end da transação PIX
Return type:: dict[str, Any]
Returns:: dict contendo os dados do PIX
Raises:: HTTPError – Para erros 403, 404, 503

solicitar_devolucao_pix(e2eid, id_devolucao, body)[source]

Solicitar devolução de PIX.

Endpoint para solicitar uma devolução através de um e2eid do PIX e do ID da devolução. O motivo que será atribuído à PACS.004 será “MD06” ou “SL02” de acordo com a natureza da devolução.

Parameters:

e2eid (str) – Identificador end-to-end da transação PIX
id_devolucao (str) – Identificador único da devolução
body (dict[str, Any]) – Dados para pedido de devolução contendo: - valor (str): Valor solicitado para devolução (formato: d{1,10}.d{2}) - natureza (str, opcional): Natureza da devolução (“ORIGINAL” ou “RETIRADA”) - descricao (str, opcional): Mensagem ao pagador (máx. 140 caracteres)

Return type:

dict[str, Any]

Returns:

dict contendo os dados da devolução solicitada

Raises:

HTTPError – Para erros 400, 403, 404, 503

Note

Naturezas da devolução: - ORIGINAL: devolução de PIX comum ou valor da compra em PIX Troco (MD06) - RETIRADA: devolução de PIX Saque ou valor do troco em PIX Troco (SL02)

A soma dos valores de todas as devoluções não pode ultrapassar o valor total do PIX.

consultar_devolucao_pix(e2eid, id_devolucao)[source]

Consultar devolução de PIX.

Endpoint para consultar uma devolução através de um End To End ID do PIX e do ID da devolução.

Parameters:

e2eid (str) – Identificador end-to-end da transação PIX
id_devolucao (str) – Identificador único da devolução

Return type:

dict[str, Any]

Returns:

dict contendo os dados da devolução

Raises:

HTTPError – Para erros 403, 404, 503

Webhook Methods

pypix_api.banks.webhook_methods

Este módulo implementa a classe WebHookMethods, que fornece métodos para operações de webhook do PIX, conforme especificação do Banco Central do Brasil.

A classe WebHookMethods é utilizada como base para integração com APIs bancárias que suportam o PIX, permitindo configurar webhooks para notificações de recebimento. Os métodos abstraem detalhes de requisições HTTP, tratamento de erros e montagem de parâmetros, facilitando a integração de sistemas Python com provedores bancários.

Principais funcionalidades: - Configuração de webhook para notificações de Pix recebidos

Esta classe é herdada por implementações específicas de bancos (ex: Banco do Brasil, Sicoob).

Dependências: - session HTTP compatível (ex: requests.Session) - Método auxiliar: _request(), fornecido por BankPixAPIBase

Exemplo de uso:

class MeuBanco(WebHookMethods):: …

banco = MeuBanco() resposta = banco.configurar_webhook(chave=”minha-chave”, webhook_url=”https://example.com/webhook/”)

class pypix_api.banks.methods.webhook_methods.WebHookMethods[source]

Bases: object

Classe que implementa os métodos para operações de webhook do PIX. Esta classe é herdada pela BankPixAPIBase.

configurar_webhook(chave, webhook_url)[source]

Configurar o Webhook Pix.

Endpoint para configuração do serviço de notificações acerca de Pix recebidos. Somente Pix associados a um txid serão notificados.

Parameters:

chave (str) – Chave Pix para configuração do webhook
webhook_url (str) – URL do webhook para notificações (ex: “https://pix.example.com/api/webhook/”)

Return type:

dict[str, Any]

Returns:

dict contendo os dados da configuração do webhook

Raises:

HTTPError – Para erros 400, 403, 404, 503

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

Consultar webhooks cadastrados.

Endpoint para consultar Webhooks Pix configurados no período especificado.

Parameters:

inicio (str) – Data de início da consulta (formato ISO)
fim (str) – Data de fim da consulta (formato ISO)
pagina_atual (int) – Página atual para paginação (default: 0)
itens_por_pagina (int) – Quantidade de itens por página (default: 100)

Return type:

dict[str, Any]

Returns:

dict contendo a lista paginada de webhooks

Raises:

HTTPError – Para erros 403, 503

excluir_webhook(chave)[source]

Cancelar o Webhook Pix.

Endpoint para cancelamento do webhook. Não é a única forma pela qual um webhook pode ser removido. O PSP recebedor pode remover unilateralmente um webhook associado a uma chave que não pertence mais a este usuário recebedor.

Parameters:: chave (str) – Chave Pix para cancelamento do webhook
Returns:: True se o webhook foi excluído com sucesso (status 204), False caso contrário
Return type:: bool
Raises:: HTTPError – Para erros 403, 404, 503

consultar_webhook(chave)[source]

Consultar informações do Webhook Pix.

Endpoint para recuperação de informações sobre o Webhook Pix configurado.

Parameters:: chave (str) – Chave Pix para consulta do webhook
Return type:: dict[str, Any]
Returns:: dict contendo as informações do webhook configurado
Raises:: HTTPError – Para erros 403, 404, 503

Recurring Methods

Módulo para métodos de recorrência da API Pix.

Este módulo implementa os métodos relacionados ao gerenciamento de recorrências conforme especificado na API OpenAPI. Inclui operações para: - Criar recorrências - Consultar recorrência específica - Revisar recorrências existentes - Cancelar recorrências - Listar recorrências com filtros

Classes:: RecMethods: Classe base com métodos para operações de recorrência

class pypix_api.banks.methods.rec_methods.RecMethods[source]

Bases: object

Classe que implementa métodos para operações de recorrência da API Pix.

Esta classe fornece métodos para gerenciar recorrências, incluindo criação, consulta, revisão e listagem de recorrências com diversos filtros disponíveis.

criar_recorrencia(body)[source]

Criar uma nova recorrência.

Endpoint para criar uma recorrência via POST /rec. O idRec deve ser informado no corpo da requisição.

Parameters:: body (dict[str, Any]) – Dados da recorrência contendo obrigatoriamente o idRec
Return type:: dict[str, Any]
Returns:: dict contendo os dados da recorrência criada
Raises:: HTTPError – Para erros 400, 403, 503

revisar_recorrencia(id_rec, body)[source]

Revisar uma recorrência existente.

Endpoint PATCH /rec/{idRec}. O schema RecRevisada aceita, além do status, os campos vinculo.devedor.nome, loc, calendario.dataInicial e ativacao.dadosJornada.txid.

O único status aceito é CANCELADA:

api.revisar_recorrencia(id_rec, {'status': StatusRec.CANCELADA.value})

Para cancelar, prefira cancelar_recorrencia(), que monta o corpo. Cancelar a recorrência encerra o vínculo por completo, incluindo as cobranças futuras. Para cancelar apenas uma cobrança do ciclo, use cancelar_cobr().

O PSP recusa a revisão (HTTP 400) se a recorrência já estiver expirada, cancelada ou rejeitada. Os campos loc e calendario.dataInicial só podem ser alterados enquanto o status for CRIADA.

Parameters:

id_rec (str) – Identificador da recorrência
body (dict[str, Any]) – Dados para revisão da recorrência

Return type:

dict[str, Any]

Returns:

dict contendo os dados da recorrência revisada

Raises:

HTTPError – Para erros 400, 403, 404, 503

cancelar_recorrencia(id_rec)[source]

Cancelar uma recorrência por completo.

Atalho para revisar_recorrencia() com {'status': 'CANCELADA'}.

Encerra o vínculo de recorrência e, com ele, as cobranças dos ciclos seguintes. Para cancelar apenas uma cobrança específica mantendo a recorrência ativa, use cancelar_cobr().

Parameters:: id_rec (str) – Identificador da recorrência
Return type:: dict[str, Any]
Returns:: dict contendo os dados da recorrência cancelada
Raises:: HTTPError – Para erros 400, 403, 404, 503. O PSP retorna 400 quando a recorrência já se encontra expirada, cancelada ou rejeitada.

consultar_recorrencia(id_rec, txid=None)[source]

Consultar uma recorrência específica.

Return type:: dict[str, Any]

listar_recorrencias(inicio, fim, cpf=None, cnpj=None, location_presente=None, status=None, convenio=None, pagina_atual=None, itens_por_pagina=None)[source]

Consultar lista de recorrências com filtros.

Return type:: dict[str, Any]

COBR (Pix Automático) Methods

pypix_api.banks.cobr_methods

Este módulo fornece métodos para operações com cobranças recorrentes (CobR) via API Pix.

Funcionalidades principais: - Criação de cobranças recorrentes com txid específico ou gerado pelo PSP. - Revisão de cobranças recorrentes existentes. - Cancelamento de uma cobrança recorrente específica, sem afetar a recorrência. - Consulta de cobranças recorrentes por txid. - Listagem de cobranças recorrentes com filtros por período, status, CPF/CNPJ, entre outros. - Solicitação de retentativa de cobrança em data específica.

As operações utilizam autenticação e comunicação HTTP com o PSP, sendo necessário fornecer os parâmetros exigidos por cada método.

Classes:: CobRMethods: Implementa os métodos para manipulação de cobranças recorrentes.
Exemplo de uso:: cobr_methods = CobRMethods() cobr_methods.criar_cobr({…})

class pypix_api.banks.methods.cobr_methods.CobRMethods[source]

Bases: object

Métodos para operações com cobranças recorrentes (CobR).

criar_cobr_com_txid(txid, body)[source]

Criar cobrança recorrente com txid específico.

Parameters:

txid (str) – Identificador da transação
body (dict[str, Any]) – Dados da cobrança recorrente

Return type:

dict[str, Any]

Returns:

dict contendo os dados da cobrança criada

Raises:

HTTPError – Para erros 400, 403, 404, 503

revisar_cobr(txid, body)[source]

Revisar cobrança recorrente.

A revisão de uma CobR só admite a alteração do status, e o único valor aceito é CANCELADA (schema CobRStatusRevisada). O corpo é plano, com um único campo:

api.revisar_cobr(txid, {'status': StatusCobR.CANCELADA.value})

Para cancelar, prefira cancelar_cobr(), que monta o corpo.

Cancelar uma CobR encerra apenas aquela cobrança do ciclo — a recorrência (rec) permanece ativa e as cobranças dos ciclos seguintes continuam sendo geradas. Para encerrar a recorrência inteira, use cancelar_recorrencia().

O PSP recusa o cancelamento (HTTP 400) quando a data corrente é igual ou posterior à data prevista da primeira tentativa de liquidação.

Parameters:

txid (str) – Identificador da transação
body (dict[str, Any]) – Dados para revisão da cobrança

Return type:

dict[str, Any]

Returns:

dict contendo os dados da cobrança revisada

Raises:

HTTPError – Para erros 400, 403, 404, 503

cancelar_cobr(txid)[source]

Cancelar uma cobrança recorrente específica.

Atalho para revisar_cobr() com {'status': 'CANCELADA'}.

Cancela apenas a cobrança identificada por txid. A recorrência (rec) associada permanece ativa — para encerrá-la, use cancelar_recorrencia().

Parameters:: txid (str) – Identificador da transação
Return type:: dict[str, Any]
Returns:: dict contendo os dados da cobrança cancelada
Raises:: HTTPError – Para erros 400, 403, 404, 503. O PSP retorna 400 quando a data corrente é igual ou posterior à data prevista da primeira tentativa de liquidação.

consultar_cobr(txid)[source]

Consultar cobrança recorrente através de um determinado txid.

Parameters:: txid (str) – Identificador da transação
Return type:: dict[str, Any]
Returns:: dict contendo os dados da cobrança
Raises:: HTTPError – Para erros 400, 403, 404, 503

criar_cobr(body)[source]

Criar cobrança recorrente, onde o txid é definido pelo PSP.

Parameters:: body (dict[str, Any]) – Dados da cobrança recorrente
Return type:: dict[str, Any]
Returns:: dict contendo os dados da cobrança criada
Raises:: HTTPError – Para erros 400, 403, 404, 503

consultar_lista_cobr(inicio, fim, id_rec=None, cpf=None, cnpj=None, status=None, convenio=None, pagina_atual=None, itens_por_pagina=None)[source]

Consultar lista de cobranças recorrentes através de parâmetros.

Parameters:

inicio (str) – Data e hora de início da consulta (formato ISO 8601)
fim (str) – Data e hora de fim da consulta (formato ISO 8601)
id_rec (str | None) – Identificador da recorrência (opcional)
cpf (str | None) – CPF do usuário recebedor (opcional)
cnpj (str | None) – CNPJ do usuário recebedor (opcional)
status (str | None) – Status da cobrança (opcional)
convenio (str | None) – Convênio usado na cobrança (opcional)
pagina_atual (int | None) – Página atual para paginação (opcional)
itens_por_pagina (int | None) – Quantidade de itens por página (opcional)

Return type:

dict[str, Any]

Returns:

dict contendo a lista de cobranças recorrentes

Raises:

ValueError – Se CPF e CNPJ forem fornecidos simultaneamente
HTTPError – Para erros 400, 403, 404, 503

solicitar_retentativa_cobr(txid, data)[source]

Solicitar retentativa de uma cobrança recorrente.

Parameters:

txid (str) – Identificador da transação
data (date) – Data para a retentativa (formato date)

Return type:

dict[str, Any]

Returns:

dict contendo o resultado da solicitação

Raises:

HTTPError – Para erros 400, 403, 404, 503

Batch CobV (Lote) Methods

pypix_api.banks.lotecobv_methods

Este módulo implementa a classe LoteCobVMethods, que fornece métodos para operações de lotes de cobrança com vencimento (LoteCobV) do PIX, conforme especificação do Banco Central do Brasil.

A classe LoteCobVMethods é utilizada como base para integração com APIs bancárias que suportam o PIX, permitindo criar, alterar, consultar e listar lotes de cobranças com vencimento. Os métodos abstraem detalhes de requisições HTTP, tratamento de erros e montagem de parâmetros, facilitando a integração de sistemas Python com provedores bancários.

Principais funcionalidades: - Criação de lote de cobrança com vencimento - Alteração de lote de cobrança com vencimento - Consulta de lote por ID - Consulta de múltiplos lotes por período e filtros

Esta classe é herdada por implementações específicas de bancos (ex: Banco do Brasil, Sicoob).

Dependências: - session HTTP compatível (ex: requests.Session) - Método auxiliar: _request(), fornecido por BankPixAPIBase

Exemplo de uso:

class MeuBanco(LoteCobVMethods):: …

banco = MeuBanco() lote = banco.criar_lote_cobv(“lote123”, {…}) consulta = banco.consultar_lote_cobv(“lote123”)

class pypix_api.banks.methods.lotecobv_methods.LoteCobVMethods[source]

Bases: object

Classe que implementa os métodos para operações de lote de cobrança com vencimento (LoteCobV) do PIX. Esta classe é herdada pela BankPixAPIBase.

criar_lote_cobv(id_lote, body)[source]

Criar lote de cobranças com vencimento.

Endpoint para criar um lote de cobranças com vencimento com um ID específico.

Parameters:

id_lote (str) – Identificador do lote de cobranças com vencimento
body (dict[str, Any]) – Dados do lote contendo: - descricao (str): Descrição do lote de cobranças - cobsv (list): Array de cobranças com vencimento

Return type:

dict[str, Any]

Returns:

dict contendo os dados do lote criado com status HTTP 202 (Accepted)

Raises:

HTTPError – Para erros 400, 403, 404, 503

Note

Este endpoint retorna status 202 (Accepted) pois a criação do lote é processada de forma assíncrona.

alterar_lote_cobv(id_lote, body)[source]

Alterar lote de cobranças com vencimento.

Endpoint para alterar um lote de cobranças com vencimento existente. O array a ser atribuído na requisição deve ser composto pelas exatas requisições de criação de cobranças que constaram no array atribuído na requisição originária.

Parameters:

id_lote (str) – Identificador do lote de cobranças com vencimento
body (dict[str, Any]) – Dados do lote revisado contendo: - descricao (str): Descrição do lote de cobranças - cobsv (list): Array de cobranças com vencimento

Return type:

dict[str, Any]

Returns:

dict contendo os dados do lote alterado com status HTTP 202 (Accepted)

Raises:

HTTPError – Para erros 400, 403, 404, 503

Note

Uma vez criado um lote, não se pode remover ou adicionar cobranças a este lote. Apenas alterações nas cobranças existentes são permitidas.

consultar_lote_cobv(id_lote)[source]

Consultar lote de cobranças com vencimento.

Endpoint para consultar um lote de cobranças com vencimento através de um ID específico.

Parameters:: id_lote (str) – Identificador do lote de cobranças com vencimento
Return type:: dict[str, Any]
Returns:: dict contendo os dados do lote de cobranças com vencimento
Raises:: HTTPError – Para erros 403, 404, 503

Note

Para cada elemento do array cobsv retornado, caso a requisição de criação de cobrança esteja em status “NEGADA”, o atributo problema será preenchido com detalhes do erro.

listar_lotes_cobv(inicio, fim, pagina_atual=None, itens_por_pagina=None)[source]

Consultar lista de lotes de cobranças com vencimento.

Endpoint para consultar lotes de cobranças com vencimento através de parâmetros como início e fim de período.

Parameters:

inicio (str) – Data de início da consulta (formato ISO)
fim (str) – Data de fim da consulta (formato ISO)
pagina_atual (int | None) – Página atual para paginação (padrão: 0)
itens_por_pagina (int | None) – Quantidade de itens por página (padrão: 100)

Return type:

dict[str, Any]

Returns:

dict contendo a lista de lotes de cobranças com vencimento

Raises:

HTTPError – Para erros 403, 503
ValueError – Se a data fim for anterior à data início

Note

Os parâmetros de paginação são opcionais. Se não informados, serão utilizados os valores padrão do PSP.

Location Methods

pypix_api.banks.loc_methods

Este módulo implementa a classe LocMethods, que fornece métodos para operações de gerenciamento de locations (payload) do PIX, conforme especificação do Banco Central do Brasil.

A classe LocMethods é utilizada como base para integração com APIs bancárias que suportam o PIX, permitindo criar, consultar, listar e desvincular locations de QR Codes. Os métodos abstraem detalhes de requisições HTTP, tratamento de erros e montagem de parâmetros.

Principais funcionalidades: - Criação de location de payload - Consulta de location específica por ID - Listagem de locations por período e filtros - Desvinculação de txid de uma location

Esta classe é herdada por implementações específicas de bancos (ex: Banco do Brasil, Sicoob).

Dependências: - session HTTP compatível (ex: requests.Session) - Método auxiliar: _request(), fornecido por BankPixAPIBase

Exemplo de uso:

class MeuBanco(LocMethods):: …

banco = MeuBanco() location = banco.criar_location(tipo_cob=”cob”) locations = banco.listar_locations(inicio=”2023-01-01T00:00:00Z”, fim=”2023-01-31T23:59:59Z”) loc = banco.consultar_location(id_loc=123) banco.desvincular_txid_location(id_loc=123)

class pypix_api.banks.methods.loc_methods.LocMethods[source]

Bases: object

Classe que implementa os métodos para operações de location (payload) do PIX. Esta classe é herdada pela BankPixAPIBase.

criar_location(tipo_cob)[source]

Criar location do payload.

Endpoint para criar uma location para um QR Code do PIX.

Parameters:

tipo_cob (str) – Tipo da cobrança (“cob” para imediata, “cobv” para com vencimento)

Returns:

id: Identificador da location
location: URL da location
tipoCob: Tipo da cobrança
criacao: Data de criação

Return type:

dict contendo os dados da location criada, incluindo

Raises:

HTTPError – Para erros 400, 403, 503

listar_locations(inicio, fim, txid_presente=None, tipo_cob=None, pagina_atual=None, itens_por_pagina=None)[source]

Consultar locations cadastradas.

Endpoint para consultar locations cadastradas por período e filtros.

Parameters:

inicio (str) – Data de início da consulta (formato ISO RFC 3339)
fim (str) – Data de fim da consulta (formato ISO RFC 3339)
txid_presente (bool | None) – Filtro por presença de txid vinculado (opcional)
tipo_cob (str | None) – Tipo de cobrança (“cob” ou “cobv”) (opcional)
pagina_atual (int | None) – Página atual para paginação (padrão: 0)
itens_por_pagina (int | None) – Quantidade de itens por página (padrão: 100)

Return type:

dict[str, Any]

Returns:

dict contendo a lista de locations e parâmetros de paginação

Raises:

HTTPError – Para erros 403, 404, 503

consultar_location(id_loc)[source]

Recuperar location do payload.

Endpoint para consultar uma location específica pelo seu ID.

Parameters:

id_loc (int) – Identificador da location

Returns:

id: Identificador da location
location: URL da location
tipoCob: Tipo da cobrança
criacao: Data de criação
txid: Identificador da transação (se vinculado)

Return type:

dict contendo os dados da location, incluindo

Raises:

HTTPError – Para erros 403, 404, 503

desvincular_txid_location(id_loc)[source]

Desvincular txid de uma location.

Endpoint para desvincular uma cobrança (txid) de uma location específica. A location continua existindo, mas sem cobrança vinculada.

Parameters:: id_loc (int) – Identificador da location
Return type:: dict[str, Any]
Returns:: dict contendo os dados da location após desvinculação
Raises:: HTTPError – Para erros 403, 404, 503

Recurrence Location Methods

pypix_api.banks.locrec_methods

Este módulo implementa a classe LocRecMethods, que fornece métodos para operações de gerenciamento de locations de recorrência do PIX, conforme especificação do Banco Central.

A classe LocRecMethods é utilizada como base para integração com APIs bancárias que suportam o PIX Automático/Recorrente, permitindo criar, consultar, listar e desvincular locations de recorrência. Os métodos abstraem detalhes de requisições HTTP e tratamento de erros.

Principais funcionalidades: - Criação de location de recorrência - Consulta de location de recorrência específica por ID - Listagem de locations de recorrência por período e filtros - Desvinculação de idRec de uma location de recorrência

Esta classe é herdada por implementações específicas de bancos (ex: Banco do Brasil).

Dependências: - session HTTP compatível (ex: requests.Session) - Método auxiliar: _request(), fornecido por BankPixAPIBase

Exemplo de uso:

class MeuBanco(LocRecMethods):: …

banco = MeuBanco() location = banco.criar_location_rec() locations = banco.listar_locations_rec(inicio=”2023-01-01T00:00:00Z”, fim=”2023-01-31T23:59:59Z”) loc = banco.consultar_location_rec(id_loc=123) banco.desvincular_idrec_location(id_loc=123)

class pypix_api.banks.methods.locrec_methods.LocRecMethods[source]

Bases: object

Classe que implementa os métodos para operações de location de recorrência do PIX. Esta classe é herdada pela BankPixAPIBase.

criar_location_rec()[source]

Criar location de recorrência.

Endpoint para criar uma location para recorrência do PIX Automático.

Returns:

id: Identificador da location
location: URL da location
criacao: Data de criação

Return type:

dict contendo os dados da location criada, incluindo

Raises:

HTTPError – Para erros 400, 403, 503

listar_locations_rec(inicio, fim, id_rec_presente=None, pagina_atual=None, itens_por_pagina=None, convenio=None)[source]

Consultar locations de recorrência cadastradas.

Endpoint para consultar locations de recorrência cadastradas por período e filtros.

Parameters:

inicio (str) – Data de início da consulta (formato ISO RFC 3339)
fim (str) – Data de fim da consulta (formato ISO RFC 3339)
id_rec_presente (bool | None) – Filtro por presença de idRec vinculado (opcional)
pagina_atual (int | None) – Página atual para paginação (padrão: 0)
itens_por_pagina (int | None) – Quantidade de itens por página (padrão: 100)
convenio (str | None) – Filtro pelo convênio associado (opcional)

Return type:

dict[str, Any]

Returns:

dict contendo a lista de locations e parâmetros de paginação

Raises:

HTTPError – Para erros 403, 404, 503

consultar_location_rec(id_loc)[source]

Recuperar location de recorrência.

Endpoint para consultar uma location de recorrência específica pelo seu ID.

Parameters:

id_loc (int) – Identificador da location de recorrência

Returns:

id: Identificador da location
location: URL da location
criacao: Data de criação
idRec: Identificador da recorrência (se vinculado)

Return type:

dict contendo os dados da location, incluindo

Raises:

HTTPError – Para erros 403, 404, 503

desvincular_idrec_location(id_loc)[source]

Desvincular idRec de uma location de recorrência.

Endpoint para desvincular uma recorrência (idRec) de uma location específica. A location continua existindo, mas sem recorrência vinculada.

Parameters:: id_loc (int) – Identificador da location de recorrência
Return type:: dict[str, Any]
Returns:: dict contendo os dados da location após desvinculação
Raises:: HTTPError – Para erros 403, 404, 503

BB-specific PIX Methods

pypix_api.banks.pix_bb_methods

Este módulo implementa a classe PixBBMethods, que fornece métodos exclusivos do Banco do Brasil para operações avançadas de PIX, não disponíveis na especificação padrão do Banco Central.

A classe PixBBMethods é um mixin específico do BB que adiciona funcionalidades extras como: - Consulta de PIX recebidos com filtros avançados (chave, contestação) - Consulta de devoluções com filtros específicos

IMPORTANTE: Esta classe deve ser usada APENAS com a implementação BBPixAPI, pois os endpoints /pix-bb são exclusivos do Banco do Brasil.

Dependências: - session HTTP compatível (ex: requests.Session) - Método auxiliar: _request(), fornecido por BankPixAPIBase

Exemplo de uso:

from pypix_api.banks.bb import BBPixAPI

bb = BBPixAPI(oauth=oauth_client)
pix = bb.consultar_pix_bb(
    inicio="2023-01-01T00:00:00Z",
    fim="2023-01-31T23:59:59Z",
    chave="email@exemplo.com"
)
devolucoes = bb.consultar_devolucoes_bb(
    inicio="2023-01-01T00:00:00Z",
    fim="2023-01-31T23:59:59Z",
    estado_devolucao="DEVOLVIDO"
)

class pypix_api.banks.methods.pix_bb_methods.PixBBMethods[source]

Bases: object

Classe que implementa os métodos exclusivos do Banco do Brasil para operações de PIX. Esta classe é herdada APENAS pela BBPixAPI.

NOTA: Os endpoints /pix-bb são exclusivos do Banco do Brasil e não fazem parte da especificação padrão do Banco Central para a API PIX.

consultar_pix_bb(inicio=None, fim=None, txid=None, txid_presente=None, devolucao_presente=None, contestacao_presente=None, cpf=None, cnpj=None, chave=None, pagina_atual=None, itens_por_pagina=None)[source]

Consultar PIX recebidos (endpoint exclusivo BB).

Endpoint exclusivo do Banco do Brasil para consultar PIX recebidos com filtros avançados não disponíveis no endpoint padrão /pix.

Parameters:

inicio (str | None) – Data de início da consulta (formato ISO RFC 3339)
fim (str | None) – Data de fim da consulta (formato ISO RFC 3339)
txid (str | None) – Identificador da transação (opcional)
txid_presente (bool | None) – Filtro por presença de txid (opcional)
devolucao_presente (bool | None) – Filtro por presença de devolução (opcional)
contestacao_presente (bool | None) – Filtro por presença de contestação (opcional)
cpf (str | None) – CPF do pagador (11 dígitos). Não pode ser usado com CNPJ
cnpj (str | None) – CNPJ do pagador (14 dígitos). Não pode ser usado com CPF
chave (str | None) – Chave DICT do recebedor (telefone, e-mail, cpf/cnpj ou EVP)
pagina_atual (int | None) – Página atual para paginação (padrão: 0)
itens_por_pagina (int | None) – Quantidade de itens por página (padrão: 100)

Return type:

dict[str, Any]

Returns:

dict contendo a lista de PIX recebidos com informações detalhadas

Raises:

HTTPError – Para erros 403, 404, 503
ValueError – Se CPF e CNPJ forem informados simultaneamente

consultar_devolucoes_bb(inicio, fim, estado_devolucao=None, cpf=None, cnpj=None, pagina_atual=None, itens_por_pagina=None)[source]

Consultar devoluções de PIX (endpoint exclusivo BB).

Endpoint exclusivo do Banco do Brasil para consultar devoluções de PIX com filtros avançados. O parâmetro data início/fim considera a data da devolução.

Parameters:

inicio (str) – Data de início da consulta (formato ISO RFC 3339)
fim (str) – Data de fim da consulta (formato ISO RFC 3339)
estado_devolucao (str | None) – Estado da devolução para filtro. Valores possíveis: - EM_PROCESSAMENTO: Devolução em processamento - DEVOLVIDO: Devolução concluída com sucesso - NAO_REALIZADO: Devolução não realizada - DEVOLUCAO_MED: Devolução via MED (Mecanismo Especial de Devolução)
cpf (str | None) – CPF do pagador (11 dígitos). Não pode ser usado com CNPJ
cnpj (str | None) – CNPJ do pagador (14 dígitos). Não pode ser usado com CPF
pagina_atual (int | None) – Página atual para paginação (padrão: 0)
itens_por_pagina (int | None) – Quantidade de itens por página (padrão: 100)

Return type:

dict[str, Any]

Returns:

dict contendo a lista de devoluções com informações detalhadas

Raises:

HTTPError – Para erros 403, 404, 503
ValueError – Se CPF e CNPJ forem informados simultaneamente

Recurrence Solicitation Methods

Módulo de métodos para operações de Solicitação de Confirmação de Recorrência (SolicRec) PIX.

Este módulo define a classe SolicRecMethods, que implementa métodos para criar, consultar e revisar solicitações de confirmação de recorrência via API Pix. Deve ser herdada por classes que implementam a interface de comunicação com bancos que suportam o recurso de SolicRec.

Requisitos:

A classe base deve fornecer o método auxiliar _request().
Atributo session deve ser uma instância de requests.Session ou compatível.

Exemplo de uso:

class MeuBancoPixAPI(SolicRecMethods):: …

api = MeuBancoPixAPI(…) resposta = api.criar_solicrec({…})

class pypix_api.banks.methods.solic_rec_methods.SolicRecMethods[source]

Bases: object

Classe que implementa os métodos para operações de Solicitação de Confirmação de Recorrência PIX. Esta classe deve ser herdada pela classe BankPixAPIBase.

criar_solicrec(body)[source]

Cria uma solicitação de confirmação de recorrência (SolicRec) via API Pix.

Return type:: dict[str, Any]

Parâmetros:

body (dict): Dados da solicitação de confirmação de recorrência conforme especificação Pix.

Retorna:

dict: Dados da solicitação criada retornados pela API.

Exceções:

HTTPError: Em caso de erro na requisição HTTP.

Exemplo:

body = {: “calendario”: {“expiracao”: 3600}, “devedor”: {“cpf”: “12345678909”, “nome”: “Fulano”}, …

} resposta = self.criar_solicrec(body)

consultar_solicrec(id_solic_rec)[source]

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

Return type:: dict[str, Any]

Parâmetros:: id_solic_rec (str): ID da solicitação de confirmação de recorrência.
Retorna:: dict: Dados da solicitação retornados pela API.
Exceções:: HTTPError: Em caso de erro na requisição HTTP.
Exemplo:: dados = self.consultar_solicrec(“123e4567-e89b-12d3-a456-426614174000”)

revisar_solicrec(id_solic_rec, body)[source]

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

Return type:: dict[str, Any]

Parâmetros:: id_solic_rec (str): ID da solicitação de confirmação de recorrência. body (dict): Dados da revisão da solicitação conforme especificação Pix.
Retorna:: dict: Dados da solicitação atualizada retornados pela API.
Exceções:: HTTPError: Em caso de erro na requisição HTTP.
Observação:: O schema SolicRecRevisada aceita apenas o campo status, e o único valor permitido é CANCELADA. REJEITADA é um status de resposta, atribuído pelo PSP do pagador — nunca deve ser enviado. Para cancelar, prefira cancelar_solicrec, que monta o corpo. O cancelamento só é aceito enquanto o status da solicitação for CRIADA, ENVIADA ou RECEBIDA; fora disso o PSP retorna 400.
Exemplo:: body = {“status”: StatusSolicRec.CANCELADA.value} resposta = self.revisar_solicrec(“123e4567-e89b-12d3-a456-426614174000”, body)

cancelar_solicrec(id_solic_rec)[source]

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

Atalho para revisar_solicrec com {“status”: “CANCELADA”}.

Return type:: dict[str, Any]

Parâmetros:

id_solic_rec (str): ID da solicitação de confirmação de recorrência.

Retorna:

dict: Dados da solicitação cancelada retornados pela API.

Exceções:

HTTPError: Em caso de erro na requisição HTTP. O PSP retorna 400: quando o status da solicitação é diferente de CRIADA, ENVIADA ou RECEBIDA.

COBR Webhook Methods

pypix_api.banks.webhook_cobr_methods

Este módulo implementa a classe WebHookCobrMethods, que fornece métodos para operações de webhook de cobrança recorrente do PIX, conforme especificação do Banco Central do Brasil.

A classe WebHookCobrMethods é utilizada como base para integração com APIs bancárias que suportam o PIX, permitindo configurar webhooks para notificações de cobranças recorrentes. Os métodos abstraem detalhes de requisições HTTP, tratamento de erros e montagem de parâmetros, facilitando a integração de sistemas Python com provedores bancários.

Principais funcionalidades: - Configuração de webhook para notificações de cobranças recorrentes - Consulta de webhook configurado - Cancelamento de webhook

Esta classe é herdada por implementações específicas de bancos (ex: Banco do Brasil, Sicoob).

Dependências: - session HTTP compatível (ex: requests.Session) - Método auxiliar: _request(), fornecido por BankPixAPIBase

Exemplo de uso:

class MeuBanco(WebHookCobrMethods):: …

banco = MeuBanco() resposta = banco.configurar_webhook_cobr(webhook_url=”https://example.com/webhook/”)

class pypix_api.banks.methods.webhook_cobr_methods.WebHookCobrMethods[source]

Bases: object

Classe que implementa os métodos para operações de webhook de cobrança recorrente do PIX. Esta classe é herdada pela BankPixAPIBase.

configurar_webhook_cobr(webhook_url)[source]

Configurar o Webhook de Cobrança Recorrente.

Endpoint para configuração do serviço de notificações acerca de cobranças recorrentes. Somente cobranças associadas ao usuário recebedor serão notificadas.

Parameters:: webhook_url (str) – URL do webhook para notificações (ex: “https://example.com/api/webhookcobr/”)
Return type:: dict[str, Any]
Returns:: dict contendo os dados da configuração do webhook
Raises:: HTTPError – Para erros 400, 403, 404, 503

consultar_webhook_cobr()[source]

Consultar informações do Webhook de Cobrança Recorrente.

Endpoint para recuperação de informações sobre o Webhook configurado.

Return type:: dict[str, Any]
Returns:: dict contendo as informações do webhook (incluindo URL e data de criação)
Raises:: HTTPError – Para erros 403, 404, 503

excluir_webhook_cobr()[source]

Cancelar o Webhook de Cobrança Recorrente.

Endpoint para cancelamento do webhook. Não é a única forma pela qual um webhook pode ser removido.

Returns:: True se o webhook foi excluído com sucesso (status 204), False caso contrário
Return type:: bool
Raises:: HTTPError – Para erros 403, 404, 503

Recurrence Webhook Methods

pypix_api.banks.webhook_rec_methods

Este módulo implementa a classe WebHookRecMethods, que fornece métodos para operações de webhook de recorrência do PIX, conforme especificação do Banco Central do Brasil.

A classe WebHookRecMethods é utilizada como base para integração com APIs bancárias que suportam o PIX, permitindo configurar webhooks para notificações de recorrências. Os métodos abstraem detalhes de requisições HTTP, tratamento de erros e montagem de parâmetros, facilitando a integração de sistemas Python com provedores bancários.

Principais funcionalidades: - Configuração de webhook para notificações de recorrências - Consulta de webhook configurado - Cancelamento de webhook

Esta classe é herdada por implementações específicas de bancos (ex: Banco do Brasil, Sicoob).

Dependências: - session HTTP compatível (ex: requests.Session) - Método auxiliar: _request(), fornecido por BankPixAPIBase

Exemplo de uso:

class MeuBanco(WebHookRecMethods):: …

banco = MeuBanco() resposta = banco.configurar_webhook_rec(webhook_url=”https://example.com/webhook/”)

class pypix_api.banks.methods.webhook_rec_methods.WebHookRecMethods[source]

Bases: object

Classe que implementa os métodos para operações de webhook de recorrência do PIX. Esta classe é herdada pela BankPixAPIBase.

configurar_webhook_rec(webhook_url)[source]

Configurar o Webhook de Recorrência.

Endpoint para configuração do serviço de notificações acerca de recorrências. Somente recorrências associadas ao usuário recebedor serão notificadas.

Parameters:: webhook_url (str) – URL do webhook para notificações (ex: “https://example.com/api/webhookrec/”)
Return type:: dict[str, Any]
Returns:: dict contendo os dados da configuração do webhook
Raises:: HTTPError – Para erros 400, 403, 404, 503

consultar_webhook_rec()[source]

Consultar informações do Webhook de Recorrência.

Endpoint para recuperação de informações sobre o Webhook configurado.

Return type:: dict[str, Any]
Returns:: dict contendo as informações do webhook (incluindo URL e data de criação)
Raises:: HTTPError – Para erros 403, 404, 503

excluir_webhook_rec()[source]

Cancelar o Webhook de Recorrência.

Endpoint para cancelamento do webhook. Não é a única forma pela qual um webhook pode ser removido.

Returns:: True se o webhook foi excluído com sucesso (status 204), False caso contrário
Return type:: bool
Raises:: HTTPError – Para erros 403, 404, 503