Delfinance SDK (Python)

SDK oficial da Delfinance para Python, fornecendo uma interface simplificada para integração com os serviços de Cobranças, PIX, Transferências e Webhooks da Delfinance.

Índice

• Estrutura do Repositório
• Requisitos
• Instalação
• Início Rápido
• Funcionalidades
• Exemplos de Uso

Estrutura do Repositório

src/
└── delfinance/                  # Pacote principal do SDK
    ├── abstractions/            # Configurações e definições base
    ├── charges/                 # Serviços de Cobranças e Boletos
    ├── qrcode/                  # Serviços de PIX e QR Code
    ├── transfers/               # Serviços de Transferências (PIX/TED)
    └── webhooks/                # Gerenciamento de Webhooks

Requisitos

• Python 3.7+
• requests
• python-dotenv (opcional, para gerenciamento de variáveis de ambiente)

Instalação

pip install delfinance-python-sdk

Início Rápido

from src.delfinance.abstractions.startup.delfinance_client import DelfinanceClient
from src.delfinance.abstractions.enums.environment import Environment
from src.delfinance.transfers.services.transfers_service import TransfersService

# Configurar o cliente
config = {
    "apiKey": "sua_api_key",
    "accountId": "seu_account_id",
    "environment": Environment.SANDBOX,
    "certificatePath": "path/to/cert.pem",  # Obrigatório apenas para produção
    "privateKeyPath": "path/to/key.pem"    # Obrigatório apenas para produção
}
client = DelfinanceClient(config)

# Acessar serviços
# Ex: Consultar transferência
transfer_service = TransfersService(client)
transfer = transfer_service.get_transfer("transfer_id")
print(transfer.status)

Funcionalidades

Cobranças (Charges)

Funcionalidade	Método	Status	Descrição
Criar Cobrança	create_charge	Ativo	Cria uma nova cobrança (Boleto, Pix, etc.)
Consultar Cobrança	get_charge_by_id	Ativo	Busca uma cobrança pelo seu ID de correlação
Listar Cobranças	list_charges_by_period	Ativo	Lista cobranças dentro de um período específico
Baixar PDF	download_charge_pdf	Ativo	Baixa o PDF de uma cobrança (boleto)
Atualizar Cobrança	update_charge	Ativo	Atualiza uma cobrança existente
Cancelar Cobrança	void_charge	Ativo	Cancela uma cobrança
Validar Pagamento	validate_payment_details	Ativo	Valida detalhes de pagamento (linha digitável)
Pagar Conta	bill_payment	Ativo	Realiza pagamento de contas/boletos

Tipos de Cobrança Suportados:

• BANKSLIP - Boleto bancário tradicional
• BANKSLIP_PIX - Boleto com opção de pagamento via PIX
• PIX_STATIC - Cobrança PIX estática
• PIX_DYNAMIC - Cobrança PIX dinâmica
• PIX_DYNAMIC_DUEDATE - Cobrança PIX dinâmica com vencimento

Recursos:

• Multa e juros configuráveis (fixo ou percentual)
• Descontos e abatimentos
• Dados completos do pagador e endereço
• Geração automática de código de barras e linha digitável
• QR Code PIX integrado (para tipos BANKSLIP_PIX e PIX_*)
• Notificação automática ao pagador

Status de Pagamento:

• PAID - Pago com sucesso
• SCHEDULED - Agendado para data futura
• CHARGEBACKED - Estornado
• PENDING_APPROVAL - Pendente de aprovação
• SCHEDULE_FAILURE - Falha no agendamento

QR Code (Pix)

Estático (Static)

Funcionalidade	Método	Status	Descrição
Criar QR Code Estático	create_static_qr_code	Ativo	Cria um QR Code estático
Consultar QR Code Estático	get_static_qr_code	Ativo	Consulta detalhes de um QR Code estático
Listar Pagamentos	get_static_qr_code_payments	Ativo	Lista pagamentos recebidos de um QR Code estático
Cancelar QR Code Estático	cancel_static_qr_code	Ativo	Cancela um QR Code estático

Imediato (Immediate)

Funcionalidade	Método	Status	Descrição
Criar QR Code Imediato	create_immediate_qr_code	Ativo	Cria um QR Code dinâmico imediato
Consultar QR Code Imediato	get_immediate_qr_code	Ativo	Consulta detalhes de um QR Code imediato
Cancelar QR Code Imediato	cancel_immediate_qr_code	Ativo	Cancela um QR Code dinâmico imediato

Com Vencimento (Due Date)

Funcionalidade	Método	Status	Descrição
Criar QR Code com Vencimento	create_due_date_qr_code	Ativo	Cria um QR Code dinâmico com vencimento
Consultar QR Code com Vencimento	get_due_date_qr_code	Ativo	Consulta detalhes de um QR Code com vencimento
Cancelar QR Code com Vencimento	cancel_due_date_qr_code	Ativo	Cancela um QR Code dinâmico com vencimento

Transferências

Funcionalidade	Método	Status	Descrição
Consultar Transferência	get_transfer	Ativo	Consulta detalhes de uma transferência
Criar Transferência (PIX)	create_transfer	Ativo	Realiza uma transferência PIX
Criar Transferência TED	create_ted_transfer	Ativo	Realiza uma transferência TED

Pix

Funcionalidade	Método	Status	Descrição
Inicializar Pagamento (DICT)	payment_initialization	Ativo	Inicializa um pagamento via chave DICT
Decodificar QR Code	decode_qr_code	Ativo	Decodifica um QR Code para pagamento
Criar Chave Pix	create_pix_key	Ativo	Cria uma nova chave Pix
Consultar Chaves Pix	get_pix_keys	Ativo	Consulta chaves Pix cadastradas
Deletar Chave Pix	delete_pix_key	Ativo	Deleta uma chave Pix
Gerar Código de Autenticação	generate_auth_code	Ativo	Gera código de autenticação para portabilidade

Webhooks

Funcionalidade	Método	Status	Descrição
Criar Webhook	create_webhook	Ativo	Cria uma nova configuração de webhook
Listar Webhooks	get_all_webhooks	Ativo	Lista todos os webhooks configurados
Consultar Webhook	get_webhook_by_id	Ativo	Consulta um webhook pelo ID
Atualizar Webhook	update_webhook	Ativo	Atualiza um webhook existente
Deletar Webhook	delete_webhook	Ativo	Remove um webhook

Tipos de Eventos Suportados:

• CHARGE_PAID - Boleto pago
• PIX_RECEIVED - PIX recebido (novo fluxo)
• PIX_PAYMENT_UPDATED - Atualização de status de pagamento PIX
• PIX_REFUNDED - Reembolso recebido
• PIX_REFUND_PAYMENT_UPDATED - Erro em reembolso
• TRANSFER_INTERNAL_CREDITED - Transferência interna recebida
• TRANSFER_INTERNAL_DEBITED - Transferência interna enviada
• TRANSFER_EXTERNAL_CREDITED - TED recebida
• TRANSFER_EXTERNAL_DEBITED - TED enviada
• INFRACTION_NOTIFICATION_CREATED - Notificação de infração
• WHITELABEL_CUSTOMER_DOCUMENTATION_REJECTED - Documentos rejeitados
• WHITELABEL_CUSTOMER_APPROVED - Cliente aprovado

Esquemas de Autorização:

• NONE - Sem autenticação
• BASIC - Basic Authentication (username:password base64)
• BEARER - Bearer Token (JWT ou API Key)
• HEADER - Header customizado

Exemplos de Uso

Criar Cobrança (Boleto)

from src.delfinance.charges.services.charges_service import ChargesService
from src.delfinance.charges.requests.create_charge_request import CreateChargeRequest

charge_request = CreateChargeRequest(
    correlation_id="correlation_id_exemplo_123",
    amount=15.00,
    your_number="numero_cliente_exemplo",
    due_date="2026-04-12",
    description="Descricao da cobranca",
    payer={
        'name': 'Cliente Exemplo',
        'document': 'documento_exemplo',
        'email': 'email_exemplo@dominio.com',
        'phone': {
            'prefix': '00',
            'number': '999999999'
        },
        'address': {
            'zipCode': '00000000',
            'publicPlace': 'Logradouro Exemplo',
            'number': '123',
            'neighborhood': 'Bairro Exemplo',
            'city': 'Cidade Exemplo',
            'state': 'EX'
        }
    },
)

charge_service = ChargesService(client)
response = charge_service.create_charge(charge_request)
print(f"Cobrança criada: {response.id}")

Consultar Cobrança por ID

from src.delfinance.charges.services.charges_service import ChargesService

charge_service = ChargesService(client)
response = charge_service.get_charge_by_id("correlation_id_exemplo_123")
print(f"Cobrança consultada: {response.correlation_id}")

Listar Cobranças por Período

from src.delfinance.charges.services.charges_service import ChargesService
from src.delfinance.charges.requests.list_charges_by_period_request import ListChargesByPeriodRequest

charge_service = ChargesService(client)
request = ListChargesByPeriodRequest(
    start_date=None,
    end_date=None,
)

response = charge_service.list_charges_by_period(request)
for charge in response:
    print(charge.correlation_id)

Baixar PDF da Cobrança

from src.delfinance.charges.services.charges_service import ChargesService

charge_service = ChargesService(client)
pdf_stream = charge_service.download_charge_pdf("correlation_id_exemplo_123")

with open("charge.pdf", "wb") as file:
    file.write(pdf_stream.getvalue())

Atualizar Cobrança

from src.delfinance.charges.services.charges_service import ChargesService
from src.delfinance.charges.requests.create_charge_request import CreateChargeRequest

charge_service = ChargesService(client)
request = CreateChargeRequest(due_date="2026-04-15")

response = charge_service.update_charge("correlation_id_exemplo_123", request)
print(response)

Observação: o endpoint pode retornar sucesso sem corpo. Nesse caso, o SDK retorna None.

Cancelar Cobrança

from src.delfinance.charges.services.charges_service import ChargesService

charge_service = ChargesService(client)
response = charge_service.void_charge("correlation_id_exemplo_123")
print(response)

Validar Detalhes de Pagamento

from src.delfinance.charges.services.charges_service import ChargesService

charge_service = ChargesService(client)
response = charge_service.validate_payment_details(
    "linha_digitavel_exemplo"
)
print(response.amount)

Pagar Boleto

from src.delfinance.charges.services.charges_service import ChargesService
from src.delfinance.charges.requests.bill_payments_request import BillPaymentsRequest

charge_service = ChargesService(client)
request = BillPaymentsRequest(
    digitable_line="linha_digitavel_exemplo",
    amount=1.00,
)

response = charge_service.bill_payment(
    request,
    idempotency_key="idempotency_key_exemplo"
)
print(response.status)

Criar QR Code Estático

from src.delfinance.qrcode.services.qr_code_service import QrCodeService
from src.delfinance.qrcode.requests.static_qr_code_request import StaticQrCodeRequest

qr_request = StaticQrCodeRequest(
    correlation_id="correlation_id_qrcode_exemplo"
    # pix_key ="sua_chave_pix", opcional
    # amount = 5 opcional
)

qr_code_service = QrCodeService(client)
response = qr_code_service.create_static_qr_code(qr_request)
print(f"Transaction ID: {response.transaction_id}")
print(f"Correlation ID: {response.correlation_id}")

Execução local no sample:

py .\sample.py create_static_qr_code

Criar Transferência PIX

from src.delfinance.transfers.services.pix_service import PixService
from src.delfinance.transfers.services.transfers_service import TransfersService
from src.delfinance.transfers.requests.create_transfer_request import CreateTransferRequest
from src.delfinance.transfers.requests.payment_initialization_request import PaymentInitializationRequest

# 1) Inicializa pagamento por chave para obter end_to_end_id válido
pix_service = PixService(client)
initialization = pix_service.payment_initialization(
    PaymentInitializationRequest(
        key="chave_pix_exemplo"
    )
)

# 2) Usa o end_to_end_id retornado na transferência PIX KEY
transfer_request = CreateTransferRequest(
    amount=100.00,
    end_to_end_id=initialization.end_to_end_id,
    initiation_type="KEY"
)

# Idempotency key é opcional, mas recomendado
transfers_service = TransfersService(client)
response = transfers_service.create_transfer(
    transfer_request, 
    idempotency_key="idempotency_key_exemplo"
)
print(f"Transferência criada: {response.id}")

Consultar Transferência

from src.delfinance.transfers.services.transfers_service import TransfersService

transfers_service = TransfersService(client)
response = transfers_service.get_transfer("transfer_id_exemplo")
print(f"Transferência consultada: {response.transfer.id}")

Criar Transferência TED

from src.delfinance.transfers.dto.beneficiary import Beneficiary, BeneficiaryHolder
from src.delfinance.transfers.requests.create_ted_transfer_request import CreateTedTransferRequest
from src.delfinance.transfers.services.transfers_service import TransfersService

beneficiary = Beneficiary(
    participant_ispb="ispb_exemplo",
    branch="0001",
    number="conta_exemplo",
    holder=BeneficiaryHolder(
        document="documento_exemplo",
        name="Favorecido Exemplo"
    ),
    account_type="CURRENT"
)

request = CreateTedTransferRequest(
    description="Descricao da TED",
    amount=1.00,
    beneficiary=beneficiary
)

transfers_service = TransfersService(client)
response = transfers_service.create_ted_transfer(
    request,
    idempotency_key="idempotency_key_exemplo"
)
print(f"TED criada: {response.id}")

Inicializar Pagamento (Pix)

from src.delfinance.transfers.services.pix_service import PixService
from src.delfinance.transfers.requests.payment_initialization_request import PaymentInitializationRequest

pix_service = PixService(client)
request = PaymentInitializationRequest(key="chave_pix_exemplo")
response = pix_service.payment_initialization(request)
# A resposta contém os dados do recebedor resolvidos
print(f"End-to-End ID: {response.end_to_end_id}")

Decodificar QR Code

from src.delfinance.transfers.services.pix_service import PixService
from src.delfinance.transfers.requests.decode_qr_code_request import DecodeQrCodeRequest

pix_service = PixService(client)
request = DecodeQrCodeRequest(payload="payload_qrcode_exemplo")
response = pix_service.decode_qr_code(request)
# A resposta contém os dados do pagamento resolvidos
print(f"Valor Original: {response.original_value}")

Gerenciar Webhooks

from src.delfinance.webhooks.services.webhook_service import WebhookService
from src.delfinance.webhooks.requests.create_webhook_request import CreateWebhookRequest

# Criar
webhook_request = CreateWebhookRequest(
    url="https://sua-api-exemplo.com/webhook",
    event_type="CHARGE_PAID"
)
webhook_service = WebhookService(client)
webhook = webhook_service.create_webhook(webhook_request)
print(f"Webhook criado: {webhook.id}")

# Listar
webhooks = webhook_service.get_all_webhooks()
for wh in webhooks:
    print(f"{wh.id} - {wh.url}")