Delfinance SDK - Node.js

SDK oficial para integração com os serviços financeiros da Delfinance, desenvolvido em TypeScript para Node.js 14+.

Índice

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

Requisitos

• Node.js + TypeScript

Instalação

npm i @delbank/delfinance-api-sdk 

⚙️ Configuração (mTLS)

Para o ambiente de Produção, é obrigatório o uso de certificados mTLS. Certifique-se de ter os arquivos .key e .pem/.crt disponíveis.

🛠️ Como usar

🚀 Início Rápido

Aqui está um exemplo básico para começar a usar o SDK:

import { delSdkOptions } from 'delSdk/abstractions/delSdkOptions';
import { delEnvironment } from 'delSdk/abstractions/delEnvironment';
import { sdkClientFactory } from 'delSdk/abstractions/sdkClientFactory';

// Configurar opções do SDK
const options: delSdkOptions = {
  environment: delEnvironment.Sandbox, // ou delEnvironment.Production
  accessToken: 'sua-api-key',
  accountId: 'sua-account-id',
  
  mtlsClientCertificate: "path/to/cert.pem", # Obrigatório apenas para produção ⚠️
  mtlsClientKey: "path/to/key.pem" # Obrigatório apenas para produção ⚠️
};

// Criar cliente dos serviços
const client = sdkClientFactory.createServicesClient(options);

// Exemplo 1: Consultar Transferência PIX
const transferId = 'E00000000000000000000000000000000';
const transferInfo = await client.pixService.getTransfer(transferId);
console.log('Informações da Transferência:', transferInfo);

// Exemplo 2: Inicializar Pagamento PIX
const initRequest = { key: '11999999999' };
const initResponse = await client.pixService.postPaymentInitalization(initRequest);
console.log('EndToEndId:', initResponse.endToEndId);

Funcionalidades

QR Code Estático

| Funcionalidade | Método | Descrição | |---|---|---| | Criar QR Code | postQRCodeStatic() | Cria um QR Code PIX estático com ou sem valor fixo | | Consultar QR Code | getQRCodeStatic() | Busca informações de um QR Code estático por transactionId | | Listar Pagamentos | getQRCodeStaticPayment() | Lista todos os pagamentos recebidos de um QR Code estático | | Cancelar QR Code | patchQRCodeCancel() | Cancela um QR Code estático previamente criado |

QR Code Dinâmico Imediato

| Funcionalidade | Método | Descrição | |---|---|---| | Criar QR Code | postQRCodeDynamicImediate() | Cria um QR Code dinâmico para pagamento imediato com expiração | | Consultar QR Code | getQRCodeDynamicImediate() | Busca informações de um QR Code dinâmico por correlationId |

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

QR Code Dinâmico com Vencimento

| Funcionalidade | Método | Descrição | |---|---|---| | Criar QR Code | postQRCodeDynamicDueDate() | Cria um QR Code dinâmico com data de vencimento e encargos | | Consultar QR Code | getQRCodeDynamicDueDate() | Busca informações de um QR Code com vencimento por transactionId |

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

Transferências e Pagamentos PIX

| Funcionalidade | Método | Descrição | |---|---|---| | Consultar Transferência | getTransfer() | Consulta detalhes de uma transferência PIX ou interna por identificador | | Consultar Transferência TED | getTEDTransfer() | Consulta detalhes de uma transferência TED por identificador | | Inicializar Pagamento (DICT) | postPaymentInitalization() | Inicializa um pagamento via chave PIX (CPF, CNPJ, e-mail, telefone, EVP) | | Inicializar Pagamento (QR Code) | postQRCodePaymentInitalization() | Inicializa um pagamento via payload EMV de QR Code | | Transferência PIX por Chave | postKeyPixTransfer() | Executa transferência PIX no endpoint de transferências usando endToEndId e initiationType: KEY | | Criar Transferência PIX | postInternalTransfer() | Executa uma transferência PIX após inicialização | | Criar Transferência TED | postTEDTransfer() | Executa uma transferência TED para outra instituição financeira |

Nota: As transferências requerem inicialização prévia para obter o endToEndId.

Gerenciamento de Chaves PIX

| Funcionalidade | Método | Descrição | |---|---|---| | Gerar Código de Autenticação | postAuthCreateKey() | Gera código de autenticação para vincular chave PIX (e-mail ou telefone) | | Criar Chave PIX | postCreateKey() | Cria/vincula uma nova chave PIX à conta | | Listar Chaves PIX | getKeys() | Lista todas as chaves PIX vinculadas à conta | | Deletar Chave PIX | deleteKey() | Remove uma chave PIX vinculada à conta |

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

Webhooks

| Funcionalidade | Método | Descrição | |---|---|---| | Criar Webhook | createWebHook() | Registra um novo webhook para receber notificações de eventos | | Listar Webhooks | getWebHooks() | Lista todos os webhooks registrados | | Consultar Webhook | getWebHookById() | Consulta detalhes de um webhook específico por ID | | Atualizar Webhook | updateWebHook() | Atualiza configuração de um webhook existente | | Deletar Webhook | deleteWebHookById() | Remove um webhook registrado |

Cobranças (Boletos)

| Funcionalidade | Método | Descrição | |---|---|---| | Criar Boleto | createBankSlip() | Cria uma cobrança (boleto ou boleto + PIX) | | Consultar Boleto | getBankSlipByCorrelationId() | Busca detalhes de um boleto por correlationId | | Listar Boletos | getListBankSlip() | Lista boletos com filtros de data e paginação | | Atualizar Boleto | updateBankSlip() | Atualiza a data de vencimento de um boleto | | Cancelar Boleto | postBaiWhenBankSlip() | Cancela/anula um boleto pendente |

Tipos suportados:

• BANKSLIP - Boleto bancário tradicional
• BANKSLIP_PIX - Boleto com opção de pagamento via PIX

Pagamento de Boletos

| Funcionalidade | Método | Descrição | |---|---|---| | Consultar Pagamento | getPaymentBankSlip() | Consulta um pagamento de boleto realizado | | Pagar Boleto | postPaymentBankSlip() | Realiza o pagamento de um boleto via código de barras |

Exemplos de Uso (TypeScript)

Os exemplos abaixo mostram chamadas usando o sdkClientFactory e os nomes reais dos métodos expostos pelos serviços (pixService, webHookService, bankSlipService).

Criar QR Code Estático

const client = sdkClientFactory.createServicesClient(options);

const staticReq = {
  correlationId: 'corr-' + Date.now(),
  pixKey: '11999999999',
  amount: 50,
  bankAccount: '123456',
  beneficiaryName: 'Minha Empresa'
};

const staticRes = await client.pixService.postQRCodeStatic(staticReq);
console.log('QR criado:', staticRes);

Criar QR Code Dinâmico Imediato

const dynReq = { correlationId: 'corr-' + Date.now(), amount: 100, expiresIn: '3600' };
const dynRes = await client.pixService.postQRCodeDynamicImediate(dynReq);
console.log('QR dinâmico imediato:', dynRes);

Criar QR Code com Vencimento e Encargos

// dueDate deve ser maior que data atual
const dueReq = { 
    correlationId: 'corr-' + Date.now(),
    amount: 10,
    dueDate: "yyyy-mm-dd",
    payer:{
        name:"",
        document:""
    }};
const dueRes = await client.pixService.postQRCodeDynamicDueDate(dueReq);
console.log('QR com vencimento:', dueRes);

Consultar QR Code com Vencimento

const txId = 'transaction-id';
const qrInfo = await client.pixService.getQRCodeDynamicDueDate(txId);
console.log('QR info:', qrInfo);

Inicializar Pagamento via Chave PIX

const initReq = { key: '[email protected]' };
const initRes = await client.pixService.postPaymentInitalization(initReq);
console.log('EndToEndId:', initRes.endToEndId);

Criar Transferência PIX

// Imports opcionais para tipagem explícita:
// import { manualPixTransferRequest } from '@delbank/delfinance-api-sdk/dist/delSdk';

// inicialize para obter endToEndId
const init = await client.pixService.postPaymentInitalization({ key: '11999999999' });

const transferReqInternal = {
    amount: 100,
    beneficiaryAccount: 'CONTA_DO_BENEFICIARIO',
    endToEndId: init.endToEndId
};

const transferReqPixManual: manualPixTransferRequest = {
  amount: 1,
    pixRecipient: {
    type: 'MANUAL'
  },
  beneficiary: {
    name: 'teste',
    number: '12345',
    branch: '12',
    participantIspb: '32132132',
        type: 'CURRENT',
    holder: {
      document: '30030030030',
      name: 'Teste Em Hml',
      type: 'NATURAL'
    }
  }
};

const transferResInternal = await client.pixService.postInternalTransfer(transferReqInternal);
console.log('Transferência por conta:', transferResInternal);

const transferResManual = await client.pixService.postManualPixTransfer(transferReqPixManual);
console.log('Transferência PIX manual:', transferResManual);

Criar Transferência PIX por Chave (com endToEndId)

// Import opcional para tipagem explícita:
// import { keyPixTransferRequest } from '@delbank/delfinance-api-sdk/dist/delSdk';

const transferReqPixByKey: keyPixTransferRequest = {
    amount: 1,
    endToEndId: 'E3822485720260325135417ReDVw2IBc',
    initiationType: 'KEY'
};

const transferResPixByKey = await client.pixService.postKeyPixTransfer(transferReqPixByKey);
console.log('Transferência PIX por chave:', transferResPixByKey);

Retorno esperado no PIX manual:

• status: PIX_PROCESSING
• type: PIX_MANUAL
• paymentChannel: API
• payer e beneficiary com dados de conta/holder/participant

Criar Transferência TED

// Imports necessários para tipagem + enum:
// import { transferTEDRequest, accountType } from '@delbank/delfinance-api-sdk/dist/delSdk';

const tedReq: transferTEDRequest = {
                amount: 500,
                description: 'Pagamento fornecedor',
                beneficiary: {
                    participantIspb: '00000000',
                    branch: '0001',
                    number: '123456-7',
                    holder: {
                        document: '12345678901',
                        name: 'João da Silva',
                    },
                    type: accountType.CURRENT
                }
            };
const tedRes = await client.pixService.postTEDTransfer(tedReq);
console.log('TED:', tedRes);

Inicializar Pagamento via QR Code (payload)

const qrInit = await client.pixService.postQRCodePaymentInitalization({ payload: '00020126580014br.gov.bcb.pix...' });
console.log('QR init:', qrInit);

Gerenciamento de Chaves PIX

// gerar código de autenticação import authEntriesType SMS = 'SMS' (SMS, EMAIL), informar por padrão {{code}} no parametro payload
const auth = await client.pixService.postAuthCreateKey({ 
    sender: authEntriesType.SMS,
    receiver: "+5579999999999"
    payload:"{{code}}"});
// criar chave (entryType: 'EMAIL'|'PHONE'|...)
const createKey = await client.pixService.postCreateKey('EMAIL');
// listar chaves
const keys = await client.pixService.getKeys();
// deletar chave (entryType: = DOCUMENT, EVP, PHONE, EMAIL) import entryType
await client.pixService.deleteKey({ entryType: entryType.EMAIL, key: '[email protected]' });

Webhooks

const webhookReq = { 
    eventType: 'PIX_RECEIVED', 
    url: 'https://meusite.com.br/webhook/pix', 
    authorizationScheme: 'BEARER', 
    authorization: 'seu-token' 
};
const webhookRes = await client.webHookService.createWebHook(webhookReq);
const webhooks = await client.webHookService.getWebHooks();
const webhook = await client.webHookService.getWebHookById(webhookRes.id);
await client.webHookService.updateWebHook({ id: webhookRes.id, eventType: 'PIX_REFUNDED', url: 'https://novo.com.br/pix' });
await client.webHookService.deleteWebHookById(String(webhookRes.id));

Cobranças (Bank Slips)

const chargeReq = { 
    type: 'BANKSLIP_PIX', 
    correlationId: 'corr-' + Date.now(), 
    amount: 150, 
    dueDate: new Date().toISOString(), 
    yourNumber: '12345', 
    payer: { 
        name: 'João Silva', 
        document: '12345678901', 
        email: '[email protected]',
        phone:{
            prefix: '79',
            number: '999999999'
        },
        address:{
            zipCode: "49065800",
            neighborhood: "ascasd",
            complement: "asda",
            city: "ARACAJU",
            state: "SE",
            publicPlace: "sadadasd",
            number: "321"
        }
    } 
};

const chargeRes = await client.bankSlipService.createBankSlip(chargeReq);
const chargeInfo = await client.bankSlipService.getBankSlipByCorrelationId(chargeReq.correlationId);
const charges = await client.bankSlipService.getListBankSlip();
await client.bankSlipService.updateBankSlip({ correlationId: chargeReq.correlationId, dueDate: new Date().toISOString() });
await client.bankSlipService.postBaiWhenBankSlip(chargeReq.correlationId); // cancelar

Pagamento de Boleto

const payReq = { 
    barCode: '12345678901234567890123456789012345678901244', 
    amount: 150
};
const proof = await client.bankSlipService.postPaymentBankSlip(payReq);
console.log('Comprovante:', proof);
const paymentInfo = await client.bankSlipService.getPaymentBankSlip(payReq.barCode);
console.log('Info do pagamento:', paymentInfo);

Métodos Obsoletos

Atualmente não há métodos obsoletos no SDK. Todas as funcionalidades estão ativas e mantidas.

Estrutura do Projeto

src/
├── delSdk/                     # Biblioteca principal do SDK
│   ├── abstractions/           # Interfaces, DTOs e contratos
│   │   ├── delEnvironment.ts  # Ambientes suportados (Sandbox, Production)
│   │   ├── delSdkOptions.ts   # Opções e configuração do SDK
│   │   ├── baseUrlResolver.ts # Resolução de URLs por ambiente
│   │   └── sdkClientFactory.ts # Factory para criar clientes de serviços
│   ├── services/               # Implementações dos serviços
│   │   ├── pixService.ts      # Operações PIX (QR codes, transferências, chaves)
│   │   ├── webHookService.ts  # Gerenciamento de webhooks
│   │   ├── bankSlipService.ts # Boletos e cobranças
│   │   ├── httpClient.ts      # Cliente HTTP (get, post, patch, delete)
│   │   └── common/            # Tipos e interfaces compartilhadas
│   │       ├── enum/          # Enumerações do domínio
│   │       │   └── enum.ts    # Tipos e enums reutilizáveis
│   │       └── interfaces/    # Interfaces de tipos
│   │           ├── pix.ts     # Tipos PIX
│   │           ├── bankSlip.ts # Tipos de boletos
│   │           ├── transfer.ts # Tipos de transferências
│   │           ├── webHook.ts # Tipos de webhooks
│   │           └── shared.ts  # Tipos compartilhados
│   └── index.ts               # Exportações principais do SDK
└── delSdk.samples/             # Projeto de exemplo
    └── sample.ts              # Exemplos de uso do SDK

Instalação e Desenvolvimento

Instale as dependências:

npm install

Para desenvolvimento com TypeScript:

npm install --save-dev ts-node typescript @types/node

Compile o código TS:

npx tsc

🧩 Requisitos adicionais para TypeScript

Se você estiver usando este SDK em um projeto TypeScript, certifique-se de instalar os tipos do Node.js para evitar erros de compilação relacionados aos módulos nativos (https, crypto etc):

⚠️ Nota: Este SDK é projetado para ambientes Node.js e pode não funcionar corretamente em projetos frontend (React, Angular, etc.) sem adaptações específicas.

Notas de Versão

• 0.6.5 - Pilot