SDK para Integração de Boletos com CitiBank

Este é um SDK para Node.js, escrito em TypeScript, que facilita a integração com a API de registro de boletos do CitiBank. Ele abstrai a complexidade da comunicação SOAP e da construção do XML, oferecendo uma interface moderna e fluida para o desenvolvedor.

Funcionalidades

• Padrão Builder: Crie boletos de forma legível e segura, encadeando métodos (setBeneficiario, setPagador, etc.).
• Suporte a Payload Direto: Para flexibilidade, permite o envio do objeto completo do boleto de uma só vez.
• Tratamento de Respostas com Hooks: Utilize onSuccess, onError e onFail para lidar com os diferentes cenários de resposta da API de forma assíncrona.
• Tipagem Forte com TypeScript: Aproveite a segurança e o autocompletar do TypeScript com interfaces bem definidas para todas as estruturas de dados.
• Modo de Depuração: Ative logs detalhados para facilitar a identificação de problemas durante a integração.

Instalação

npm install @dueheads/citi-bank-boleto-sdk --save

Configuração

Primeiro, importe e instancie o SDK, fornecendo a configuração necessária, incluindo os caminhos para seus certificados de segurança.

import { CitiBankBoletoSDK } from '@dueheads/citi-bank-boleto-sdk';

const sdk = new CitiBankBoletoSDK({
    certPath: './certs/cert.crt',
    keyPath: './certs/private.key',
    rejectUnauthorized: false, // Em produção, use 'true'.
    debug: true, // Ativa logs detalhados no console.
});

Como Usar

Existem duas maneiras principais de registrar um boleto.

Exemplo 1: Usando o Padrão Builder (Recomendado)

Este método é mais verboso, porém mais seguro e legível, pois utiliza métodos específicos para cada parte do boleto.

import { 
    CitiBankBoletoSDK,
    SuccessResponse, 
    ErrorResponse, 
    SoapFaultResponse,
    BeneficiarioData,
    PagadorData,
    SacadorData,
    DocumentoData
} from '@dueheads/citi-bank-boleto-sdk';

// 1. Defina os dados do boleto
const beneficiario: BeneficiarioData = { /* ... */ };
const pagador: PagadorData = { /* ... */ };
const sacador: SacadorData = { /* ... */ };
const documento: DocumentoData = { /* ... */ };

// 2. Registre os hooks e encadeie os métodos para construir e enviar o boleto
try {
    await sdk
        .onSuccess((res: SuccessResponse) => {
            console.log('SUCESSO (Builder):', res);
        })
        .onError((res: ErrorResponse) => {
            console.error('ERRO DE NEGÓCIO (Builder):', res);
        })
        .onFail((error: SoapFaultResponse | Error) => {
            console.error('FALHA GERAL (Builder):', error);
        })
        .setBeneficiario(beneficiario)
        .setPagador(pagador)
        .setSacador(sacador)
        .setDocumento(documento)
        .registraBoleto(); // O método send() dispara o processo

} catch (error) {
    console.error('Ocorreu um erro fatal na execução do SDK (Builder):', error);
}

Exemplo 2: Usando o Payload Completo

Este método é útil se você já possui o objeto completo do boleto.

import { 
    CitiBankBoletoSDK,
    BoletoPayload 
} from '@dueheads/citi-bank-boleto-sdk';

// 1. Monte o objeto completo do boleto
const boletoCompleto: BoletoPayload = {
    dadosBeneficiario: { /* ... */ },
    dados: {
        pagador: { /* ... */ },
        sacador: { /* ... */ },
        documento: { /* ... */ }
    }
};

// 2. Registre os hooks e chame o método de registro
try {
    sdk.onSuccess((res) => { /* ... */ })
       .onError((res) => { /* ... */ })
       .onFail((err) => { /* ... */ });

    await sdk.registraBoletoWithPayload(boletoCompleto);

} catch (error) {
    console.error('Ocorreu um erro fatal na execução do SDK (Payload):', error);
}

Tratamento de Respostas (Hooks)

• .onSuccess(callback): É chamado quando o boleto é registrado com sucesso. A callback recebe um objeto SuccessResponse.
• .onError(callback): É chamado quando a API retorna um erro de negócio, como um campo inválido. A callback recebe um objeto ErrorResponse com um array de erros detalhados.
• .onFail(callback): É chamado em caso de falha na comunicação (ex: erro de certificado, timeout, SOAP Fault) ou exceção interna do SDK.

Interfaces

Todas as estruturas de dados (BoletoPayload, PagadorData, SuccessResponse, etc.) são tipadas e exportadas pelo pacote para garantir a consistência e segurança do seu código.