PHP code example of husail / cnab-sdk

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

husail / cnab-sdk example snippets

use Husail\CnabSdk\Types\CnabDate;
use Husail\CnabSdk\Banks\Itau\Cnab240Itau;
use Husail\CnabSdk\Builder\CnabBatchBuilder;

$file = Cnab240Itau::pagamentos()
    ->fileHeader([
        'company_type'     => '2',             // 2 = CNPJ
        'company_document' => '12345678000195',
        'bank_branch'      => '00341',
        'bank_account'     => '123456789012',
        'company_name'     => 'ACME LTDA',
        'generated_date'   => CnabDate::toDate(now()), // DDMMAAAA
        'generated_time'   => CnabDate::toTime(now()), // HHMMSS
        'sequence_number'  => '000000001',
    ])
    ->batch(function (CnabBatchBuilder $batch) use ($payments) {
        $batch->header([
            'operation_type'   => 'C',         // C = Credit
            'payment_type'     => '20',        // Credit to account
            'payment_form'     => '01',
            'company_type'     => '2',
            'company_document' => '12345678000195',
            'bank_branch'      => '00341',
            'bank_account'     => '123456789012',
            'company_name'     => 'ACME LTDA',
        ]);

        foreach ($payments as $payment) {
            $batch->add('segment_a', [
                'clearing_code'      => '009',
                'recipient_bank'     => $payment->bankCode,
                'bank_branch'        => $payment->bankBranch,
                'bank_account'       => $payment->bankAccountNumber,
                'recipient_name'     => $payment->recipientName,
                'payment_date'       => CnabDate::toDate($payment->paymentDate),
                'bank_ispb'          => $payment->bankIspb,
                'transfer_type'      => '01',  // TED
                'amount'             => $payment->amount, // float: 150.75
                'recipient_document' => $payment->recipientDocument,
            ]);
        }
    })
    ->toString();

->batch(function (CnabBatchBuilder $batch) use ($payments) {
    $batch->header(['operation_type' => 'C', 'payment_type' => '45', ...]);

    foreach ($payments as $payment) {
        $batch->add('segment_a', [
            'transfer_type'      => 'PIX',
            'amount'             => $payment->amount,
            'recipient_document' => $payment->recipientDocument,
            // other fields...
        ]);

        $batch->add('segment_b_pix', [
            'pix_key_type'       => '04',          // 04 = random key (EVP)
            'recipient_type'     => '2',           // 2 = CNPJ
            'recipient_document' => $payment->recipientDocument,
            'pix_key'            => $payment->pixKey,
            'txid'               => $payment->txid, // optional
        ]);
    }
})

$batch->add('segment_b', [
    'recipient_type'     => '2',
    'recipient_document' => $payment->recipientDocument,
    'email'              => $payment->email, // optional
]);

Cnab240Itau::pagamentos()
    ->fileHeader([...])

    ->batch(function (CnabBatchBuilder $batch) use ($tedPayments) {
        $batch->header(['operation_type' => 'C', 'payment_type' => '20', 'payment_form' => '01', ...]);
        foreach ($tedPayments as $p) {
            $batch->add('segment_a', [...]);
        }
    })

    ->batch(function (CnabBatchBuilder $batch) use ($pixPayments) {
        $batch->header(['operation_type' => 'C', 'payment_type' => '45', 'payment_form' => '01', ...]);
        foreach ($pixPayments as $p) {
            $batch->add('segment_a', [...]);
            $batch->add('segment_b', [...]);
        }
    })

    ->toString();

// Override batch trailer fields
$batch->trailer([
    'total_amount' => 47075,
]);

// Override file trailer fields
->fileTrailer([
    'batch_count'  => 2,
    'record_count' => 10,
])

use Husail\CnabSdk\Banks\Itau\Cnab240Itau;
use Husail\CnabSdk\Cnab;

$content = file_get_contents('/path/to/retorno.txt');
$layout  = Cnab240Itau::layout();

// Always validate before parsing
$validation = Cnab::validate($content, $layout);
if ($validation->fails()) {
    foreach ($validation->errors() as $error) {
        echo "Line {$error->line} [{$error->record}] {$error->field}: {$error->message}";
    }
}

$result = Cnab::parse($content, $layout);

// File header
$header = $result->first('file_header');
echo $header?->get('company_name');
echo $header?->get('file_code');    // '1' = remessa, '2' = retorno
echo $header?->get('generated_date');

// Segment A collection — TED, DOC, PIX by bank account
$segmentsA = $result->records('segment_a');
$segmentsA->count();
$segmentsA->each(function ($seg) {
    echo $seg->get('recipient_name');
    echo $seg->get('amount');          // float
    echo $seg->get('occurrence_code'); // '00' = paid
    echo $seg->get('effective_date');  // filled by bank on return
});

// Filter paid segments
$paid = $segmentsA->filter(fn ($seg) => $seg->get('occurrence_code') === '00');

// Segment B PIX — PIX by key complement
$result->records('segment_b_pix')->each(function ($seg) {
    echo $seg->get('pix_key_type');
    echo $seg->get('pix_key');
    echo $seg->get('occurrence_code');
});

// Segment J — boletos and concessionárias
$result->records('segment_j')->each(function ($seg) {
    echo $seg->get('recipient_name');
    echo $seg->get('payment_amount'); // float
    echo $seg->get('occurrence_code');
});

// Segment J52 — payer/beneficiary data and QR Code
$result->records('segment_j52')->each(function ($seg) {
    echo $seg->get('payer_document');
    echo $seg->get('beneficiary_name');
    echo $seg->get('pix_url');
});

use Husail\CnabSdk\Banks\Itau\Cnab240Itau;
use Husail\CnabSdk\Cnab;

$result   = Cnab::parse($content, Cnab240Itau::layout());
$payments = Cnab240Itau::groupPayments($result);

$payments->count();        // total payments
$payments->pixCount();     // PIX payments only
$payments->boletoCount();  // boleto payments only

foreach ($payments->payments() as $group) {
    $group->batchCode(); // '0001'
    $group->sequence();  // '00001'

    $group->get('segment_a')?->get('amount');
    $group->get('segment_j')?->get('barcode');
    $group->has('segment_b_pix'); // bool
}

foreach ($payments->pixPayments() as $pix) {
    $pix->batchCode();
    $pix->sequence();
    $pix->isPixByKey(); // true when segment_b_pix is present

    // segment_a — always present
    $pix->segmentA()->get('amount');         // float
    $pix->segmentA()->get('recipient_name');
    $pix->segmentA()->get('payment_date');

    // segment_b — PIX by bank account complement (optional)
    $pix->segmentB()?->get('email');

    // segment_b_pix — PIX by key complement (optional)
    $pix->segmentBPix()?->get('pix_key');
    $pix->segmentBPix()?->get('pix_key_type'); // '04' = random key
}

foreach ($payments->boletoPayments() as $boleto) {
    $boleto->batchCode();
    $boleto->sequence();
    $boleto->hasPixQrCode(); // true when segment_j52 has a pix_url

    // segment_j — always present
    $boleto->segmentJ()->get('barcode');
    $boleto->segmentJ()->get('payment_amount'); // float
    $boleto->segmentJ()->get('due_date');

    // segment_j52 — payer/beneficiary and QR Code (optional)
    $boleto->segmentJ52()?->get('payer_name');
    $boleto->segmentJ52()?->get('beneficiary_name');
    $boleto->segmentJ52()?->get('pix_url');
}

// Payments above R$ 1,000
$highValue = $payments->filter(
    fn ($group) => ($group->get('segment_a')?->get('amount') ?? 0) > 1000
);

// All PIX by key
$pixByKey = $payments->filter(
    fn ($group) => $group->has('segment_b_pix')
);

use Husail\CnabSdk\Banks\Itau\Cnab240Itau;
use Husail\CnabSdk\Cnab;

$result = Cnab::validate($content, Cnab240Itau::layout());

if ($result->passes()) {
    // safe to process
}

foreach ($result->errors() as $error) {
    echo "Line {$error->line} [{$error->record}] {$error->field}: {$error->message}";
}

use Husail\CnabSdk\Cnab;

$layout = Cnab::fromYaml('/path/to/my-bank/cnab240-pagamentos.yaml');

$file = Cnab::write($layout)
    ->fileHeader([...])
    ->batch(function ($batch) use ($payments) {
        $batch->header([...]);
        foreach ($payments as $p) {
            $batch->add('segment_a', [...]);
        }
    })
    ->toString();

use Husail\CnabSdk\Types\CnabDate;
use Husail\CnabSdk\Types\Monetary;

// Dates
CnabDate::toDate(now());           // '08052026'
CnabDate::toTime(now());           // '143052'
CnabDate::fromDate('08052026');    // DateTimeImmutable
CnabDate::zero();                  // '00000000'
CnabDate::isZero('00000000');      // true

// Monetary values
Monetary::serialize(150.75, decimalPlaces: 2, length: 15); // '000000000015075'
Monetary::deserialize('000000000015075', decimalPlaces: 2); // 150.75
Monetary::format(150.75);                                    // 'R$ 150,75'

use Husail\CnabSdk\Contracts\BankLayoutInterface;
use Husail\CnabSdk\Builder\CnabFileBuilder;
use Husail\EdiSdk\Drivers\YamlDriver;
use Husail\EdiSdk\Schema\FileLayout;

class Cnab240MyBank implements BankLayoutInterface
{
    public const BANK_CODE = '999';
    public const BANK_NAME = 'MY BANK SA';

    private const LAYOUT = __DIR__ . '/../../Layouts/MyBank/cnab240/pagamentos/layout.yaml';

    public static function layout(): FileLayout
    {
        return (new YamlDriver())->load(self::LAYOUT);
    }

    public static function pagamentos(): CnabFileBuilder
    {
        return new CnabFileBuilder(self::layout());
    }
}