Metadata-Version: 2.4
Name: delfinance-api-sdk
Version: 0.7.10
Summary: SDK oficial da Delfinance para Python
Home-page: https://github.com/delfinance/python-sdk
Author: Delfinance Team
Author-email: dev@delfinance.com
Project-URL: Bug Tracker, https://github.com/delfinance/python-sdk/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dotenv>=0.21.1
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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](#estrutura-do-repositório)
- [Requisitos](#requisitos)
- [Instalação](#instalação)
- [Início Rápido](#início-rápido)
- [Funcionalidades](#funcionalidades)
- [Exemplos de Uso](#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

```bash
pip install delfinance-python-sdk
```
## Início Rápido

```python
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)

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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:

```bash
py .\sample.py create_static_qr_code
```

### Criar Transferência PIX

```python
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

```python
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

```python
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)

```python
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

```python
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

```python
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}")
```
