Laravel E-Invoicing
The Laravel bridge for intragile/php-einvoicing: send and receive EN 16931 invoices over Peppol from a Laravel application.
composer require intragile/laravel-einvoicing
The Laravel bridge for intragile/php-einvoicing:
send and receive EN 16931 invoices over Peppol from a Laravel application.
Status: version 1.0.0, released 2026-11-16. What is verified, and how, is in What is verified and docs/VERIFICATION.md.
- Configured transports. Named connections in
config/einvoicing.php; the built-in driversrecommand,b2brouterandeinvoicebetalk to the Recommand, B2Brouter and e-invoice.be access points, andEInvoicing::extend()adds your own. Storecove is planned; see Drivers. - Validation before every send, on by default: Peppol BIS documents with the official rules, installed by one artisan command, and XRechnung documents with the KoSIT rules.
- Queued sending with a guarded state machine. A send is claimed with a conditional update, so a duplicate or repeated job never sends twice. A send whose outcome is unknown is never resent automatically: it waits for an operator.
- Delivery status by polling and by webhook, with events at every step.
- Inbound documents from webhooks or polling: fetched, stored, announced once, and only then acknowledged at the access point.
- Signed webhooks, verified against the request exactly as received, without the
webmiddleware group. EInvoicing::fake()for your tests, andeinvoicing:doctorto check an installation.
Live testing, per driver. Recommand is live-tested on the Peppol test network, through this package as well. B2Brouter and e-invoice.be are live-tested against the provider sandbox (simulated network). Everything else is tested offline; see Drivers and What is verified.
Requirements
- PHP 8.3+ with
dom,libxml,mbstring - Laravel 12 or 13
- A queue worker for production use (see Queues)
Packages
This package is the engine's Laravel bridge. Three thin entry packages carry the names people search for; each is a Composer metapackage (no code) that requires this package, and where the use case needs one, its rule package:
| Package | Use it for | Requires |
|---|---|---|
intragile/laravel-xrechnung |
XRechnung 3.0 for Germany | this package, intragile/einvoicing-rules-xrechnung |
intragile/laravel-zugferd |
ZUGFeRD 2.x and Factur-X 1.0 hybrid PDF invoices | this package, intragile/einvoicing-rules-facturx |
intragile/laravel-peppol |
Sending and receiving over Peppol | this package |
The engine itself is intragile/php-einvoicing; the rule packages are intragile/einvoicing-rules-en16931, intragile/einvoicing-rules-xrechnung and intragile/einvoicing-rules-facturx.
Drivers
Recommand, B2Brouter and e-invoice.be are the available drivers; Storecove is planned.
| Driver | Peppol test network | Provider sandbox | Status |
|---|---|---|---|
Recommand (recommand) |
yes (playground team with useTestNetwork) |
yes | live-tested on the Peppol test network |
B2Brouter (b2brouter) |
no (the sandbox simulates the network) | yes, free | live-tested against the provider sandbox (simulated network) |
e-invoice.be (einvoicebe) |
no (the sandbox simulates the network) | yes, free | live-tested against the provider sandbox (simulated network) |
| Storecove | unverified | on request (sales contact) | planned |
A test against a provider sandbox that simulates the network proves the provider's API contract, not delivery over Peppol; only Recommand can reach the Peppol test network. e-invoice.be sends Peppol BIS Billing 3.0 UBL only. B2Brouter renders the document it transmits from its own invoice model, so the delivered bytes may differ from your XML. Webhook signatures are verified offline against each provider's documented scheme (e-invoice.be also against its published test vector); webhooks were not live-tested. What each driver sends, its status mapping, inbound behaviour and webhook details are in the core's TRANSPORT.md.
Installation
composer require intragile/laravel-einvoicing
php artisan vendor:publish --tag=einvoicing-config # optional: config/einvoicing.php
php artisan einvoicing:install-rules # the Peppol BIS validation rules
php artisan migrate # two tables: einvoicing_outbound_documents, einvoicing_inbound_documents
php artisan einvoicing:doctor # checks everything below
Before the first release neither this package nor
intragile/php-einvoicingis on Packagist. Until then, clone both repositories next to your application and add them as path repositories in itscomposer.json:"repositories": [ { "type": "path", "url": "../php-einvoicing", "options": { "versions": { "intragile/php-einvoicing": "1.0.0" } } }, { "type": "path", "url": "../php-einvoicing/packages/rules-en16931", "options": { "versions": { "intragile/einvoicing-rules-en16931": "1.0.0" } } }, { "type": "path", "url": "../php-einvoicing/packages/rules-xrechnung", "options": { "versions": { "intragile/einvoicing-rules-xrechnung": "1.0.0" } } }, { "type": "path", "url": "../php-einvoicing/packages/rules-facturx", "options": { "versions": { "intragile/einvoicing-rules-facturx": "1.0.0" } } }, { "type": "path", "url": "../laravel-einvoicing", "options": { "versions": { "intragile/laravel-einvoicing": "1.0.0" } } } ]and require
"intragile/laravel-einvoicing": "^1.0". Theversionsoption gives each path package the version the constraints between the packages expect.
The migration is loaded from the package. To keep a copy in your application, publish it with
php artisan vendor:publish --tag=einvoicing-migrations.
einvoicing:install-rules downloads the pinned Peppol BIS Billing sources and compiles them
into storage/einvoicing/peppol-rules (or EINVOICING_RULES_DIR). Without network access,
pass a folder with the downloaded .sch files: --from=DIR. OpenPeppol publishes no licence
for its rules, so they are installed on your machine, never shipped with the package.
Configuration
EINVOICING_TRANSPORT=recommand # the default transport
RECOMMAND_API_KEY_ID=key_...
RECOMMAND_API_SECRET=secret_...
RECOMMAND_COMPANY_ID=c_...
RECOMMAND_WEBHOOK_SECRET=... # only when you receive webhooks
# RECOMMAND_BASE_URL=https://app.recommand.eu
# EINVOICING_RULES_DIR=/path/to/peppol-rules
# EINVOICING_QUEUE_CONNECTION=redis
# EINVOICING_QUEUE=einvoicing
Each access point is one entry in einvoicing.transports, with one of the built-in drivers
recommand, b2brouter or einvoicebe. The published config file holds the recommand entry;
the other two are in it commented out, because einvoicing:doctor checks every listed transport.
Uncomment the ones you use and point EINVOICING_TRANSPORT at the default one.
B2Brouter (driver b2brouter):
// config/einvoicing.php
return [
// ...
'transports' => [
'b2brouter' => [
'driver' => 'b2brouter',
'api_key' => env('B2BROUTER_API_KEY'),
'account_id' => env('B2BROUTER_ACCOUNT_ID'),
'base_url' => env('B2BROUTER_BASE_URL', 'https://api.b2brouter.net'),
'document_type_codes' => [],
'webhook_secret' => env('B2BROUTER_WEBHOOK_SECRET'),
'webhook_tolerance' => null,
],
],
];
B2BROUTER_API_KEY=... # a key starting with test_ goes to the sandbox
B2BROUTER_ACCOUNT_ID=12345 # the account that sends and receives
B2BROUTER_WEBHOOK_SECRET=... # only when you receive webhooks
# B2BROUTER_BASE_URL=https://api.b2brouter.net
B2Brouter sends a key starting with test_ to its sandbox, which never reaches the Peppol
network; the doctor shows a warning for it. account_id is a positive whole number.
document_type_codes maps further Peppol document type identifiers to B2Brouter document type
codes; Peppol BIS Billing 3.0 invoices and credit notes need none. webhook_tolerance, in
seconds, refuses notifications whose signed timestamp is further from now; it is off (null) by
default, because B2Brouter retries a notification for about a week.
e-invoice.be (driver einvoicebe):
// config/einvoicing.php
return [
// ...
'transports' => [
'einvoicebe' => [
'driver' => 'einvoicebe',
'api_key' => env('EINVOICEBE_API_KEY'),
'base_url' => env('EINVOICEBE_BASE_URL', 'https://api.e-invoice.be'),
'tenant_id' => env('EINVOICEBE_TENANT_ID'),
'inbound_lookback_days' => 7,
'inbound_max_pages' => 10,
'webhook_secret' => env('EINVOICEBE_WEBHOOK_SECRET'),
],
],
];
EINVOICEBE_API_KEY=...
EINVOICEBE_WEBHOOK_SECRET=... # only when you receive webhooks
# EINVOICEBE_TENANT_ID=... # drops webhook notifications of other tenants
# EINVOICEBE_BASE_URL=https://api.e-invoice.be
e-invoice.be has no call to acknowledge a received document, so acknowledgement is local only:
a document stays in its inbox and each poll lists the last inbound_lookback_days days (1 to
365), at most inbound_max_pages pages of 100 (1 to 100); the package stores and fetches each
document once. With tenant_id set, webhook notifications naming another tenant are ignored;
without it (or with an empty EINVOICEBE_TENANT_ID= line), every signed notification is
applied, and einvoicing:doctor shows an info row for that case when webhooks are on.
The rest of config/einvoicing.php: HTTP timeouts and the response size cap (http),
validation on or off (validation.enabled), send retries (sending.max_attempts,
sending.backoff), status polling (status.poll, status.delays, status.max_attempts),
inbound acknowledgement and the inbound attempt budget (inbound.acknowledge,
inbound.max_fetch_attempts) and the webhook route (webhooks). In every list of delays the
last value repeats. Numbers may be given as numeric strings, as environment variables deliver
them; anything else is refused with an error that names the key. webhooks.enabled also takes
the strings "true"/"false" and "1"/"0". API keys, and the Recommand API key id and
secret, must each be at least 8 characters long.
A transport is built on first use, so missing credentials never break application boot. Secrets never appear in exception messages, doctor output, events or queued job payloads; jobs carry only a row id.
Sending
use IntrAgile\EInvoicing\Laravel\Facades\EInvoicing;
$message = EInvoicing::send($invoice, reference: 'INV-2026-0001');
send() accepts a core Invoice model, UBL or CII XML as a string, or an OutboundDocument. The
routing (sender, receiver, process) is read from the invoice itself. It stores the document as
an OutboundMessage in state queued and dispatches the SendDocument job after the open
database transaction, if any, commits. The optional third argument names a transport other than
the default.
Give the invoice the process control of what you send. Only these documents are sent over Peppol, chosen by the exact pair of document element and specification identifier (BT-24):
- Peppol BIS Billing 3.0: a UBL Invoice or CreditNote;
- XRechnung 3.0: a UBL Invoice, UBL CreditNote or CII invoice;
- XRechnung 3.0 Extension: a UBL Invoice or CII invoice.
The XRechnung CVD and the deprecated XRechnung UBL Credit Note Extension are refused. The core's
writers use urn:cen.eu:en16931:2017 for an invoice without process control, which is plain
EN 16931 and none of these, so set it:
use IntrAgile\EInvoicing\Model\ProcessControl;
use IntrAgile\EInvoicing\Syntax\Syntax;
use IntrAgile\EInvoicing\Syntax\XRechnung;
use IntrAgile\EInvoicing\Transport\OutboundDocument;
use IntrAgile\EInvoicing\Transport\Peppol\PeppolBis3;
// Peppol BIS Billing 3.0
new Invoice(
// ...
processControl: new ProcessControl(
'urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0',
PeppolBis3::PROCESS,
),
);
// XRechnung 3.0, sent as UBL by send($invoice), or as CII:
$invoice = new Invoice(/* ... */ processControl: XRechnung::processControl());
EInvoicing::send(OutboundDocument::fromInvoice($invoice, syntax: Syntax::Cii));
Any other document is refused by send() itself: it throws UnsupportedDocument with the reason
and stores nothing. This holds with validation off as well.
Validation
With validation on (the default), the SendDocument job validates the document before it claims
the row: Peppol BIS documents with the installed Peppol rules, XRechnung documents with the KoSIT
rules of intragile/einvoicing-rules-xrechnung, which this package requires. An invalid document
ends as failed with category validation and attempts 0, and nothing leaves your server. A
missing rule set leaves the row queued and the job fails with the reason, so install the rules
and queue it again with einvoicing:resolve ID --resend.
To check documents with your own rules, bind a validator in the container; the job and
EInvoicing::transport() then use it instead of the Peppol rules:
use IntrAgile\EInvoicing\Validation\DocumentValidator;
$this->app->singleton(DocumentValidator::class, fn () => new MyValidator());
The default validator loads the Peppol BIS rules when it is built, even if you send only
XRechnung documents, so run einvoicing:install-rules in that case too. A bound
DocumentValidator is ignored when validation.enabled is false. A transport already built by
EInvoicing::transport() keeps the validator it was built with, so bind yours before the first
call, for example in a service provider's register().
EInvoicing::transport() returns a transport that validates every document;
EInvoicing::transport($name, validated: false) returns the bare driver. To validate a document
yourself, for example a received one, EInvoicing::xrechnung()->validate($xml) and
EInvoicing::facturx()->validate($xml) return a core ValidationReport.
States
send() ─► queued ─► sending ─► pending ─► delivered
▲ │ └─────► failed
│ ├─► failed
└─retry───┤
└─► unconfirmed ─► (operator) einvoicing:resolve
| State | Meaning | What to do |
|---|---|---|
queued |
Stored, waiting for a send job | Nothing; a worker picks it up |
sending |
Claimed by a job; the request may be in flight | Nothing; it moves on, or becomes unconfirmed when the claim expires |
pending |
Accepted by the access point; delivery to the receiver is not confirmed yet | Nothing; status polls and webhooks finish it |
delivered |
Delivered to the receiver (terminal) | |
failed |
Definitely not delivered (terminal); see failure_category, failure_message, provider_code |
Fix the cause, then resend if needed: einvoicing:resolve ID --resend |
unconfirmed |
The outcome is not known: the access point may have accepted the document | Check the access point, then einvoicing:resolve (below) |
A send failure is handled by what it proves:
- Definitely not accepted (validation error, rejected document, unreachable recipient,
wrong credentials):
failed. - Safe to retry (
TransportUnavailable,RateLimited): back toqueued, sent again afterRetry-Afterorsending.backoff, up tosending.max_attempts, thenfailedwith categorytransport. - Anything else (no answer, a 5xx other than 503, an unreadable 200, any unexpected
exception):
unconfirmed. It is never sent again automatically, because sending again might deliver the invoice twice.
Send jobs have $tries = 1: the queue never repeats a send. A worker that dies in the middle of
a send leaves the row sending; a delayed ExpireSendingClaim job then moves it to
unconfirmed.
Resolving an unconfirmed send
Look the document up in the access point, by receiver and invoice number, then:
- Recommand: the company's documents in the dashboard or the API.
- B2Brouter: the account's invoices; the document id is the invoice id (digits). Per B2Brouter's API documentation, a resend of an invoice number the account already holds is refused as a duplicate.
- e-invoice.be: the drafts and sent documents; the document id is
doc-…. A document still inDRAFTwas uploaded but not sent: either send it at e-invoice.be and use--sent, or use--resend, which uploads a new draft.
php artisan einvoicing:resolve 42 --sent=<document-id> # it was accepted: pending, polled from here on
php artisan einvoicing:resolve 42 --resend # it was not: queue it again (asks for confirmation)
php artisan einvoicing:resolve 42 --resend --force # the same without the question, e.g. in scripts
--resend also accepts a failed or queued row. It never resets the attempt counter, so a
row that failed after sending.max_attempts gets one new attempt, without backoff; run it
again if that fails too. A row still sending longer than the send job's timeout plus 30
seconds is treated as abandoned and can be resolved like unconfirmed (relevant on a sync
connection, which cannot schedule the claim expiry). That assumes the worker that held it was
killed at its timeout, which needs pcntl (see Queues).
Events
| Event | When |
|---|---|
DocumentSent |
the transport accepted the document, whatever its delivery state |
DocumentDelivered |
the document reached the receiver |
DocumentFailed |
the document was definitely not delivered |
DocumentUnconfirmed |
the outcome of the send is unknown; an operator must resolve it |
DocumentReceived |
an inbound document is stored ($event->message->xml) |
WebhookReceived |
a signed webhook for this provider account was verified, before it is applied (repeated deliveries fire it again; $event->event->deduplicationKey identifies one delivery) |
All are in IntrAgile\EInvoicing\Laravel\Events; the document events carry the
OutboundMessage or InboundMessage model as $message.
use IntrAgile\EInvoicing\Laravel\Events\DocumentDelivered;
Event::listen(function (DocumentDelivered $event) {
Order::where('invoice_number', $event->message->reference)->update(['einvoice' => 'delivered']);
});
Delivery status is polled after status.delays while a document is pending, up to
status.max_attempts checks; then polling stops and the row stays pending until a webhook
finishes it. A status check that throws something other than a transport error stops polling
for that document for good; the failed job shows why.
Receiving
Inbound documents arrive by webhook or by polling; both end in the same pipeline. A row in
einvoicing_inbound_documents is notified, then fetched (the XML is stored), then
acknowledged (the access point was told). DocumentReceived fires once per document, after
the database commit, and the acknowledgement follows it.
use IntrAgile\EInvoicing\Laravel\Events\DocumentReceived;
use IntrAgile\EInvoicing\Syntax\Ubl\UblReader;
Event::listen(function (DocumentReceived $event) {
$invoice = (new UblReader)->read($event->message->xml)->invoice;
// ...
});
Delivery of DocumentReceived is at most once. If the process dies between the commit and
the event, or a listener throws, the document is still acknowledged and the event is not fired
again. Make listeners that must not miss a document queued (ShouldQueue), and reconcile from
the table: every stored document is a fetched or acknowledged row with its XML.
A document that cannot be read (a DOCTYPE, broken XML) stays notified with last_error and
is not acknowledged. A fetch or acknowledgement that failed with a retryable error (and an
acknowledgement whose outcome is unknown) is retried after sending.backoff, up to
sending.max_attempts; any other fetch error, and anything left after the last attempt, waits
for the next poll, which queues one more attempt each time the access point still lists the
document.
Every failed fetch and acknowledgement counts against one budget per document,
inbound.max_fetch_attempts (default 10, from 1 to 65535). A document that has used it up is
no longer fetched or acknowledged automatically: the poll skips it and reports it as capped,
and einvoicing:doctor warns about it. Look at its last_error, fix the cause (often at the
access point), then run php artisan einvoicing:poll-inbound --include-capped, which gives each
capped document still listed by the access point exactly one more attempt.
Polling
// routes/console.php
use Illuminate\Support\Facades\Schedule;
Schedule::command('einvoicing:poll-inbound')->everyFiveMinutes()->withoutOverlapping();
// one line per transport when you have several:
// Schedule::command('einvoicing:poll-inbound --transport=other')->everyFiveMinutes();
Each poll records new documents and queues their intake. A document the access point still
lists whose row is stuck (notified or fetched) is queued again, so polling also recovers
documents that a failed job or a sync connection left behind. Schedule it even when you use
webhooks.
Webhooks
The package registers one route, POST /einvoicing/webhooks/{transport} (route name
einvoicing.webhook), for every transport name. It accepts notifications only for a transport
with a built-in driver (or a custom driver with a parser registered with
EInvoicing::extendWebhook()) and a webhook_secret; any other name gets 404. Setup:
-
Run
php artisan einvoicing:doctor. Thetransport <name>: webhookrow prints the full URL,https://<your app>/einvoicing/webhooks/<name>, where<name>is the transport's key ineinvoicing.transports(not the driver), when the transport has a webhook secret and webhooks are enabled; otherwise it shows a warning that says what is missing. A missing required key (Recommandcompany_id, B2Brouteraccount_id) fails theconfigrow. -
Register that URL at the provider and put the secret it gives you into the transport's
webhook_secret:Driver Register Events Secret recommanda webhook in Recommand its document events the webhook's signing secret→RECOMMAND_WEBHOOK_SECRETb2broutera web hook in B2Brouter (API POST /web_hooks)issued_invoice.state_change,received_invoice.createdthe web hook's signing secret ( signing_secretin the API; B2Brouter's guide calls itsignature_key) →B2BROUTER_WEBHOOK_SECRETeinvoicebea webhook through the e-invoice.be API ( POST /api/webhooks/)document.received,document.sent,document.sent.failedthe secretof the create response →EINVOICEBE_WEBHOOK_SECRETNotifications are matched against the configured account: Recommand
company_id, B2Brouteraccount_idand, when set, e-invoice.betenant_id. A notification that names another account is ignored; one that names no account, or arrives for a transport without a configured account, is applied. -
Nothing else: the route does not run the
webmiddleware group, so no CSRF token or session is involved, and you need no CSRF exception.
Pass the body exactly as received; each driver's parser verifies it its provider's way, with an
HMAC-SHA256 keyed with the webhook secret: Recommand over the raw body, B2Brouter over
<t>.<raw body> (the timestamp from its signature header, a dot, then the raw body), and
e-invoice.be over a canonical JSON form of the event, not over the raw body.
Answers have an empty body: 401 for a missing or wrong signature, 404 for a transport
without a webhook secret, 204 for everything else, including notifications that are ignored
(another provider account, an unknown document, a non-document event), so the access point does
not retry them. Repeated or out-of-order notifications are harmless: inbound documents are
stored once per id, and delivered and failed never change again. A notification that says a
delivery changed without saying how (e-invoice.be's document.sent.failed, or a Recommand
event of a non-Peppol channel) starts an extra status-poll chain for each pending document it
names. The extra chain shares the document's status_checks count with the regular polls, so
together they stay within status.max_attempts. Once those are used up, with status.poll off,
or on a sync queue connection, nothing is polled and the row stays pending, as after the last
regular status poll. Check such a row at the access point: einvoicing:resolve does not handle a
pending row (it resolves unconfirmed and abandoned sending rows).
B2Brouter's X-B2Brouter-Delivery-Id header, which the core offers as deduplicationKey to
your WebhookReceived listeners (the package itself does not deduplicate on it), is not
covered by B2Brouter's signature, and webhook_tolerance is off by default, so
a captured notification can be replayed later. A replay can only repeat a state B2Brouter really
reported, and delivered and failed never change again. Set webhook_tolerance if replays
matter more to you than late retries (see the core's TRANSPORT.md). Webhooks are not live-tested,
which needs a public HTTPS endpoint; their signatures are verified offline against each
provider's documented scheme (for e-invoice.be also against its published test vector).
Harden the endpoint. The route has no rate limit and no body size limit of its own. Add a
throttle in einvoicing.webhooks.middleware, for example ['throttle:120,1'], and cap the
request body in your web server (client_max_body_size in nginx, LimitRequestBody in
Apache). The prefix is einvoicing.webhooks.prefix; einvoicing.webhooks.enabled = false
removes the route.
A delivery-status webhook that arrives before the send job has stored the access point's
document id finds no row and is dropped. On a real queue the status polls catch up; on a sync
connection nothing does, so check such rows by hand.
Queues
Configure the connection and queue name with einvoicing.queue.connection and
einvoicing.queue.name (null uses the application defaults). Use a real, asynchronous
queue in production.
sync,deferredandbackgroundrun jobs in the calling process and ignore delays. On these drivers a retryable send failure goes straight tofailed(the message says retries need an asynchronous queue), status polling and the expiry of a stucksendingclaim are not scheduled, and onsyncthe fetch and acknowledgement of a webhook's document run inside the webhook request, so an error there answers the webhook with500(and, withAPP_DEBUG, a debug page). The doctor warns about these drivers.retry_aftermust be longer than the job timeouts. With the defaulthttpsettings the send job's timeout is 100 seconds and the inbound job's 170. If a job outlives the connection'sretry_after, another worker reserves it again, and since these jobs are never retried it is marked failed while the first run may still succeed. The doctor checks this.- Run workers with
pcntl(usually available in Linux CLI builds; it needs PHP built with--enable-pcntl), so a worker stops a job at its timeout.einvoicing:resolvetreats a long-sendingrow as abandoned on that assumption. The doctor checkspcntlin the PHP that runs the doctor, which is not necessarily the PHP your workers run; it warns whenpcntlis missing there, and otherwise reminds you to check the workers. - Amazon SQS accepts delays of at most 900 seconds. On an
sqsconnection every delay is capped at 900 seconds, so a longer backoff, status poll delay orRetry-Aftersimply waits less: the defaultsending.backoff(up to 1800) andstatus.delays(up to 21600) then poll and retry earlier than configured. Keep the claim expiry (send job timeout plus 30 seconds, 130 with the defaulthttpsettings) below 900, or a slow send is markedunconfirmedwhile it still runs. Amazon SQS does not allow per-message delays on FIFO queues (DelaySecondscan only be set on the queue), so retries and status polls would not be spaced out. Do not use a FIFO queue. (SeeDelaySecondsin the SendMessage API reference.) The doctor warns about delays over 900 seconds and fails on a FIFO queue, recognised by a queue name, the connection'sprefix, name andsuffix, or a full queue URL that ends in.fifo.
Custom drivers
use IntrAgile\EInvoicing\Laravel\Facades\EInvoicing;
EInvoicing::extend('my-ap', fn ($app, #[\SensitiveParameter] array $config) => new MyAccessPointTransport($config['token']));
// config/einvoicing.php
return [
// ...
'transports' => [
'other' => ['driver' => 'my-ap', 'token' => env('MY_AP_TOKEN')],
],
];
The factory returns a core Transport (and an InboundSource if it receives documents). With
validation on, its documents are validated like those of the built-in driver: by the send job
before the claim, and by the ValidatingTransport that EInvoicing::transport() wraps it in. Its
contract with this package:
- After the request has been sent, throw only
TransportExceptionsubclasses of the core, chosen by what you know:OutcomeUnknownwhen the access point may have accepted the document,TransportUnavailableorRateLimitedonly when a retry cannot duplicate it. AnInvalidArgumentExceptionis taken to mean "nothing was sent" and marks the documentfailed, so throwing it after the request risks a duplicate when the operator resends. - Exception messages must not quote credentials, in any form (encoded, inside a URL). They
are stored in
failure_messageandlast_error, and the doctor redacts only the built-in key names. Mark the factory's$configparameter#[\SensitiveParameter]so the credentials stay out of stack traces. status()must answer for the exact document id it was given: the returned status'sdocumentIdmust equal it (strict string equality). A driver that normalises ids (case, prefixes, whitespace) has its answers ignored, and the document never settles.
Transports are cached per name once built. Changing einvoicing.validation.enabled at runtime
does not rewrap a transport that was already built; set it in the configuration, not in code.
To receive webhooks for a custom driver, register its parser, a core WebhookParser:
use IntrAgile\EInvoicing\Laravel\Facades\EInvoicing;
EInvoicing::extendWebhook('my-ap', fn ($app, #[\SensitiveParameter] array $config) => new MyAccessPointWebhook($config['webhook_secret']));
The factory gets the application and the transport's configuration, whose webhook_secret is
always set (the route refuses a transport without one). The route then accepts notifications for
every transport of that driver. A custom driver has no configured account, so no notification is
ignored as foreign; check the account in your parser if you need to. A parser registered for a
built-in driver replaces the built-in one.
Testing
use IntrAgile\EInvoicing\Laravel\Facades\EInvoicing;
use IntrAgile\EInvoicing\Transport\DeliveryState;
use IntrAgile\EInvoicing\Transport\Exception\OutcomeUnknown;
use IntrAgile\EInvoicing\Transport\InboundDocument;
use IntrAgile\EInvoicing\Transport\InboundReference;
use IntrAgile\EInvoicing\Transport\OutboundDocument;
use IntrAgile\EInvoicing\Transport\SendResult;
$fake = EInvoicing::fake();
$fake->willReturn(
new SendResult('doc-1', DeliveryState::Pending), // the next send
new OutcomeUnknown('no answer'), // the one after
);
// ... run your code ...
$fake->assertSent(fn (OutboundDocument $d): bool => $d->receiver->toString() === '0208:0123456789');
$fake->sent(); // list<OutboundDocument>
$fake->receive(new InboundDocument(
new InboundReference('in-1', null, null, null, new \DateTimeImmutable),
$ublXml,
));
$this->artisan('einvoicing:poll-inbound');
$fake->acknowledged(); // ['in-1']
fake() replaces every transport with one in-memory FakeTransport and skips validation.
Without queued answers each send returns a delivered result with ids fake-1, fake-2, and
so on. With the sync queue connection in tests, the whole pipeline runs at once; refresh the
returned message to see its final state. Webhook signatures are still checked against the
configured secret while faked.
Artisan commands
| Command | Purpose |
|---|---|
einvoicing:doctor [--live] |
check transports, webhook URLs, validation rules, the installed rule packages, tables, inbound documents at the attempt cap, numeric job settings, the queue driver, pcntl, retry_after and SQS delays; --live also calls each inbox once to check the credentials |
einvoicing:install-rules [--from=DIR] |
install the Peppol BIS Billing validation rules |
einvoicing:poll-inbound [--transport=] [--include-capped] |
record waiting inbound documents and queue their intake; schedule it. --include-capped gives each document at inbound.max_fetch_attempts one more attempt |
einvoicing:resolve ID (--sent=DOCUMENT-ID | --resend) [--force] |
resolve an unconfirmed send, or queue a document again |
What is verified
| Area | How | Status |
|---|---|---|
| State machine, send policy, retries, claim expiry, status polling, inbound intake, webhooks, commands | Offline feature tests with FakeTransport and stub transports: 338 tests, 1824 assertions on PHP 8.5 with the dependencies installed here (CI runs PHP 8.3, 8.4 and 8.5 × Laravel 12 and 13) |
Run on every test run |
| Peppol validation through the manager | Opt-in group peppol-rules: installs the official rules from a local copy and sends the Peppol base example through a validating transport |
Run before releases |
| Recommand driver | Core offline tests with fixtures written from Recommand's published API description; core live group recommand-live; bridge live smoke run RecommandSmokeTest, which sends an invoice through EInvoicing::send() |
Live-tested on the Peppol test network (2026-11-15: core run and bridge run) |
| B2Brouter and e-invoice.be drivers | Core offline contract tests with fixtures written from each provider's public API reference, core live groups b2brouter-live and einvoicebe-live; manager, config, doctor and webhook routing tested here |
Live-tested against the provider sandbox (simulated network) (2026-11-15, core) |
| Webhook signatures | Offline tests against each provider's documented scheme (e-invoice.be also against its published test vector) | Verified offline; webhooks were not live-tested (needs a public HTTPS endpoint) |
The core requires brick/math ^0.14.8, which Laravel 13 also accepts.
The run results, with dates and commits, are in the core's VERIFICATION.md. Webhook signatures are verified offline against each provider's documented scheme (e-invoice.be also against its published test vector); webhooks were not live-tested.
The default test run of this package makes no network call; the live smoke run is excluded from
it (group recommand-live, testsuite Live) and refuses unless the key belongs to a Recommand
playground on the Peppol test network. The core has opt-in live groups:
recommand-live for a Recommand playground team, b2brouter-live for a B2Brouter sandbox and
einvoicebe-live for an e-invoice.be sandbox company; see its
TRANSPORT.md.
Known limits (deferred to 1.x)
- No operator command yet for a
pendingrow whose status polls are used up; check such a row at the access point (einvoicing:resolvehandlesunconfirmedand abandonedsendingrows). - e-invoice.be: the inbox is cut at the look-back on our side; the provider's
date_fromfilter is not used yet. - No guard against a second status-poll chain started by a stateless webhook; the extra chain
shares the document's
status_checksbudget, so the total stays withinstatus.max_attempts.
None of them is a correctness issue.
Versioning
The eight packages are released together with the same version number and follow Semantic
Versioning: the five engine packages, intragile/php-einvoicing, the rule packages
intragile/einvoicing-rules-en16931, intragile/einvoicing-rules-xrechnung and
intragile/einvoicing-rules-facturx, and intragile/laravel-einvoicing, and the three entry
packages intragile/laravel-xrechnung, intragile/laravel-zugferd and intragile/laravel-peppol.
Use the same minor version of each.
A rule package declares a Composer conflict with cores older than its own minor version (and
with the next major), so new rules are never installed next to an engine that cannot run them.
Development
composer test # PHPUnit
composer analyse # PHPStan, max level
composer format # Pint
EINVOICING_PEPPOL_FROM=/path/to/peppol/sch vendor/bin/phpunit --group peppol-rules
License
MIT. See LICENSE.
Developed and maintained by IntrAgile Kft.
This page is built from the README of version v1.0.0 of the package. Source on GitHubopens in a new tab