Metadata-Version: 2.4
Name: delfinance-api-sdk
Version: 0.7.7
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
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="joao@email.com",
        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

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

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

```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="user@example.com")
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="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

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