delfinance-api-sdk 0.7.6

SDK oficial da Delfinance para Python

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-api-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
from src.delfinance.charges.requests.create_charge_request import Payer, Address, Phone

charge_request = CreateChargeRequest(
    correlation_id="unique_id_123",
    value=150.50,
    due_date="2023-12-31",
    description="Serviço de Consultoria",
    days_after_due_date_to_registration_cancellation=10,
    late_payment_penalty=2.00,
    interest_rate=1.00,
    payer=Payer(
        name="João da Silva",
        document="12345678909",
        email="[e-mail]",
        address=Address(
            street="Rua das Flores",
            number="123",
            complement="Apto 101",
            neighborhood="Centro",
            city_name="São Paulo",
            state="SP",
            zip_code="01001000"
        ),
        phone=Phone(
            area_code="11",
            number="999999999"
        )
    )
)

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

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
from src.delfinance.qrcode.dtos.address_dto import AddressDto

qr_request = StaticQrCodeRequest(
    key="sua_chave_pix",
    amount=50.00,
    description="Venda Loja",
    merchant_name="Minha Loja",
    merchant_city="Sao Paulo",
    transaction_identifier="transacao123"
)

qr_code_service = QrCodeService(client)
response = qr_code_service.create_static_qr_code(qr_request)
print(f"QR Code (EMV): {response.emv_payload}")

Criar Transferência PIX

from src.delfinance.transfers.services.transfers_service import TransfersService
from src.delfinance.transfers.requests.create_transfer_request import CreateTransferRequest

transfer_request = CreateTransferRequest(
    amount=100.00,
    end_to_end_id="E1234567890...",
    description="Pagamento Fornecedor"
)

# Idempotency key é opcional, mas recomendado
transfers_service = TransfersService(client)
response = transfers_service.create_transfer(
    transfer_request, 
    idempotency_key="unique_key_123"
)
print(f"Transferência 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="[e-mail]")
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="00020126580014BR.GOV.BCB.PIX...")
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(
    name="Meu Webhook",
    url="https://minhaapi.com/callback",
    event_types=["PAYMENT_RECEIVED"]
)
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}")