SDKs

El SDK de PHP de B2Brouter us permet integrar la facturació electrònica i els informes fiscals a la vostra aplicació PHP sense haver de gestionar peticions HTTP en brut.

Zero dependències — PHP 7.4+ amb extensions estàndard (cURL, JSON, mbstring)
Reintents automàtics — fallades de xarxa gestionades amb exponential backoff
Suport de paginació — Iterator i Countable per a conjunts de resultats grans
Suport complet d’informes fiscals — Verifactu, TicketBAI, SDI, KSeF, ZATCA i més

Instal·lació

composer require b2brouter/b2brouter-php

Inici ràpid

<?php

require_once 'vendor/autoload.php';

use B2BRouter\B2BRouterClient;

$client = new B2BRouterClient('your-api-key');
$accountId = 'your-account-id';

$invoice = $client->invoices->create($accountId, [
    'invoice' => [
        'number' => 'INV-2025-001',
        'date' => '2025-01-15',
        'due_date' => '2025-02-15',
        'currency' => 'EUR',
        'contact' => [
            'name' => 'Acme Corporation',
            'tin_value' => 'ESB12345678',
            'country' => 'ES',
            'email' => 'billing@acme.com',
        ],
        'invoice_lines_attributes' => [
            [
                'description' => 'Professional Services',
                'quantity' => 10,
                'price' => 100.00,
                'taxes_attributes' => [
                    ['name' => 'IVA', 'category' => 'S', 'percent' => 21.0]
                ]
            ]
        ]
    ]
]);

echo "Factura creada: {$invoice['id']}\n";

Configuració

$client = new B2BRouterClient('your-api-key', [
    // 'api_base' => 'https://api.b2brouter.net',          // Sandbox i Producció (per defecte)
    // 'api_base' => 'https://api-staging.b2brouter.net',  // Staging
    'api_version' => '2026-04-20',
    'timeout'     => 80,
    'max_retries' => 3,
]);

El SDK usa per defecte https://api.b2brouter.net. Useu una clau test_ per a sandbox o una clau de producció per a producció. Configureu api_base a https://api-staging.b2brouter.net únicament si necessiteu l’entorn staging.

Identificar la vostra aplicació

Els integradors i plugins poden afegir la seva identitat a la capçalera User-Agent:

$client = new B2BRouterClient('your-api-key', [
    'app_info' => [
        'name'    => 'MyApp',              // obligatori
        'version' => '1.0.0',             // opcional
        'url'     => 'https://myapp.com', // opcional
    ],
]);

Factures

Crear

$invoice = $client->invoices->create($accountId, [
    'invoice' => [
        'number' => 'INV-2025-001',
        'date'   => '2025-01-15',
        'currency' => 'EUR',
        'contact' => [
            'name'      => 'Customer Name',
            'tin_value' => 'ESB12345678',
            'country'   => 'ES',
        ],
        'invoice_lines_attributes' => [
            [
                'description' => 'Service',
                'quantity'    => 1,
                'price'       => 1000.00,
                'taxes_attributes' => [
                    ['name' => 'IVA', 'category' => 'S', 'percent' => 21.0]
                ]
            ]
        ]
    ],
    'send_after_import' => false,
]);

Recuperar, actualitzar, eliminar

$invoice = $client->invoices->retrieve($invoiceId);

$invoice = $client->invoices->update($invoiceId, [
    'invoice' => ['extra_info' => 'Payment terms: 30 days net']
]);

$client->invoices->delete($invoiceId);

Llistar amb paginació

$invoices = $client->invoices->all($accountId, [
    'limit'     => 25,
    'offset'    => 0,
    'date_from' => '2025-01-01',
    'date_to'   => '2025-12-31',
]);

foreach ($invoices as $invoice) {
    echo "{$invoice['number']}: €{$invoice['total']}\n";
}

echo "Total: {$invoices->getTotal()}, n'hi ha més: " . ($invoices->hasMore() ? 'sí' : 'no') . "\n";

Descarregar

$pdf = $client->invoices->downloadPdf($invoiceId);
file_put_contents('invoice.pdf', $pdf);

$xml = $client->invoices->downloadAs($invoiceId, 'xml.facturae.3.2.2');

$xml = $client->invoices->downloadAs($invoiceId, 'xml.ubl.invoice.bis3');

Enviar i reconèixer

$client->invoices->send($invoiceId);

$client->invoices->acknowledge($invoiceId, ['ack' => true]);

$accounts = $client->accounts->all(['limit' => 25]);
$account  = $client->accounts->retrieve($accountId);
$account  = $client->accounts->create(['account' => [/* ... */]]);
$account  = $client->accounts->update($accountId, ['account' => [/* ... */]]);
$client->accounts->delete($accountId);
$client->accounts->unarchive($accountId);

$contacts = $client->contacts->all($accountId, ['limit' => 25]);
$contact  = $client->contacts->create($accountId, ['contact' => [/* ... */]]);
$contact  = $client->contacts->update($contactId, ['contact' => [/* ... */]]);
$client->contacts->delete($contactId);

Informes fiscals

Els informes fiscals es generen automàticament quan envieu factures, sempre que hàgiu configurat TaxReportSettings per al compte. Consulteu Configuració d’informes fiscals per a les instruccions de configuració.

Configurar paràmetres

$client->taxReportSettings->create($accountId, [
    'tax_report_setting' => [
        'code'       => 'verifactu',
        'start_date' => '2025-01-01',
        'auto_generate' => true,
        'auto_send'     => true,
    ]
]);

Recuperar i descarregar

$taxReportId = $invoice['tax_report_ids'][0];
$taxReport   = $client->taxReports->retrieve($taxReportId);

echo "Estat: {$taxReport['state']}\n";

if (!empty($taxReport['qr'])) {
    file_put_contents('qr.png', base64_decode($taxReport['qr']));
}

$xml = $client->taxReports->download($taxReportId);

Correcció i anul·lació

Correcció
Anul·lació

$client->taxReports->update($taxReportId, [
    'tax_report' => ['tax_inclusive_amount' => 133.1, /* ... */]
]);

$client->taxReports->delete($taxReportId);

Estats

Estat	Significat
`processing`	Encadenament i enviament en curs
`registered`	Acceptat per l’autoritat fiscal
`registered_with_errors`	Enviat amb advertiments
`error`	Enviament fallit
`annulled`	Cancel·lat

Gestió d’errors

use B2BRouter\Exception\ApiErrorException;
use B2BRouter\Exception\AuthenticationException;
use B2BRouter\Exception\PermissionException;
use B2BRouter\Exception\ResourceNotFoundException;
use B2BRouter\Exception\InvalidRequestException;
use B2BRouter\Exception\ApiConnectionException;

try {
    $invoice = $client->invoices->create($accountId, ['invoice' => [/* ... */]]);
} catch (AuthenticationException $e) {
    // 401 — clau d'API no vàlida
} catch (PermissionException $e) {
    // 403 — permisos insuficients
} catch (ResourceNotFoundException $e) {
    // 404
} catch (InvalidRequestException $e) {
    // 400 / 422 — errors de validació
    $details = $e->getJsonBody();
} catch (ApiConnectionException $e) {
    // error de xarxa
} catch (ApiErrorException $e) {
    // qualsevol altre error d'API
    error_log("Request ID: {$e->getRequestId()}");
}

Registreu sempre el Request ID quan reporteu problemes al suport — identifica de manera única la petició fallida.