SDKs

Das B2Brouter PHP SDK ermöglicht es Ihnen, elektronische Rechnungsstellung und Tax Reporting in Ihre PHP-Anwendung zu integrieren, ohne sich mit rohen HTTP-Requests befassen zu müssen.

• Keine Abhängigkeiten — PHP 7.4+ mit Standard-Erweiterungen (cURL, JSON, mbstring)
• Automatische Retries — Netzwerkfehler werden mit Exponential Backoff behandelt
• Pagination-Unterstützung — Iterator und Countable für große Ergebnismengen
• Vollständige Tax-Report-Unterstützung — Verifactu, TicketBAI, SDI, KSeF, ZATCA und mehr

Installation

composer require b2brouter/b2brouter-php

Schnellstart

<?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 "Invoice created: {$invoice['id']}\n";

Konfiguration

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

Das SDK verwendet standardmäßig https://api.b2brouter.net. Verwenden Sie einen test_-Schlüssel für Sandbox oder einen Produktionsschlüssel für Production. Setzen Sie api_base nur dann auf https://api-staging.b2brouter.net, wenn Sie die Staging-Umgebung benötigen.

Ihre Anwendung identifizieren

Integratoren und Plugins können ihre Identität an den User-Agent-Header anhängen:

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

Rechnungen

Erstellen

$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,
]);

Abrufen, aktualisieren, löschen

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

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

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

Auflisten mit Pagination

$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()}, has more: " . ($invoices->hasMore() ? 'yes' : 'no') . "\n";

Herunterladen

PDF

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

Facturae 3.2.2

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

UBL BIS3

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

Senden und bestätigen

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

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

Konten und Kontakte

Konten

$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);

Kontakte

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

Tax Reports

Tax Reports werden automatisch erzeugt, wenn Sie Rechnungen senden, sofern Sie TaxReportSettings für das Konto konfiguriert haben. Siehe Tax Report Settings für Einrichtungsanweisungen.

Einstellungen konfigurieren

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

Abrufen und herunterladen

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

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

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

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

Korrektur und Annullierung

Korrektur

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

Annullierung

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

Status

State	Meaning
processing	Verkettung und Übermittlung laufen
registered	Von der Steuerbehörde akzeptiert
registered_with_errors	Mit Warnungen übermittelt
error	Übermittlung fehlgeschlagen
annulled	Storniert

Fehlerbehandlung

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 — invalid API key
} catch (PermissionException $e) {
    // 403 — insufficient permissions
} catch (ResourceNotFoundException $e) {
    // 404
} catch (InvalidRequestException $e) {
    // 400 / 422 — validation errors
    $details = $e->getJsonBody();
} catch (ApiConnectionException $e) {
    // network error
} catch (ApiErrorException $e) {
    // any other API error
    error_log("Request ID: {$e->getRequestId()}");
}

Protokollieren Sie bei Support-Anfragen immer die Request ID — sie identifiziert die fehlgeschlagene Anfrage eindeutig.