Banks

Banco do Brasil

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

Bases: PixBBMethods, BankPixAPIBase

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

Parameters:

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

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

BASE_URL

URL da API de produção

SANDBOX_BASE_URL

URL da API de sandbox

TOKEN_URL

URL para obtenção de token OAuth2

SCOPES

Scopes necessários para autenticação

get_bank_code()[source]
Return type:

str

get_base_url()[source]

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

Returns:

URL base da API (produção ou sandbox)

Return type:

str

Note

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

Sicoob

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

Bases: BankPixAPIBase

Implementação da API PIX do Sicoob.

Parameters:

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

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

BASE_URL

URL da API de produção

SANDBOX_BASE_URL

URL da API de sandbox

TOKEN_URL

URL para obtenção de token OAuth2

SCOPES

Scopes necessários para autenticação

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

Base Classes

Base Bank API

class pypix_api.banks.base.BankPixAPIBase(oauth, sandbox_mode=False)[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)[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)

Raises:

ValueError – Se BASE_URL, TOKEN_URL ou SCOPES não forem definidos na subclasse

sandbox_mode: bool
oauth: OAuth2Client
session: Session
client_id: str | None
get_bank_code()[source]
Return type:

str

Bank Exceptions

exception pypix_api.banks.exceptions.PixAPIException(type_, title, status, detail)[source]

Bases: Exception

Exceção base para erros da API Pix.

__init__(type_, title, status, detail)[source]
exception pypix_api.banks.exceptions.PixAcessoNegadoException(type_, title, status, detail)[source]

Bases: PixAPIException

Erro de acesso negado (403).

exception pypix_api.banks.exceptions.PixRecursoNaoEncontradoException(type_, title, status, detail)[source]

Bases: PixAPIException

Erro de recurso não encontrado (404).

exception pypix_api.banks.exceptions.PixErroValidacaoException(type_, title, status, detail)[source]

Bases: PixAPIException

Erro de validação (400).

exception pypix_api.banks.exceptions.PixErroServicoIndisponivelException(type_, title, status, detail)[source]

Bases: PixAPIException

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

exception pypix_api.banks.exceptions.PixErroDesconhecidoException(type_, title, status, detail)[source]

Bases: PixAPIException

Erro desconhecido da API Pix.

exception pypix_api.banks.exceptions.PixRespostaInvalidaError(type_, title, status, detail)[source]

Bases: PixAPIException

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

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étodos auxiliares: _create_headers(), get_base_url()

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)[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étodos auxiliares: _create_headers(), get_base_url()

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.

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étodos auxiliares: _create_headers(), get_base_url()

Exemplo de uso:
class MeuBanco(WebHookMethods):

…

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

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

Return type:

dict[str, Any]

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]