b2brouter/b2brouter-php

What's changed

This is a docs + default-version release. The SDK default API version moves to 2026-04-20 (minor bump per the versioning policy), and the SDK now self-identifies on every request via a User-Agent header.

New features

• User-Agent header on every request — the SDK identifies itself as B2BRouter-PHP/1.3.0 (PHP/{version}; curl/{version}). Applies to JSON and binary endpoints. No caller action required.
• app_info constructor option — applications that wrap the SDK (integrators, plugins) can identify themselves in the User-Agent header.
• B2BRouterClient::VERSION constant and B2BRouterClient::getUserAgent() getter.

Default API version → 2026-04-20

The SDK default api_version moves from 2026-03-02 to 2026-04-20. The PHP interface is unchanged; callers can pin the previous API version via the api_version config option.

The CHANGELOG [1.3.0] entry includes a full migration guide covering the 2026-04-20 API delta (invoice_references[] in place of flat amend fields, classification_code_scheme typo fix, removed payment_method_info response field, inline contact identifier requirement, stricter contact/parent_id validation, Peppol transport response shape changes, plus all new fields).

The CHANGELOG also notes that the new TIN verification endpoint and tin_verification.finished webhook event ship with v2026-04-20 but are not yet surfaced by the SDK.

Also included

• New example: identify_caller_app.php
• docs/VERSIONING.md adds a "Supported API versions" section
• All examples updated to use the new default

Quick start

// Identify your integrating app in the User-Agent header
$client = new B2BRouterClient('your-api-key', [
    'app_info' => [
        'name'    => 'B2BRouter-WooCommerce',
        'version' => '1.0.3',
        'url'     => 'https://shop.example.com',
    ],
]);

// Pin the previous API version if you need time to migrate
$client = new B2BRouterClient('your-api-key', [
    'api_version' => '2026-03-02',
]);

Full Changelog: v1.2.0...v1.3.0

Added

• User-Agent header on every request — the SDK now identifies itself with a header like B2BRouter-PHP/1.3.0 (PHP/8.2.10; curl/8.5.0). Applies to both JSON and binary endpoints. No caller action required.
• app_info constructor option — applications that wrap the SDK (e.g. integrators, plugins) can identify themselves in the User-Agent header:

  $client = new B2BRouterClient('sk_...', [
      'app_info' => [
          'name'    => 'B2BRouter-WooCommerce',   // required
          'version' => '1.0.3',                    // optional
          'url'     => 'https://shop.example.com', // optional
      ],
  ]);
  

  Produces: B2BRouter-PHP/1.3.0 (PHP/8.2.10; curl/8.5.0) B2BRouter-WooCommerce/1.0.3 (https://shop.example.com).
• B2BRouterClient::VERSION constant — the SDK version, also accessible at runtime.
• B2BRouterClient::getUserAgent() — returns the composed User-Agent string (lazy, cached).
• New example: identify_caller_app.php

Changed

• Default API version updated from 2026-03-02 to 2026-04-20

API version 2026-04-20 migration guide

The following changes apply only if you use API version 2026-04-20 (the new default). If you pin 'api_version' => '2026-03-02', your existing code continues to work unchanged.

To keep the previous API version:

$client = new B2BRouterClient('your-api-key', [
    'api_version' => '2026-03-02',
]);

Invoice amend fields replaced by invoice_references[]

The flat amend fields on invoices have been removed in favour of a structured invoice_references[] array. Each entry carries a reference_type (amend or prepayment) plus the reference data.

Removed fields: amended_number, amended_date, amended_invoicing_period_start, amended_invoicing_period_end, amend_reason, amend_code_tax, correction_method.

Before (API 2026-03-02):

$invoice = $client->invoices->create($accountId, [
    'invoice' => [
        // ...
        'amended_number' => 'INV-2025-001',
        'amended_date' => '2025-01-15',
        'amend_reason' => 'Corrected line items',
    ],
]);

After (API 2026-04-20):

$invoice = $client->invoices->create($accountId, [
    'invoice' => [
        // ...
        'invoice_references' => [
            [
                'reference_type' => 'amend',
                'number' => 'INV-2025-001',
                'date' => '2025-01-15',
                'reason' => 'Corrected line items',
            ],
        ],
    ],
]);

Invoice line field typo fix: clasification_code_scheme → classification_code_scheme

The misspelled clasification_code_scheme (single s) on invoice lines has been renamed to the correctly-spelled classification_code_scheme. Update any payloads that set this field.

Removed invoice response field

payment_method_info is no longer returned. Use the structured fields instead: payment_method, contact_iban, contact_bic.

Inline contact on invoice POST now requires identifier

When creating an invoice with an inline contact block via POST /accounts/{account}/invoices, the contact must include either tin_value or cin_value. The only exception is IssuedSimplifiedInvoice. Previously the inline contact could be created without an identifier; this now returns 422 parameter_invalid.

Contact tin_value / tin_scheme validated against parent

When a contact is created or updated with parent_id set, tin_value and tin_scheme must match the parent contact's values. Mismatches now return 422 parameter_invalid (previously they were silently ignored).

Peppol transport response shape changes

The Peppol transport response replaces standard_documents and pending_peppol_directory_publish with three fields: sml_status, peppol_directory_status, reception_document_types. The SDK does not currently surface Peppol transports through a dedicated service, so this only affects callers parsing the raw response.

New API endpoints not yet surfaced by the SDK

The B2BRouter 2026-04-20 platform release adds two capabilities that this SDK does not yet expose. They are noted here so callers are aware they exist at the API level; dedicated SDK support is planned for a future release.

• TIN verification — POST /tin_verifications?country=es submits a batch of up to 20,000 TIN+name pairs for verification against the tax authority census (Spain / AEAT only at launch). The request returns 202 Accepted; results are retrieved with GET /tin_verifications/{id} or via webhook. A dedicated TinVerificationService is planned.
• tin_verification.finished webhook event — fired when a TIN verification batch reaches a terminal state (success or failed). The payload carries only id and status; use GET /tin_verifications/{id} to fetch the full results. Subscribe via the existing webhook configuration; no SDK helpers or event constants are provided yet.

New API fields (no SDK changes required)

These fields are automatically available through the array-based response:

• Accounts: routing_codes (cin1_value/cin1_scheme … cin5_value/cin5_scheme), auto_remittance, skip_line_taxable_base_rounding.
• Invoices: cin_value and cin_scheme on the contact object; exchange_rate, exchange_date, order_date (previously write-only, now returned); total_amount_due accepted as write-only input.
• Invoices (KSeF): apply_to_local_government_unit, apply_to_vat_group_member, third_party (expandable via ?include=).
• Invoice type_code (KSeF): ZAL, ROZ, KOR_ZAL, KOR_ROZ, KOR, VAT, UPR.
• Tax reports (KSeF): customer_party_jst, customer_party_gv, purchase_order_date, despatch_advice_reference, supplier_party_krs, supplier_party_regon, supplier_party_bdo, supplier_contact_phone, supplier_contact_email, previous_advance_total, order_total_amount, prepayment_references[], writable third_party_*.

What's changed

This release adds full CRUD support for accounts and contacts.

New services

• AccountService ($client->accounts) — list, create, retrieve, update, delete, unarchive, upload/delete logo
• ContactService ($client->contacts) — list, create, retrieve, update, delete

Also included

• New examples: accounts_edocsync.php, accounts_edocexchange.php, contacts.php
• docs/VERSIONING.md — SDK versioning policy documentation

Quick start

// List accounts
$accounts = $client->accounts->all(['limit' => 10]);

// Create a contact                                                                                                  
$contact = $client->contacts->create($accountId, [
    'contact' => [                                                                                                   
        'name' => 'Customer Company',
        'email' => '[email protected]',                                                                           
        'tin_value' => 'ESB87654321',
        'country' => 'ES',                                                                                           
    ]           
]);                                                                                                                  
                
Full Changelog: https://github.com/B2Brouter/b2brouter-php/compare/v1.1.0...v1.2.0

Added

• AccountService ($client->accounts) — full account management:
  • all() — list accounts with Ransack query filtering
  • create() — create a new account (eDocSync subscriptions)
  • retrieve() — get account details
  • update() — update account fields
  • delete() — archive or delete an account
  • unarchive() — restore an archived account
  • uploadLogo() — upload account logo (binary)
  • deleteLogo() — remove account logo
• ContactService ($client->contacts) — full contact management:
  • all() — list contacts with filtering by name, type, and integration code
  • create() — create a new contact
  • retrieve() — get contact details
  • update() — update contact fields
  • delete() — delete a contact
• New examples: accounts.php, contacts.php
• docs/VERSIONING.md — SDK versioning policy documentation

This release updates the default B2BRouter API version from 2025-10-13 to 2026-03-02.

This is a safe upgrade. The SDK's PHP interface is unchanged. If you're not ready to adopt the new API version, pin the previous one:

$client = new B2BRouterClient('your-api-key', [
    'api_version' => '2025-10-13',
]);

What changed in the SDK

• Default API version updated to 2026-03-02
• Request ID header updated to X-B2B-API-Request-Id (falls back to X-Request-Id for older API versions)
• Added versioning policy documentation
• New example: use_previous_api_version.php

API version 2026-03-02 migration guide

The following changes apply only if you use API version 2026-03-02 (the new default).

Removed invoice fields

Use allowance_charges_attributes instead:

• discount_amount, discount_percent, discount_text → allowance_charge_indicator: "allowance"
• charge_amount, charge_percent, charge_reason → allowance_charge_indicator: "charge"
• apply_taxes_to_charge → individual apply_taxes per allowance/charge
• charge_is_reimbursable_expense → individual is_reimbursable_expense per allowance/charge

Same removals apply to invoice line fields (discount_*, charge_*).

Invoice search: taxcode replaced by query

// Before (API 2025-10-13)
$invoices = $client->invoices->all($accountId, ['taxcode' => 'ESB12345678']);

// After (API 2026-03-02)
$invoices = $client->invoices->all($accountId, ['query' => 'tin_value=ESB12345678']);

Other API changes

• type_document renamed to type_code on invoices
• Scheme fields (tin_scheme, cin_scheme, pin_scheme) now return zero-padded 4-char strings (e.g., "0007" instead of 7)
• POST create endpoints return 201 Created instead of 200 OK (SDK handles this transparently)
• contact_id ignored for IssuedSimplifiedInvoice
• Contact is_provider defaults to true when creating via API

New API fields (automatic, no SDK changes needed)

• Invoice: base_quantity, tax_currency_code, tax_amount_in_tax_currency, payments_on_account
• TaxReport: annulled_by_id, corrected_by_id, KSeF-specific fields
• TaxReportLine: item_seller_identifier, item_standard_identifier
• BankAccount: is_default

Upgrade

composer update b2brouter/b2brouter-php

Full changelog: v1.0.0...v1.1.0

Changed

• Default API version updated from 2025-10-13 to 2026-03-02
• Request ID header updated to X-B2B-API-Request-Id (falls back to X-Request-Id for older API versions)

API version 2026-03-02 migration guide

The following changes apply only if you use API version 2026-03-02 (the new default). If you pin 'api_version' => '2025-10-13', your existing code continues to work unchanged.

To keep the previous API version:

$client = new B2BRouterClient('your-api-key', [
    'api_version' => '2025-10-13',
]);

Removed invoice fields

The following invoice-level fields have been removed. Use allowance_charges_attributes instead:

• discount_amount, discount_percent, discount_text — use allowance_charges_attributes with allowance_charge_indicator: "allowance"
• charge_amount, charge_percent, charge_reason — use allowance_charges_attributes with allowance_charge_indicator: "charge"
• apply_taxes_to_charge — use allowance_charges_attributes with individual apply_taxes settings
• charge_is_reimbursable_expense — use allowance_charges_attributes with individual is_reimbursable_expense settings

Removed invoice line fields

The following line-level fields have been removed. Use allowance_charges_attributes instead:

• discount_amount, discount_percent, discount_text — use allowance_charges_attributes with allowance_charge_indicator: "allowance"
• charge_amount, charge_percent, charge_reason — use allowance_charges_attributes with allowance_charge_indicator: "charge"

Invoice search: taxcode replaced by query

Before (API 2025-10-13):

$invoices = $client->invoices->all($accountId, ['taxcode' => 'ESB12345678']);

After (API 2026-03-02):

$invoices = $client->invoices->all($accountId, ['query' => 'tin_value=ESB12345678']);

Other API changes

• type_document renamed to type_code on invoices for document type codes (Peppol, CII, KSeF, FatturaPA)
• Scheme fields (tin_scheme, cin_scheme, pin_scheme) now return zero-padded 4-character strings (e.g., "0007" instead of 7). Unknown scheme returns nil instead of "0001".
• POST create endpoints now return 201 Created instead of 200 OK (SDK handles this transparently)
• contact_id ignored for IssuedSimplifiedInvoice — simplified invoices always use inline contact fields
• Contact is_provider now defaults to true when creating contacts via API

New API fields (no SDK changes required)

These fields are automatically available through the array-based response:

• Invoice: base_quantity (decimal), tax_currency_code (ISO 4217 string), tax_amount_in_tax_currency (decimal), payments_on_account
• TaxReport: annulled_by_id, corrected_by_id (integer, nullable), payment_account_name, purchase_order_reference, sales_order_reference, tax_inclusive_amount_before_allowances_and_charges (KSeF-specific)
• TaxReportLine: item_seller_identifier, item_standard_identifier (TicketBAI/KSeF)
• BankAccount: is_default (boolean)

First Stable Release

This is the first stable release of the B2BRouter PHP SDK. The SDK is production-ready with semantic versioning guarantees. All future 1.x releases will maintain backward compatibility.

Features

Invoice Management

• Complete CRUD operations (create, retrieve, update, delete, list)
• Domain-specific operations:
  • validate() - Validate invoice structure before sending
  • send() - Send invoice to customer and generate tax reports
  • markAs() - Update invoice state (new, sent, paid, etc.)
  • acknowledge() - Mark received invoices as acknowledged
  • import() - Import invoices from external sources
• Multi-format document downloads:
  • downloadAs() - Download in any supported format
  • downloadPdf() - Convenience method for PDF downloads
  • Support for PDF (pdf.invoice)
  • Support for Spanish Facturae XML (xml.facturae.3.2.2)
  • Support for UBL BIS3 (xml.ubl.invoice.bis3)
  • Additional formats based on account configuration

Tax Reports

• Full CRUD operations (create, retrieve, update, delete, list)
• Multi-jurisdiction support:
  • Spanish Verifactu (Law 11/2021 Anti-Fraud compliance)
  • TicketBAI (Basque Country: Álava, Bizkaia, Gipuzkoa)
  • Italian SDI (Sistema di Interscambio)
  • Polish KSeF (National e-Invoicing System)
  • Saudi Zatca (e-invoicing)
• Automatic tax report generation on invoice send
• QR code generation for invoice verification
• Digital fingerprint and hash chain computation
• Corrections (subsanación) via update()
• Annullations (anulación) via delete()
• XML download support

Tax Report Settings

• Configure tax authority settings (Verifactu, TicketBAI, etc.)
• Full CRUD operations
• Auto-generation and auto-send configuration
• Special regime and exemption settings

HTTP Client & Error Handling

• Automatic retry logic with exponential backoff (configurable, default: 3 retries)
• Configurable timeouts (request: 80s, connection: 30s)
• Custom HTTP client support via ClientInterface
• Comprehensive exception hierarchy:
  • ApiErrorException - Base exception for all API errors
  • AuthenticationException - Invalid API key (401)
  • PermissionException - Insufficient permissions (403)
  • ResourceNotFoundException - Resource not found (404)
  • InvalidRequestException - Validation errors (400, 422)
  • ApiConnectionException - Network/connection errors
• Rich exception context with HTTP status, headers, request ID

Collections & Pagination

• Collection class implementing Iterator and Countable interfaces
• Easy iteration with native foreach loops
• Pagination metadata (total, offset, limit)
• hasMore() helper for checking additional pages

Developer Experience

• Modern PHP 7.4+ with type hints throughout
• PSR-4 autoloading
• PSR-12 coding standards compliant
• Zero dependencies (only PHP extensions: cURL, JSON, mbstring)
• 15 working examples covering all features
• Comprehensive documentation:
  • README.md with quick start and examples
  • API_REFERENCE.md with complete method documentation
  • SPANISH_INVOICING.md with Verifactu compliance guide
  • TAX_REPORTS.md with tax reporting details
  • DEVELOPER_GUIDE.md with setup and best practices
• Environment configuration support via .env files
• Composer scripts for testing (test, test:all, test:coverage)

Upgrade from 0.9.x

No breaking changes. Update your composer.json:

{
  "require": {
    "b2brouter/b2brouter-php": "^1.0"
  }
}

Then run: composer update b2brouter/b2brouter-php

All 0.9.x code is fully compatible with 1.0.0.

Requirements

• PHP 7.4 or higher
• cURL extension
• JSON extension
• mbstring extension

Support

• Documentation: https://developer.b2brouter.net
• Email: [email protected]
• Issues: https://github.com/B2Brouter/b2brouter-php/issues

First Stable Release

This is the first stable release of the B2BRouter PHP SDK. The SDK is production-ready with semantic versioning guarantees. All future 1.x releases will maintain backward compatibility.

Features

Invoice Management

• Complete CRUD operations (create, retrieve, update, delete, list)
• Domain-specific operations:
  • validate() - Validate invoice structure before sending
  • send() - Send invoice to customer and generate tax reports
  • markAs() - Update invoice state (new, sent, paid, etc.)
  • acknowledge() - Mark received invoices as acknowledged
  • import() - Import invoices from external sources
• Multi-format document downloads:
  • downloadAs() - Download in any supported format
  • downloadPdf() - Convenience method for PDF downloads
  • Support for PDF (pdf.invoice)
  • Support for Spanish Facturae XML (xml.facturae.3.2.2)
  • Support for UBL BIS3 (xml.ubl.invoice.bis3)
  • Additional formats based on account configuration

Tax Reports

• Full CRUD operations (create, retrieve, update, delete, list)
• Multi-jurisdiction support:
  • Spanish Verifactu (Law 11/2021 Anti-Fraud compliance)
  • TicketBAI (Basque Country: Álava, Bizkaia, Gipuzkoa)
  • Italian SDI (Sistema di Interscambio)
  • Polish KSeF (National e-Invoicing System)
  • Saudi Zatca (e-invoicing)
• Automatic tax report generation on invoice send
• QR code generation for invoice verification
• Digital fingerprint and hash chain computation
• Corrections (subsanación) via update()
• Annullations (anulación) via delete()
• XML download support

Tax Report Settings

• Configure tax authority settings (Verifactu, TicketBAI, etc.)
• Full CRUD operations
• Auto-generation and auto-send configuration
• Special regime and exemption settings

HTTP Client & Error Handling

• Automatic retry logic with exponential backoff (configurable, default: 3 retries)
• Configurable timeouts (request: 80s, connection: 30s)
• Custom HTTP client support via ClientInterface
• Comprehensive exception hierarchy:
  • ApiErrorException - Base exception for all API errors
  • AuthenticationException - Invalid API key (401)
  • PermissionException - Insufficient permissions (403)
  • ResourceNotFoundException - Resource not found (404)
  • InvalidRequestException - Validation errors (400, 422)
  • ApiConnectionException - Network/connection errors
• Rich exception context with HTTP status, headers, request ID

Collections & Pagination

• Collection class implementing Iterator and Countable interfaces
• Easy iteration with native foreach loops
• Pagination metadata (total, offset, limit)
• hasMore() helper for checking additional pages

Developer Experience

• Modern PHP 7.4+ with type hints throughout
• PSR-4 autoloading
• PSR-12 coding standards compliant
• Zero dependencies (only PHP extensions: cURL, JSON, mbstring)
• 15 working examples covering all features
• Comprehensive documentation:
  • README.md with quick start and examples
  • API_REFERENCE.md with complete method documentation
  • SPANISH_INVOICING.md with Verifactu compliance guide
  • TAX_REPORTS.md with tax reporting details
  • DEVELOPER_GUIDE.md with setup and best practices
• Environment configuration support via .env files
• Composer scripts for testing (test, test:all, test:coverage)

Upgrade from 0.9.x

No breaking changes. Update your composer.json:

{
  "require": {
    "b2brouter/b2brouter-php": "^1.0"
  }
}

Then run: composer update b2brouter/b2brouter-php

All 0.9.x code is fully compatible with 1.0.0.

Requirements

• PHP 7.4 or higher
• cURL extension
• JSON extension
• mbstring extension

Support

• Documentation: https://developer.b2brouter.net
• Email: [email protected]
• Issues: https://github.com/B2Brouter/b2brouter-php/issues

Release v0.9.1 - Invoice document download support

Added

• Invoice document download support - Download invoices in various formats
  • InvoiceService::downloadAs($id, $documentType, $params) - Download invoice in any supported format
  • InvoiceService::downloadPdf($id, $params) - Convenience method for PDF downloads
  • Support for PDF format (pdf.invoice)
  • Support for XML formats (Facturae xml.facturae.3.2.2, UBL BIS3 xml.ubl.invoice.bis3, and more)
  • Optional query parameters for disposition and custom filename
• Binary response handling - New ApiResource::requestBinary() method for non-JSON responses
  • Automatic Accept header determination based on document type
  • Proper error handling for binary endpoints (still parses JSON errors)
  • Returns raw binary data for PDF/XML downloads

Documentation

• Added invoice document download examples to README
• Updated PHPDoc with comprehensive documentation for new methods
• Added unit tests for PDF, Facturae, and UBL downloads
• Documented available document type codes
• Added examples/download_invoice_documents.php - Complete example showing invoice creation and downloading in PDF and UBL BIS3 formats

Technical Details

• Binary downloads return raw string data (PDF bytes, XML text, etc.)
• Accept headers automatically set: application/pdf for PDF formats, application/xml for XML formats
• All existing exception types work with download methods (404, 401, 403, etc.)
• Automatic retry logic applies to document downloads

Core SDK Features

• Invoice CRUD operations (create, retrieve, update, delete, list)
• Invoice domain-specific operations:
  • validate() - Validate invoice structure before sending
  • send() - Send invoice to customer and/or tax authority
  • markAs() - Update invoice state (sent, paid, etc.)
  • acknowledge() - Mark received invoices as acknowledged
  • import() - Bulk import invoices
• Tax report management:
  • retrieve() - Get tax report details
  • all() - List tax reports with filtering
  • download() - Download XML tax report
  • create(), update(), delete() - CRUD operations
• Tax report settings configuration (CRUD operations)
• Collection-based pagination with Iterator and Countable interfaces

Tax Compliance

• Spanish Verifactu compliance support (Law 11/2021 Anti-Fraud)
• TicketBAI tax reporting (Basque Country: Álava, Bizkaia, Gipuzkoa)
• Support for multiple tax jurisdictions:
  • Spain (Verifactu)
  • Basque Country (TicketBAI)
  • Italy (SDI)
  • Poland (KSeF)
  • Saudi Arabia (Zatca)
• Automatic tax report generation on invoice send
• QR code generation for invoice verification
• Digital fingerprint and hash chain computation

Error Handling

• Comprehensive exception hierarchy:
  • ApiErrorException - Base exception for all API errors
  • AuthenticationException - Invalid API key (401)
  • PermissionException - Insufficient permissions (403)
  • ResourceNotFoundException - Resource not found (404)
  • InvalidRequestException - Validation errors (400, 422)
  • ApiConnectionException - Network/connection errors
• Rich exception context:
  • HTTP status code
  • Raw HTTP body
  • Parsed JSON response
  • HTTP headers
  • Request ID for support tracking

HTTP Client

• Automatic retry logic with exponential backoff (default: 3 retries)
• Configurable timeouts (request: 80s, connection: 30s)
• Custom HTTP client support via ClientInterface
• cURL-based default implementation
• Mock HTTP client for testing

Testing & Quality

• Comprehensive test suite with PHPUnit 9.x
• Unit tests for all major components:
  • B2BRouterClientTest
  • InvoiceServiceTest
  • TaxReportServiceTest
  • TaxReportSettingServiceTest
  • CollectionTest
  • ExceptionTest
  • HttpClientTest
• Mock HTTP client for isolated testing
• Test grouping (unit, integration, external)
• GitHub Actions CI/CD pipeline:
  • Automated testing on push/PR
  • Composer validation
  • Dependency caching
• Static analysis with PHPStan
• Code standards checking with PHP_CodeSniffer

Documentation

• Comprehensive README.md with:
  • Quick start guide
  • Configuration options
  • Core concepts (Invoices, Tax Reports, Spanish Invoicing)
  • Pagination examples
  • Error handling examples
• Specialized guides:
  • DEVELOPER_GUIDE.md - Setup, IDE configuration, testing, best practices
  • SPANISH_INVOICING.md - Verifactu compliance guide
  • TAX_REPORTS.md - Tax reporting system documentation
• 14 working examples:
  • create_simple_invoice.php
  • create_detailed_invoice.php
  • list_invoices.php
  • paginate_all_invoices.php
  • update_invoice.php
  • invoice_workflow.php
  • invoices.php
  • invoicing_in_spain_with_verifactu.php
  • tax_reports.php
  • verifactu_tax_report.php
  • ticketbai_tax_report.php
  • And more...
• Environment configuration support (.env.example)

Developer Experience

• Modern PHP 7.4+ with type hints throughout
• PSR-4 autoloading
• Composer scripts for testing:
  • composer test - Unit tests (fast)
  • composer test:all - All tests including integration
  • composer test:external - External integration tests
  • composer test:coverage - HTML coverage report
• Clean service-based API design
• Lazy service loading (services created on first access)
• Iterator support for collections (native foreach loops)

Requirements

• PHP 7.4 or higher
• cURL extension
• JSON extension
• mbstring extension

Notes

This is a beta release (v0.9.x) intended for early adopters and development/testing purposes.

Stability:

• ✅ The SDK is feature-complete and well-tested
• ✅ Suitable for WooCommerce plugin development and testing
• ⚠️ API may undergo minor refinements before v1.0.0
• ⚠️ Production use should pin to specific version: "b2brouter/b2brouter-php": "0.9.0"

What's Coming in v1.0.0:

• Potential minor API refinements based on early adopter feedback

Upgrade Path:

• Beta users: ^0.9.0 (allows 0.9.1, 0.9.2, etc.)
• After v1.0.0: ^1.0 (semantic versioning guarantees)

Added

Core SDK Features

• Invoice CRUD operations (create, retrieve, update, delete, list)
• Invoice domain-specific operations:
  • validate() - Validate invoice structure before sending
  • send() - Send invoice to customer and/or tax authority
  • markAs() - Update invoice state (sent, paid, etc.)
  • acknowledge() - Mark received invoices as acknowledged
  • import() - Bulk import invoices
• Tax report management:
  • retrieve() - Get tax report details
  • all() - List tax reports with filtering
  • download() - Download XML tax report
  • create(), update(), delete() - CRUD operations
• Tax report settings configuration (CRUD operations)
• Collection-based pagination with Iterator and Countable interfaces

Tax Compliance

• Spanish Verifactu compliance support (Law 11/2021 Anti-Fraud)
• TicketBAI tax reporting (Basque Country: Álava, Bizkaia, Gipuzkoa)
• Support for multiple tax jurisdictions:
  • Spain (Verifactu)
  • Basque Country (TicketBAI)
  • Italy (SDI)
  • Poland (KSeF)
  • Saudi Arabia (Zatca)
• Automatic tax report generation on invoice send
• QR code generation for invoice verification
• Digital fingerprint and hash chain computation

Error Handling

• Comprehensive exception hierarchy:
  • ApiErrorException - Base exception for all API errors
  • AuthenticationException - Invalid API key (401)
  • PermissionException - Insufficient permissions (403)
  • ResourceNotFoundException - Resource not found (404)
  • InvalidRequestException - Validation errors (400, 422)
  • ApiConnectionException - Network/connection errors
• Rich exception context:
  • HTTP status code
  • Raw HTTP body
  • Parsed JSON response
  • HTTP headers
  • Request ID for support tracking

HTTP Client

• Automatic retry logic with exponential backoff (default: 3 retries)
• Configurable timeouts (request: 80s, connection: 30s)
• Custom HTTP client support via ClientInterface
• cURL-based default implementation
• Mock HTTP client for testing

Testing & Quality

• Comprehensive test suite with PHPUnit 9.x
• Unit tests for all major components:
  • B2BRouterClientTest
  • InvoiceServiceTest
  • TaxReportServiceTest
  • TaxReportSettingServiceTest
  • CollectionTest
  • ExceptionTest
  • HttpClientTest
• Mock HTTP client for isolated testing
• Test grouping (unit, integration, external)
• GitHub Actions CI/CD pipeline:
  • Automated testing on push/PR
  • Composer validation
  • Dependency caching
• Static analysis with PHPStan
• Code standards checking with PHP_CodeSniffer

Documentation

• Comprehensive README.md with:
  • Quick start guide
  • Configuration options
  • Core concepts (Invoices, Tax Reports, Spanish Invoicing)
  • Pagination examples
  • Error handling examples
• Specialized guides:
  • DEVELOPER_GUIDE.md - Setup, IDE configuration, testing, best practices
  • SPANISH_INVOICING.md - Verifactu compliance guide
  • TAX_REPORTS.md - Tax reporting system documentation
• 14 working examples:
  • create_simple_invoice.php
  • create_detailed_invoice.php
  • list_invoices.php
  • paginate_all_invoices.php
  • update_invoice.php
  • invoice_workflow.php
  • invoices.php
  • invoicing_in_spain_with_verifactu.php
  • tax_reports.php
  • verifactu_tax_report.php
  • ticketbai_tax_report.php
  • And more...
• Environment configuration support (.env.example)

Developer Experience

• Modern PHP 7.4+ with type hints throughout
• PSR-4 autoloading
• Composer scripts for testing:
  • composer test - Unit tests (fast)
  • composer test:all - All tests including integration
  • composer test:external - External integration tests
  • composer test:coverage - HTML coverage report
• Clean service-based API design
• Lazy service loading (services created on first access)
• Iterator support for collections (native foreach loops)

Requirements

• PHP 7.4 or higher
• cURL extension
• JSON extension
• mbstring extension

Notes

This is a beta release (v0.9.x) intended for early adopters and development/testing purposes.

Stability:

• ✅ The SDK is feature-complete and well-tested
• ✅ Suitable for WooCommerce plugin development and testing
• ⚠️ API may undergo minor refinements before v1.0.0
• ⚠️ Production use should pin to specific version: "b2brouter/b2brouter-php": "0.9.0"

What's Coming in v1.0.0:

• Potential minor API refinements based on early adopter feedback

Upgrade Path:

• Beta users: ^0.9.0 (allows 0.9.1, 0.9.2, etc.)
• After v1.0.0: ^1.0 (semantic versioning guarantees)

Support

• Documentation: https://developer.b2brouter.net
• Email: [email protected]
• Issues: https://github.com/B2Brouter/b2brouter-php/issues