delfinance-api-sdk 0.2.5

Delfinance SDK (C#)

SDK oficial da Delfinance para .NET, fornecendo uma interface simplificada para integração com os serviços PIX, Webhooks e Cobranças da Delfinance.

Índice

• Requisitos
• Instalação
• Início Rápido
• Configuração e Autenticação
• Funcionalidades
• Exemplos de Uso
• Tratamento de Erros
• Suporte e Contribuição

Requisitos

• .NET 6.0+ ou .NET Framework 4.6.1+
• Credenciais de acesso Delfinance (API Key e Account ID)

Instalação

Via NuGet Package Manager

Install-Package DelSdk

Via .NET CLI

dotnet add package DelSdk

Via PackageReference (.csproj)

<PackageReference Include="DelSdk" Version="*" />

Início Rápido

using DelSdk.Abstractions.Configurations;
using DelSdk.Abstractions.Configurations.Enums;
using DelSdk.Abstractions.PixServices.Interfaces;

// Configurar o SDK
var options = new DelSdkConfigurations(
    DelEnvironment.Sandbox,  // ou DelEnvironment.Production
    "sua-api-key",
    "sua-account-id"
);

// Criar o client PIX
var pixClient = SdkClientFactory.CreatePixServicesClient(options);

// Exemplo: Consultar transferência
var transfer = await pixClient.GetTransferAsync("E00000000000000000000000000000000", CancellationToken.None);
Console.WriteLine($"Transferência: {transfer}");

Configuração e Autenticação

Ambientes

Headers de Autenticação

O SDK configura automaticamente os seguintes headers em todas as requisições:

Configuração básica:

using DelSdk.Abstractions.Configurations;
using DelSdk.Abstractions.Configurations.Enums;

var options = new DelSdkConfigurations(
    DelEnvironment.Sandbox,  // ou DelEnvironment.Production
    apiKey: "sua-api-key",
    accountId: "sua-account-id"
);

mTLS (Mutual TLS)

Importante: Em ambiente de produção, mTLS é obrigatório. Em sandbox, é opcional.

using System.Security.Cryptography.X509Certificates;

// Carregar certificado PFX (recomendado para Windows)
var certificate = new X509Certificate2(
    "certificate.pfx", 
    "password",
    X509KeyStorageFlags.Exportable | X509KeyStorageFlags.PersistKeySet
);

// Ou carregar certificado PEM (conversão automática no Windows)
var certificate = X509Certificate2.CreateFromPemFile(
    "certificate.crt", 
    "privatekey.key"
);

// Configurar SDK com mTLS
var options = new DelSdkConfigurations(
    DelEnvironment.Production,
    apiKey: "sua-api-key",
    accountId: "sua-account-id"
)
{
    MtlsClientCertificate = certificate
};

Nota: Para mais detalhes sobre mTLS, incluindo troubleshooting, consulte a documentação completa de mTLS.

Criando Clients

O SDK fornece três clients principais:

using DelSdk.Abstractions.Configurations;

var options = new DelSdkConfigurations(
    DelEnvironment.Sandbox,
    "sua-api-key",
    "sua-account-id"
);

// Client PIX - QR Codes, Transferências, Chaves PIX
var pixClient = SdkClientFactory.CreatePixServicesClient(options);

// Client Webhooks - Notificações de eventos
var webhookClient = SdkClientFactory.CreateWebhookClient(options);

// Client Cobranças - Boletos e Pagamentos
var chargeClient = SdkClientFactory.CreateChargeServicesClient(options);

Funcionalidades

QR Code Estático

QR Code Dinâmico Imediato

Nota: Ideal para cobranças imediatas com controle de expiração (padrão: 24 horas).

QR Code Dinâmico com Vencimento

Nota: Suporta boleto PIX com vencimento, multas, juros, descontos e abatimentos.

Transferências e Pagamentos

Nota: As transferências requerem inicialização prévia via InitializePaymentAsync() ou InitializeQrCodePaymentAsync() para obter o endToEndId.

Gerenciamento de Chaves PIX

Nota: Chaves do tipo EMAIL e PHONE requerem validação via código de autenticação gerado por GenerateAuthCodeAsync().

Webhooks

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

Cobranças (Charges)

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

Pagamentos de Boletos (Bill Payments)

Recursos:

• Pagamento imediato ou agendado
• Suporte a código de barras ou linha digitável
• Idempotência com chave única
• Cálculo automático de multas, juros e descontos
• Comprovante completo com todos os detalhes
• Informações do beneficiário e banco emissor

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

Exemplos de Uso

Criar QR Code Estático

var request = new CreateStaticQrCodeRequest
{
    CorrelationId = Guid.NewGuid().ToString(),
    PixKey = "11999999999",
    Amount = 50.00m,
    BankAccount = "123456",
    BeneficiaryName = "Minha Empresa",
    FormatResponse = QrCodeResponseFormat.PayloadAndQrCode
};

var response = await pixClient.CreateStaticQrCodeAsync(request, CancellationToken.None);
Console.WriteLine($"QR Code criado: {response.TransactionId}");
Console.WriteLine($"Payload: {response.PayloadPix}");

Criar QR Code Dinâmico Imediato

var request = new CreateDynamicImmediateQrCodeRequest
{
    CorrelationId = Guid.NewGuid().ToString(),
    Amount = 100.00m,
    ExpiresIn = "3600", // 1 hora
    FormatResponse = "PAYLOAD_AND_QRCODE"
};

var response = await pixClient.CreateDynamicImmediateQrCodeAsync(request, CancellationToken.None);
Console.WriteLine($"QR Code expira em: {response.ExpiresAt}");

Criar QR Code com Vencimento e Encargos

var request = new CreateDynamicDueDateQrCodeRequest
{
    CorrelationId = Guid.NewGuid().ToString(),
    Amount = 500.00m,
    DueDate = DateTime.Now.AddDays(30),
    MaxDaysOverdue = 60,
    Taxes = new DynamicQrCodeTaxesDto
    {
        FineType = "PERCENTAGE",
        FineAmount = 2.0m,  // 2%
        InterestType = "FIXED_AMOUNT",
        InterestAmount = 1.0m,  // R$ 1,00 por dia
        DiscountType = "FIXED_AMOUNT",
        DiscountAmount = 10.0m  // R$ 10,00 de desconto
    }
};

var response = await pixClient.CreateDynamicDueDateQrCodeAsync(request, CancellationToken.None);
Console.WriteLine($"Vencimento: {response.DueDate}");

Criar Transferência PIX

// Primeiro, inicialize o pagamento para obter o endToEndId
var initRequest = new PaymentInitializationRequest { Key = "11999999999" };
var initResponse = await pixClient.InitializePaymentAsync(initRequest, CancellationToken.None);

// Depois, execute a transferência
var transferRequest = new CreateTransferRequest
{
    Amount = 100.00m,
    EndToEndId = initResponse.EndToEndId,
    Description = "Pagamento de serviços",
    InitiationType = FundTransferPixType.Key,
    Type = FundTransferType.Pix
};

var idempotencyKey = Guid.NewGuid().ToString();
var transferResponse = await pixClient.CreateTransferAsync(
    transferRequest, 
    idempotencyKey, 
    CancellationToken.None
);

Console.WriteLine($"Transferência realizada: {transferResponse.Id}");
Console.WriteLine($"Status: {transferResponse.Status}");
Console.WriteLine($"Valor: R$ {transferResponse.Amount:N2}");

Criar Webhook

using DelSdk.Abstractions.Webhooks.Interfaces;

// Criar o client de webhooks
var webhookClient = SdkClientFactory.CreateWebhookClient(options);

// Criar webhook para receber notificações de PIX
var request = new CreateWebhookRequest
{
    EventType = WebhookEventType.PixPaymentUpdated,
    Url = "https://meusite.com.br/webhook/pix",
    AuthorizationScheme = WebhookAuthorizationScheme.Bearer,
    Authorization = "seu-token-secreto-aqui"
};

var response = await webhookClient.CreateWebhookAsync(request, CancellationToken.None);
Console.WriteLine($"Webhook criado com ID: {response.Id}");
Console.WriteLine($"Evento: {response.EventType}");
Console.WriteLine($"URL: {response.Url}");

Criar Cobrança (Boleto + PIX)

using DelSdk.Abstractions.ChargeServices.Interfaces;

// Criar o client de cobranças
var chargeClient = SdkClientFactory.CreateChargeServicesClient(options);

var request = new CreateChargeRequest
{
    Type = "BANKSLIP_PIX",  // Boleto com PIX
    CorrelationId = Guid.NewGuid().ToString(),
    Amount = 150.00m,
    DueDate = DateTime.Now.AddDays(30),
    Description = "Pagamento de mensalidade",
    YourNumber = "12345",  // Seu número (obrigatório)
    Payer = new ChargePayerDto
    {
        Name = "João Silva",
        Document = "12345678901",
        Email = "joao@example.com",
        Phone = new ChargePhoneDto
        {
            Prefix = "11",
            Number = "999999999"
        },
        Address = new ChargePayerAddressDto
        {
            ZipCode = "01310-100",
            PublicPlace = "Av. Paulista",
            Number = "1000",
            Neighborhood = "Bela Vista",
            City = "São Paulo",
            State = "SP"
        }
    },
    LateFine = new ChargeFeeDto
    {
        Type = "Percentage",
        Amount = 2.0m,  // 2% de multa
        Date = DateTime.Now.AddDays(31)
    },
    LatePayment = new ChargeFeeDto
    {
        Type = "Percentage",
        Amount = 0.033m,  // 0.033% ao dia (1% ao mês)
        Date = DateTime.Now.AddDays(31)
    },
    NotifyPayerOfCreation = true
};

var response = await chargeClient.CreateChargeAsync(request, CancellationToken.None);

Console.WriteLine($"Cobrança criada: {response.Key}");
Console.WriteLine($"Código de barras: {response.BarCode}");
Console.WriteLine($"Linha digitável: {response.DigitableLine}");
Console.WriteLine($"QR Code PIX: {response.QrCode}");

Pagar Boleto

var payRequest = new PayBillRequest
{
    BarCode = "12345678901234567890123456789012345678901234",
    Amount = 150.00m
    // PayAt = DateTime.Now.AddDays(1)  // Para agendar pagamento
};

var idempotencyKey = Guid.NewGuid().ToString();

var proof = await chargeClient.PayBillAsync(
    payRequest,
    idempotencyKey,
    CancellationToken.None
);

Console.WriteLine($"Pagamento ID: {proof.Id}");
Console.WriteLine($"Status: {proof.Status}");
Console.WriteLine($"Valor pago: R$ {proof.PaidAmount:N2}");
Console.WriteLine($"Beneficiário: {proof.Beneficiary.NameOrCompanyName}");

if (proof.Status == "PAID")
{
    Console.WriteLine($"✅ Boleto pago em {proof.PaidAt:dd/MM/yyyy HH:mm:ss}");
}
else if (proof.Status == "SCHEDULED")
{
    Console.WriteLine($"📅 Pagamento agendado para {proof.PayAt:dd/MM/yyyy}");
}

Mais exemplos: Consulte o projeto DelSdk.Samples para exemplos completos de todos os endpoints.

Tratamento de Erros

O SDK lança exceções específicas para cada domínio:

PIX e Transferências

using DelSdk.Abstractions.Errors;

try
{
    var response = await pixClient.CreateStaticQrCodeAsync(request, CancellationToken.None);
}
catch (DelSdkApiException ex)
{
    Console.WriteLine($"Erro da API: {ex.ErrorResponse.Title}");
    Console.WriteLine($"Status HTTP: {ex.StatusCode}");
    Console.WriteLine($"Trace ID: {ex.ErrorResponse.TraceId}");
    
    foreach (var error in ex.ErrorResponse.Errors)
    {
        Console.WriteLine($"  - {error}");
    }
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Erro de rede: {ex.Message}");
}

Cobranças

try
{
    var response = await chargeClient.CreateChargeAsync(request, CancellationToken.None);
}
catch (ChargeApiException ex)
{
    Console.WriteLine($"Erro de Cobrança: {ex.ErrorResponse.Title}");
    Console.WriteLine($"Status: {ex.StatusCode}");
    Console.WriteLine($"Trace ID: {ex.ErrorResponse.TraceId}");
    
    if (ex.ErrorResponse.Errors != null)
    {
        foreach (var (field, messages) in ex.ErrorResponse.Errors)
        {
            Console.WriteLine($"{field}:");
            foreach (var msg in messages)
            {
                Console.WriteLine($"  - {msg}");
            }
        }
    }
}

Documentação Técnica

Para mais detalhes sobre os endpoints e parâmetros, consulte a Documentação da API Delfinance.

Desenvolvido pela equipe Delfinance 🚀