Laravel E-Invoicing
Laravel-integráció az intragile/php-einvoicing csomaghoz: EN 16931 szerinti számlák küldése és fogadása Peppol hálózaton, Laravel alkalmazásból.
composer require intragile/laravel-einvoicing
Laravel-integráció az intragile/php-einvoicing
csomaghoz: EN 16931 szerinti számlák küldése és fogadása Peppol hálózaton, Laravel
alkalmazásból.
Állapot: 1.0.0-s verzió, kiadva 2026-11-16-án. Mit és hogyan ellenőriztünk: Mi van ellenőrizve és docs/VERIFICATION.md (angolul).
- Konfigurált transportok. Névvel ellátott kapcsolatok a
config/einvoicing.php-ban; a beépítettrecommand,b2brouteréseinvoicebedriver a Recommand, a B2Brouter és az e-invoice.be access pointhoz csatlakozik, saját drivert azEInvoicing::extend()regisztrál. A Storecove tervezett; lásd: Driverek. - Validáció minden küldés előtt, alapból bekapcsolva: a Peppol BIS dokumentumokat a hivatalos szabályok ellenőrzik (egyetlen artisan parancs telepíti őket), az XRechnung dokumentumokat a KoSIT-szabályok.
- Sorba állított küldés, védett állapotgéppel. A küldést egy feltételes UPDATE foglalja le, így egy duplikált vagy megismételt job sosem küld kétszer. Ha egy küldés kimenetele nem ismert, a csomag soha nem küldi újra magától: egy operátor dönt róla.
- Kézbesítési státusz lekérdezéssel és webhookkal, minden lépésnél eseménnyel.
- Bejövő dokumentumok webhookból vagy lekérdezésből: letöltés, tárolás, egyszeri esemény, és csak ezután nyugtázás az access pointnál.
- Aláírt webhookok, pontosan a beérkezett kérésen ellenőrizve, a
webmiddleware-csoport nélkül. EInvoicing::fake()a saját tesztekhez,einvoicing:doctora telepítés ellenőrzéséhez.
Éles tesztelés driverenként. A Recommandot a Peppol teszthálózaton teszteltük élesben, e csomagon keresztül is. A B2Brouter és az e-invoice.be a szolgáltatói sandbox ellen van élesben tesztelve (szimulált hálózat). Minden más offline tesztelt; lásd: Driverek és Mi van ellenőrizve.
Követelmények
- PHP 8.3+ a
dom,libxmlésmbstringkiterjesztéssel - Laravel 12 vagy 13
- Éles használathoz queue worker (lásd: Queue)
Csomagok
Ez a csomag a motor Laravel-integrációja. Három vékony belépő csomag viseli azokat a neveket, amelyekre az emberek keresnek; mindegyik Composer metacsomag (nincs kódja), amely ezt a csomagot, és ahol a használati eset megkívánja, a szabálycsomagját is behúzza:
| Csomag | Mire való | Behúzza |
|---|---|---|
intragile/laravel-xrechnung |
XRechnung 3.0 Németországhoz | ezt a csomagot, intragile/einvoicing-rules-xrechnung |
intragile/laravel-zugferd |
ZUGFeRD 2.x és Factur-X 1.0 hibrid PDF-számlák | ezt a csomagot, intragile/einvoicing-rules-facturx |
intragile/laravel-peppol |
Küldés és fogadás Peppol hálózaton | ezt a csomagot |
Maga a motor az intragile/php-einvoicing; a szabálycsomagok: intragile/einvoicing-rules-en16931, intragile/einvoicing-rules-xrechnung és intragile/einvoicing-rules-facturx.
Driverek
Elérhető driver a Recommand, a B2Brouter és az e-invoice.be; a Storecove tervezett.
| Driver | Peppol tesztháló | Szolgáltatói sandbox | Állapot |
|---|---|---|---|
Recommand (recommand) |
igen (playground csapat useTestNetwork beállítással) |
igen | élesben tesztelve a Peppol teszthálózaton |
B2Brouter (b2brouter) |
nem (a sandbox szimulálja a hálózatot) | igen, ingyenes | élesben tesztelve a szolgáltatói sandbox ellen (szimulált hálózat) |
e-invoice.be (einvoicebe) |
nem (a sandbox szimulálja a hálózatot) | igen, ingyenes | élesben tesztelve a szolgáltatói sandbox ellen (szimulált hálózat) |
| Storecove | nem ellenőrzött | kérésre (értékesítői kapcsolat) | tervezett |
A hálózatot csak szimuláló szolgáltatói sandbox elleni teszt a szolgáltató API-szerződését igazolja, nem a Peppolon történő kézbesítést; a Peppol teszthálót csak a Recommand éri el. Az e-invoice.be csak Peppol BIS Billing 3.0 UBL-t küld. A B2Brouter a továbbított dokumentumot a saját számlamodelljéből állítja elő, így a kézbesített bájtok eltérhetnek a te XML-edtől. A webhook-aláírásokat a szolgáltatók dokumentált sémája szerint offline ellenőrizzük (az e-invoice.be-ét a közzétett tesztvektorral is); a webhookokat nem teszteltük élesben. Hogy melyik driver mit küld, hogyan képezi le az állapotokat, hogyan fogad és mit tud a webhookja, azt a core TRANSPORT.md leírása tartalmazza (angolul).
Telepítés
composer require intragile/laravel-einvoicing
php artisan vendor:publish --tag=einvoicing-config # opcionális: config/einvoicing.php
php artisan einvoicing:install-rules # a Peppol BIS validációs szabályok
php artisan migrate # két tábla: einvoicing_outbound_documents, einvoicing_inbound_documents
php artisan einvoicing:doctor # mindent ellenőriz, ami alább szerepel
Az első kiadásig sem ez a csomag, sem az
intragile/php-einvoicingnincs fent a Packagisten. Addig klónozd mindkét repót az alkalmazás mellé, és vedd fel őket path repositoryként az alkalmazáscomposer.json-jába:"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" } } } ]majd kérd be így:
"intragile/laravel-einvoicing": "^1.0". Aversionsbeállítás minden path csomagnak azt a verziót adja, amelyet a csomagok egymás közötti feltételei várnak.
A migrációt a csomag maga tölti be. Ha saját példányt szeretnél belőle az alkalmazásban:
php artisan vendor:publish --tag=einvoicing-migrations.
Az einvoicing:install-rules letölti a rögzített verziójú Peppol BIS Billing forrásokat, és a
storage/einvoicing/peppol-rules mappába (vagy az EINVOICING_RULES_DIR helyére) fordítja
őket. Hálózat nélkül add meg a letöltött .sch fájlok mappáját: --from=DIR. Az OpenPeppol nem
ad licencet a szabályaihoz, ezért azok a te gépeden települnek, a csomag nem tartalmazza őket.
Beállítás
EINVOICING_TRANSPORT=recommand # az alapértelmezett transport
RECOMMAND_API_KEY_ID=key_...
RECOMMAND_API_SECRET=secret_...
RECOMMAND_COMPANY_ID=c_...
RECOMMAND_WEBHOOK_SECRET=... # csak ha webhookot fogadsz
# RECOMMAND_BASE_URL=https://app.recommand.eu
# EINVOICING_RULES_DIR=/path/to/peppol-rules
# EINVOICING_QUEUE_CONNECTION=redis
# EINVOICING_QUEUE=einvoicing
Minden access point egy bejegyzés az einvoicing.transports listában, a beépített recommand,
b2brouter vagy einvoicebe driverek egyikével. A publikált konfigurációs fájlban a
recommand bejegyzés aktív, a másik kettő kikommentezve szerepel, mert az einvoicing:doctor
minden felsorolt transportot ellenőriz. Vedd ki a kommentből azokat, amelyeket használsz, és az
EINVOICING_TRANSPORT mutasson az alapértelmezettre.
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 test_ kezdetű kulcs a sandboxba megy
B2BROUTER_ACCOUNT_ID=12345 # a küldő és fogadó fiók
B2BROUTER_WEBHOOK_SECRET=... # csak ha webhookot fogadsz
# B2BROUTER_BASE_URL=https://api.b2brouter.net
A B2Brouter a test_ kezdetű kulcsot a sandboxába irányítja, amely sosem éri el a Peppol
hálózatot; a doctor erre figyelmeztet. Az account_id pozitív egész szám. A
document_type_codes további Peppol dokumentumtípus-azonosítókat rendel B2Brouter
dokumentumtípus-kódokhoz; a Peppol BIS Billing 3.0 számlához és jóváíráshoz nem kell semmi. A
webhook_tolerance (másodperc) elutasítja azt az értesítést, amelynek aláírt időbélyege ennél
távolabb van a jelentől; alapból ki van kapcsolva (null), mert a B2Brouter nagyjából egy hétig
próbálja újra az értesítést.
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=... # csak ha webhookot fogadsz
# EINVOICEBE_TENANT_ID=... # más tenant webhook-értesítéseit eldobja
# EINVOICEBE_BASE_URL=https://api.e-invoice.be
Az e-invoice.be-nek nincs hívása egy fogadott dokumentum nyugtázására, ezért a nyugtázás csak
helyi: a dokumentum a beérkező mappájában marad, és minden lekérdezés az utolsó
inbound_lookback_days nap (1–365) dokumentumait listázza, legfeljebb inbound_max_pages
százas oldalon (1–100); a csomag minden dokumentumot egyszer tárol és tölt le. Ha a tenant_id
be van állítva, a más tenantot megnevező webhook-értesítéseket figyelmen kívül hagyja; nélküle
minden aláírt értesítést feldolgoz (üres EINVOICEBE_TENANT_ID= sor esetén is), és az
einvoicing:doctor ilyenkor, bekapcsolt webhooknál, egy info sorban jelzi ezt.
A config/einvoicing.php további részei: HTTP-időkorlátok és a válaszméret felső határa
(http), a validáció ki- és bekapcsolása (validation.enabled), a küldés újrapróbálása
(sending.max_attempts, sending.backoff), a státusz lekérdezése (status.poll,
status.delays, status.max_attempts), a bejövő dokumentumok nyugtázása és kísérleti kerete
(inbound.acknowledge, inbound.max_fetch_attempts) és a webhook-útvonal (webhooks). A
késleltetési listák utolsó eleme ismétlődik. A számok számot tartalmazó stringként is
megadhatók, ahogy a környezeti változók adják őket; minden mást a csomag a kulcsot megnevező
hibával elutasít. A webhooks.enabled a "true"/"false" és az "1"/"0" stringet is
elfogadja. Az API-kulcsok, valamint a Recommand API-kulcs azonosítója és titka egyaránt legalább
8 karakter legyenek.
A transport első használatkor épül fel, így a hiányzó hozzáférési adatok sosem akasztják meg az alkalmazás indulását. A titkos kulcsok nem kerülnek kivételüzenetbe, a doctor kimenetébe, eseménybe vagy sorba állított job adatai közé; a jobok csak a sor azonosítóját viszik magukkal.
Küldés
use IntrAgile\EInvoicing\Laravel\Facades\EInvoicing;
$message = EInvoicing::send($invoice, reference: 'INV-2026-0001');
A send() elfogad egy core Invoice modellt, UBL vagy CII XML-t stringként vagy egy
OutboundDocument-et. A címzést (küldő, címzett, folyamat) magából a számlából olvassa ki. A
dokumentumot OutboundMessage-ként, queued állapotban tárolja, a SendDocument jobot pedig
a nyitott adatbázis-tranzakció (ha van) commitja után indítja. A harmadik, opcionális
paraméterrel az alapértelmezettől eltérő transport adható meg.
Add meg a számlán annak a folyamatvezérlését (process control), amit küldesz. Peppolon csak ezek a dokumentumok mennek ki, a gyökérelem és a specifikációazonosító (BT-24) pontos párosa alapján:
- Peppol BIS Billing 3.0: UBL Invoice vagy CreditNote;
- XRechnung 3.0: UBL Invoice, UBL CreditNote vagy CII számla;
- XRechnung 3.0 Extension: UBL Invoice vagy CII számla.
Az XRechnung CVD-t és az elavult XRechnung UBL Credit Note Extensiont a csomag elutasítja. A core
írói folyamatvezérlés nélküli számlára urn:cen.eu:en16931:2017 értéket írnak: ez sima
EN 16931, egyik fenti sem, ezért állítsd be:
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, a send($invoice) UBL-ként küldi, CII-ként így:
$invoice = new Invoice(/* ... */ processControl: XRechnung::processControl());
EInvoicing::send(OutboundDocument::fromInvoice($invoice, syntax: Syntax::Cii));
Minden más dokumentumot már maga a send() elutasít: UnsupportedDocument kivételt dob az
okkal, és semmit sem tárol. Ez kikapcsolt validációnál is így van.
Validáció
Bekapcsolt validációnál (ez az alapértelmezés) a SendDocument job még a sor lefoglalása előtt
validálja a dokumentumot: a Peppol BIS dokumentumokat a telepített Peppol-szabályokkal, az
XRechnung dokumentumokat az intragile/einvoicing-rules-xrechnung KoSIT-szabályaival (ezt a
csomag függőségként behúzza). Az érvénytelen dokumentum failed állapotba kerül validation
kategóriával és 0 attempts értékkel, és semmi sem hagyja el a szervert. Ha egy szabálykészlet
hiányzik, a sor queued marad, a job pedig az okkal együtt elbukik: telepítsd a szabályokat,
majd sorold be újra az einvoicing:resolve ID --resend paranccsal.
Saját szabályokhoz köss be egy validátort a containerbe; a job és az EInvoicing::transport()
ekkor ezt használja a Peppol-szabályok helyett:
use IntrAgile\EInvoicing\Validation\DocumentValidator;
$this->app->singleton(DocumentValidator::class, fn () => new MyValidator());
Az alapértelmezett validátor létrehozáskor betölti a Peppol BIS szabályokat akkor is, ha csak
XRechnung dokumentumot küldesz, ezért az einvoicing:install-rules ilyenkor is kell. Kikapcsolt
validációnál (validation.enabled hamis) a bekötött DocumentValidator nem fut. Az
EInvoicing::transport() által már felépített transport azt a validátort tartja meg, amellyel
felépült, ezért a sajátodat az első hívás előtt kösd be, például egy service provider
register() metódusában.
Az EInvoicing::transport() minden dokumentumot validáló transportot ad vissza, az
EInvoicing::transport($name, validated: false) a nyers drivert. Ha magad validálnál egy
dokumentumot, például egy fogadottat, az EInvoicing::xrechnung()->validate($xml) és az
EInvoicing::facturx()->validate($xml) core ValidationReport-ot ad vissza.
Állapotok
send() ─► queued ─► sending ─► pending ─► delivered
▲ │ └─────► failed
│ ├─► failed
└─retry───┤
└─► unconfirmed ─► (operátor) einvoicing:resolve
| Állapot | Jelentés | Teendő |
|---|---|---|
queued |
Eltárolva, küldő jobra vár | Nincs; egy worker felveszi |
sending |
Egy job lefoglalta; a kérés úton lehet | Nincs; továbblép, vagy a foglalás lejártakor unconfirmed lesz |
pending |
Az access point átvette; a címzetthez kézbesítés még nincs visszaigazolva | Nincs; a státuszlekérdezés és a webhook lezárja |
delivered |
Kézbesítve a címzettnek (végállapot) | |
failed |
Biztosan nem lett kézbesítve (végállapot); lásd failure_category, failure_message, provider_code |
Javítsd az okot, majd szükség esetén küldd újra: einvoicing:resolve ID --resend |
unconfirmed |
A kimenetel ismeretlen: az access point lehet, hogy átvette a dokumentumot | Nézd meg az access pointban, majd einvoicing:resolve (lásd lent) |
Egy sikertelen küldést az alapján kezel a csomag, amit a hiba bizonyít:
- Biztosan nem vették át (validációs hiba, elutasított dokumentum, elérhetetlen címzett,
hibás hozzáférési adatok):
failed. - Biztonságosan újrapróbálható (
TransportUnavailable,RateLimited): visszaqueuedállapotba, és újraküldés aRetry-Aftervagy asending.backoffszerinti idő után, legfeljebbsending.max_attemptsalkalommal; utánafailed,transportkategóriával. - Minden más (nincs válasz, 503-tól eltérő 5xx, olvashatatlan 200-as válasz, bármilyen
váratlan kivétel):
unconfirmed. Ezt a csomag soha nem küldi újra magától, mert egy újabb küldés kétszer juttathatná el a számlát.
A küldő jobok $tries értéke 1: a queue sosem ismétel meg egy küldést. Ha egy worker küldés
közben leáll, a sor sending állapotban marad, majd egy késleltetett ExpireSendingClaim job
unconfirmed állapotba teszi.
Egy unconfirmed küldés rendezése
Keresd meg a dokumentumot az access pointban, címzett és számlaszám alapján, majd:
- Recommand: a cég dokumentumai a felületen vagy az API-ban.
- B2Brouter: a fiók számlái; a dokumentum-azonosító a számla azonosítója (számjegyek). A B2Brouter API-dokumentációja szerint a fiókban már meglévő számlaszám újraküldését duplikátumként elutasítja.
- e-invoice.be: a piszkozatok és az elküldött dokumentumok; a dokumentum-azonosító
doc-…. A mégDRAFTállapotú dokumentumot feltöltötték, de nem küldték el: vagy küldd el az e-invoice.be-nél, és használd a--sentkapcsolót, vagy a--resendkapcsolót, amely új piszkozatot tölt fel.
php artisan einvoicing:resolve 42 --sent=<dokumentum-azonosító> # átvették: pending, innentől lekérdezve
php artisan einvoicing:resolve 42 --resend # nem vették át: újra sorba állítja (megerősítést kér)
php artisan einvoicing:resolve 42 --resend --force # ugyanez kérdés nélkül, pl. szkriptből
A --resend failed és queued sorra is használható. A próbálkozásszámlálót sosem nullázza,
így egy sending.max_attempts után failed sor egy új próbát kap, várakozás nélkül; ha az
is elbukik, futtasd újra. Egy sor, amely a küldő job időkorlátjánál 30 másodperccel tovább
marad sending állapotban, elhagyottnak számít, és az unconfirmed sorhoz hasonlóan rendezhető
(ez sync kapcsolaton számít, ahol a foglalás lejárata nem ütemezhető). Ez csak akkor igaz, ha
a foglaló workert az időkorlátnál leállították, ehhez pedig pcntl kell (lásd:
Queue).
Események
| Esemény | Mikor |
|---|---|
DocumentSent |
a transport átvette a dokumentumot, bármi is a kézbesítési állapota |
DocumentDelivered |
a dokumentum eljutott a címzetthez |
DocumentFailed |
a dokumentum biztosan nem lett kézbesítve |
DocumentUnconfirmed |
a küldés kimenetele ismeretlen; operátornak kell rendeznie |
DocumentReceived |
egy bejövő dokumentum eltárolva ($event->message->xml) |
WebhookReceived |
egy ehhez a szolgáltatói fiókhoz tartozó, aláírt webhook ellenőrizve, még a feldolgozása előtt (ismételt kézbesítésnél újra lefut; a $event->event->deduplicationKey azonosít egy kézbesítést) |
Mind az IntrAgile\EInvoicing\Laravel\Events névtérben van; a dokumentum-események a
$message tulajdonságban adják át az OutboundMessage vagy InboundMessage modellt.
use IntrAgile\EInvoicing\Laravel\Events\DocumentDelivered;
Event::listen(function (DocumentDelivered $event) {
Order::where('invoice_number', $event->message->reference)->update(['einvoice' => 'delivered']);
});
Amíg egy dokumentum pending, a csomag a status.delays szerint lekérdezi az állapotát,
legfeljebb status.max_attempts alkalommal; utána abbahagyja, és a sor pending marad, amíg
egy webhook le nem zárja. Ha egy státuszlekérdezés transporthibán kívül mást dob, annak a
dokumentumnak a lekérdezése végleg leáll; az okot a sikertelen job mutatja.
Fogadás
A bejövő dokumentumok webhookon vagy lekérdezéssel érkeznek, és mindkét út ugyanoda fut ki. Az
einvoicing_inbound_documents tábla egy sora előbb notified, aztán fetched (az XML
eltárolva), végül acknowledged (az access point értesítve). A DocumentReceived dokumentumonként
egyszer fut le, az adatbázis-commit után, és a nyugtázás ezt követi.
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;
// ...
});
A DocumentReceived legfeljebb egyszer fut le. Ha a folyamat a commit és az esemény között
leáll, vagy egy listener kivételt dob, a dokumentum ettől még nyugtázva lesz, és az esemény nem
ismétlődik. Azokat a listenereket, amelyeknek egyetlen dokumentumot sem szabad elszalasztaniuk,
tedd sorba (ShouldQueue), és egyeztess a táblából: minden eltárolt dokumentum egy fetched
vagy acknowledged sor az XML-lel együtt.
Az olvashatatlan dokumentum (DOCTYPE, hibás XML) notified állapotban marad a last_error
oszlopban rögzített okkal, és nem kerül nyugtázásra. Az újrapróbálható hibával elbukott
letöltést vagy nyugtázást (és az ismeretlen kimenetelű nyugtázást) a csomag a sending.backoff
szerint, legfeljebb sending.max_attempts alkalommal próbálja újra; minden más letöltési hiba,
és ami az utolsó kísérlet után is megmaradt, a következő lekérdezésre vár, amely minden
alkalommal még egy kísérletet indít, amíg az access point listázza a dokumentumot.
Minden elbukott letöltés és nyugtázás dokumentumonként egyetlen keretből fogy, ez az
inbound.max_fetch_attempts (alapértelmezés 10, 1 és 65535 között). Ha egy dokumentum elhasználta,
a csomag többé nem tölti le és nem nyugtázza automatikusan: a lekérdezés átugorja és elakadtként
jelzi, az einvoicing:doctor pedig figyelmeztet rá. Nézd meg a last_error értékét, hárítsd el
az okot (gyakran az access pointnál), majd futtasd a
php artisan einvoicing:poll-inbound --include-capped parancsot, amely minden elakadt, az access
point által még listázott dokumentumnak pontosan egy újabb kísérletet ad.
Lekérdezés
// routes/console.php
use Illuminate\Support\Facades\Schedule;
Schedule::command('einvoicing:poll-inbound')->everyFiveMinutes()->withoutOverlapping();
// több transportnál transportonként egy sor:
// Schedule::command('einvoicing:poll-inbound --transport=other')->everyFiveMinutes();
Minden lekérdezés rögzíti az új dokumentumokat, és sorba állítja a feldolgozásukat. Ha az access
point még listáz egy dokumentumot, amelynek a sora elakadt (notified vagy fetched), azt is
újra sorba állítja, így a lekérdezés a sikertelen job vagy sync kapcsolat miatt elakadt
dokumentumokat is helyrehozza. Webhook mellett is érdemes ütemezni.
Webhookok
A csomag egyetlen útvonalat regisztrál minden transportnévhez:
POST /einvoicing/webhooks/{transport} (neve: einvoicing.webhook). Értesítést csak beépített
driverű (vagy EInvoicing::extendWebhook()-kal regisztrált parserű saját driverű),
webhook_secret-tel rendelkező transporthoz fogad el; minden más név 404-et kap. Beállítás:
-
Futtasd a
php artisan einvoicing:doctorparancsot. Atransport <név>: webhooksor akkor írja ki a teljes URL-t (https://<alkalmazásod>/einvoicing/webhooks/<név>, ahol a<név>a transport kulcsa azeinvoicing.transportsalatt, nem a driver neve), ha a transportnak van webhook secretje, és a webhookok be vannak kapcsolva; különben figyelmeztetést ad arról, mi hiányzik. Egy hiányzó kötelező kulcs (Recommandnálcompany_id, B2Brouternélaccount_id) miatt aconfigsor jelez hibát. -
Vedd fel ezt az URL-t a szolgáltatónál, és a tőle kapott secretet írd a transport
webhook_secretbeállításába:Driver Hol veszed fel Események Secret recommandwebhookként a Recommandban a dokumentumeseményei a webhook aláíró secret-je →RECOMMAND_WEBHOOK_SECRETb2brouterweb hookként a B2Brouterben (API: POST /web_hooks)issued_invoice.state_change,received_invoice.createda web hook aláíró secretje (az API-ban signing_secret, a B2Brouter útmutatójábansignature_key) →B2BROUTER_WEBHOOK_SECRETeinvoicebewebhookként az e-invoice.be API-n keresztül ( POST /api/webhooks/)document.received,document.sent,document.sent.faileda létrehozó válasz secretmezője →EINVOICEBE_WEBHOOK_SECRETAz értesítéseket a csomag a beállított fiókkal veti össze: Recommandnál a
company_id, B2Brouternél azaccount_id, e-invoice.be-nél atenant_id, ha meg van adva. A más fiókot megnevező értesítést figyelmen kívül hagyja; azt, amelyik nem nevez meg fiókot, vagy olyan transporthoz érkezik, amelynek nincs beállított fiókja, alkalmazza. -
Más teendő nincs: az útvonal nem futtatja a
webmiddleware-csoportot, így sem CSRF-token, sem session nem kell hozzá, és CSRF-kivételt sem kell felvenni.
A kéréstörzset pontosan úgy add át, ahogy megérkezett; minden driver parsere a saját
szolgáltatója módján ellenőrzi, a webhook secrettel kulcsolt HMAC-SHA256-tal: a Recommand a nyers
törzsön, a B2Brouter a <t>.<nyers törzs> szövegen (az aláírásfejléc időbélyege, egy pont, majd
a nyers törzs), az e-invoice.be pedig az esemény kanonikus JSON-alakján, nem a nyers törzsön.
A válaszok törzse üres: 401 hiányzó vagy hibás aláírásra, 404 webhook secret nélküli
transportra, minden másra 204, a figyelmen kívül hagyott értesítésekre is
(másik szolgáltatói fiók, ismeretlen dokumentum, nem dokumentumra vonatkozó esemény), hogy az
access point ne próbálja újra őket. Az ismételt vagy rossz sorrendben érkező értesítések
ártalmatlanok: a bejövő dokumentum azonosítónként egyszer tárolódik, a delivered és failed
állapot pedig már nem változik. Az az értesítés, amely csak annyit mond, hogy a kézbesítés
állapota változott, de azt nem, hogy mire (az e-invoice.be document.sent.failed eseménye, vagy
egy nem Peppol csatornás Recommand-esemény), egy további státuszlekérdezési láncot indít minden
általa megnevezett pending dokumentumra. Ez a lánc a rendes lekérdezésekkel közös
status_checks számlálót használ, így együtt sem lépik túl a status.max_attempts keretet. Ha a
keret elfogyott, a status.poll ki van kapcsolva, vagy sync queue-kapcsolaton, nem történik
lekérdezés, és a sor pending marad, ahogy az utolsó rendes státuszlekérdezés után is. Az ilyen
sort az access pointnál ellenőrizd: az einvoicing:resolve nem kezeli a pending sort (az
unconfirmed és az elhagyott sending sort rendezi).
A B2Brouter X-B2Brouter-Delivery-Id fejlécét, amelyet a core deduplicationKey-ként ad át a
WebhookReceived listenereidnek (maga a csomag nem szűr rá ismétlést), a B2Brouter aláírása
nem fedi le, a webhook_tolerance pedig alapból ki van kapcsolva, így egy elfogott értesítés
később újra beküldhető. Az újrajátszás csak olyan állapotot ismételhet
meg, amelyet a B2Brouter valóban jelentett, a delivered és failed állapot pedig már nem
változik. Állítsd be a webhook_tolerance értékét, ha az újrajátszás fontosabb szempont a késői
újrapróbálásoknál (lásd a core TRANSPORT.md leírását). A webhookokat élesben nem teszteltük,
ehhez nyilvános HTTPS-végpont kellene; az aláírásokat a szolgáltatók dokumentált sémája szerint
offline ellenőrizzük (az e-invoice.be-nél a közzétett tesztvektorral is).
Védd az útvonalat. Saját sebességkorlátja és törzsméret-korlátja nincs. Adj meg throttle-t az
einvoicing.webhooks.middleware beállításban, például ['throttle:120,1'], a kérés törzsének
méretét pedig korlátozd a webszerverben (nginxben client_max_body_size, Apache-ban
LimitRequestBody). Az előtag az einvoicing.webhooks.prefix; az
einvoicing.webhooks.enabled = false eltávolítja az útvonalat.
Ha egy kézbesítési státuszról szóló webhook még azelőtt érkezik, hogy a küldő job eltárolta
volna az access point dokumentum-azonosítóját, nem talál sort, és elvész. Valódi queue mellett a
státuszlekérdezés pótolja; sync kapcsolaton semmi, ezért ezeket a sorokat kézzel kell
ellenőrizni.
Queue
A kapcsolatot és a queue nevét az einvoicing.queue.connection és az einvoicing.queue.name
adja meg (null esetén az alkalmazás alapértelmezése). Élesben valódi, aszinkron queue-t
használj.
- A
sync,deferredésbackgrounddriver a hívó folyamatban futtatja a jobokat, és figyelmen kívül hagyja a késleltetést. Ezeken az újrapróbálható küldési hiba azonnalfailedlesz (az üzenet jelzi, hogy az újrapróbáláshoz aszinkron queue kell), a státuszlekérdezés és a beragadtsendingfoglalás lejárata nincs ütemezve,syncesetén pedig a webhookban jelzett dokumentum letöltése és nyugtázása magában a webhook-kérésben fut, így ott egy hiba500-as választ ad (APP_DEBUGmellett hibaoldallal). A doctor ezekre a driverekre figyelmeztet. - A
retry_afterlegyen hosszabb a jobok időkorlátjánál. Az alapértelmezetthttpbeállításokkal a küldő job időkorlátja 100, a bejövő dokumentumé 170 másodperc. Ha egy job tovább fut a kapcsolatretry_afterértékénél, egy másik worker újra lefoglalja, és mivel ezek a jobok sosem ismétlődnek, sikertelennek jelöli, miközben az első futás még sikerülhet. A doctor ezt is ellenőrzi. - A workerek fussanak
pcntl-lel (a linuxos CLI buildekben általában elérhető; a PHP-t--enable-pcntlkapcsolóval kell fordítani), hogy az időkorlátnál le tudják állítani a jobot. Azeinvoicing:resolveerre építve tekinti elhagyottnak a sokáigsendingállapotú sort. A doctor apcntl-t abban a PHP-ban ellenőrzi, amely a doctort futtatja, és ez nem feltétlenül azonos a workerek PHP-jával; ha ott hiányzik, figyelmeztet, egyébként emlékeztet, hogy a workereknél is nézd meg. - Az Amazon SQS legfeljebb 900 másodperces késleltetést fogad el.
sqskapcsolaton minden késleltetés legfeljebb 900 másodperc, így a hosszabb backoff, státuszlekérdezési késleltetés vagyRetry-Afteregyszerűen rövidebb várakozást jelent: az alapértelmezettsending.backoff(legfeljebb 1800) ésstatus.delays(legfeljebb 21600) esetén a csomag a beállítottnál korábban kérdez le és próbálkozik újra. A foglalás lejárata (a küldő job időkorlátja plusz 30 másodperc, az alapértelmezetthttpbeállításokkal 130) maradjon 900 alatt, különben a lassú küldés még futás közbenunconfirmedlesz. Az Amazon SQS FIFO queue-n nem enged üzenetenkénti késleltetést (aDelaySecondscsak a queue szintjén állítható be), így az újrapróbálások és a státuszlekérdezések nem lennének időben széthúzva. Ne használj FIFO queue-t. (Lásd aDelaySecondsleírását a SendMessage API-referenciában.) A doctor figyelmeztet a 900 másodpercnél hosszabb késleltetésekre, FIFO queue-nál pedig hibát jelez; a FIFO queue-t a.fifovégű queue-névről, a kapcsolatprefix+ név +suffixalakjáról vagy a teljes queue-URL-ről ismeri fel.
Saját driver
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')],
],
];
A factory egy core Transport-ot ad vissza (és InboundSource-ot is, ha dokumentumot fogad).
Bekapcsolt validációnál a dokumentumait a beépített driveréhez hasonlóan validálja a csomag: a
küldő job a lefoglalás előtt, és az a ValidatingTransport, amelybe az EInvoicing::transport()
csomagolja. A csomaggal szemben vállalt szerződése:
- Miután a kérés elment, csak a core
TransportExceptionalosztályait dobja, aszerint, amit tud:OutcomeUnknown-t, ha az access point átvehette a dokumentumot,TransportUnavailable-t vagyRateLimited-et csak akkor, ha az újrapróbálás nem okozhat duplikációt. AzInvalidArgumentExceptionazt jelenti a csomagnak, hogy „semmi sem ment el”, és a dokumentumotfailedállapotba teszi; ha a kérés után dobja, egy operátori újraküldés duplikációt okozhat. - A kivételüzenetek ne idézzenek hozzáférési adatot, semmilyen formában (kódolva vagy
URL-be ágyazva sem). Ezek a
failure_messageéslast_erroroszlopba kerülnek, a doctor pedig csak a beépített kulcsneveket takarja ki. A factory$configparaméterét jelöld#[\SensitiveParameter]attribútummal, hogy a hozzáférési adatok ne kerüljenek a stack trace-be. - A
status()pontosan arra a dokumentumazonosítóra válaszoljon, amelyet kapott: a visszaadott státuszdocumentIdmezője egyezzen meg vele (szigorú stringegyezés). Ha a driver normalizálja az azonosítót (kis- és nagybetű, előtag, szóköz), a válaszát a csomag figyelmen kívül hagyja, és a dokumentum sosem zárul le.
A felépített transportot a csomag név szerint gyorsítótárazza. Az einvoicing.validation.enabled
futás közbeni átállítása nem csomagolja át a már felépített transportot; a konfigurációban
állítsd, ne kódból.
Ha saját driverrel webhookot is fogadnál, regisztráld a parserét, egy core WebhookParser-t:
use IntrAgile\EInvoicing\Laravel\Facades\EInvoicing;
EInvoicing::extendWebhook('my-ap', fn ($app, #[\SensitiveParameter] array $config) => new MyAccessPointWebhook($config['webhook_secret']));
A factory megkapja az alkalmazást és a transport konfigurációját, amelyben a webhook_secret
mindig meg van adva (az útvonal a secret nélküli transportot elutasítja). Ettől kezdve az útvonal
az adott driver minden transportjához fogad értesítést. Saját drivernek nincs beállított fiókja,
ezért a csomag egyetlen értesítést sem hagy figyelmen kívül idegenként; ha kell, a fiókot a
parseredben ellenőrizd. A beépített driverhez regisztrált parser a beépítettet váltja fel.
Tesztelés
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), // a következő küldés
new OutcomeUnknown('no answer'), // az azutáni
);
// ... a tesztelt kód futtatása ...
$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']
A fake() minden transportot egyetlen memóriabeli FakeTransport-ra cserél, és kihagyja a
validációt. Előre megadott válasz nélkül minden küldés delivered eredményt ad fake-1,
fake-2 stb. azonosítóval. Ha a tesztekben sync a queue-kapcsolat, a teljes folyamat azonnal
lefut; az eredményt a visszakapott üzenet refresh()-ével látod. A webhook-aláírást a csomag
fake módban is a beállított kulccsal ellenőrzi.
Artisan parancsok
| Parancs | Feladat |
|---|---|
einvoicing:doctor [--live] |
ellenőrzi a transportokat, a webhook-URL-eket, a validációs szabályokat, a telepített szabálycsomagokat, a táblákat, a kísérleti keretet elhasznált bejövő dokumentumokat, a számértékű job-beállításokat, a queue drivert, a pcntl-t, a retry_after-t és az SQS-késleltetéseket; --live mellett minden inboxot egyszer meghív a hozzáférési adatok ellenőrzéséhez |
einvoicing:install-rules [--from=DIR] |
telepíti a Peppol BIS Billing validációs szabályokat |
einvoicing:poll-inbound [--transport=] [--include-capped] |
rögzíti a várakozó bejövő dokumentumokat és sorba állítja a feldolgozásukat; ütemezd. A --include-capped minden, az inbound.max_fetch_attempts keretet elhasznált dokumentumnak még egy kísérletet ad |
einvoicing:resolve ID (--sent=DOKUMENTUM-ID | --resend) [--force] |
rendez egy unconfirmed küldést, vagy újra sorba állít egy dokumentumot |
Mi van ellenőrizve
| Terület | Hogyan | Állapot |
|---|---|---|
| Állapotgép, küldési szabályok, újrapróbálás, foglalás lejárata, státuszlekérdezés, bejövő feldolgozás, webhookok, parancsok | Offline feature tesztek FakeTransport-tal és stub transportokkal: 338 teszt, 1824 ellenőrzés PHP 8.5-ön az itt telepített függőségekkel (a CI PHP 8.3, 8.4 és 8.5 × Laravel 12 és 13 kombinációkat futtat) |
Minden tesztfuttatáskor |
| Peppol-validáció a manageren keresztül | Opcionális peppol-rules csoport: helyi másolatból telepíti a hivatalos szabályokat, és validáló transporton átküldi a Peppol alappéldát |
Kiadás előtt |
| Recommand driver | A core offline tesztjei a Recommand publikált API-leírásából írt fixture-ökkel; a core recommand-live éles csoportja; a híd RecommandSmokeTest éles futtatása, amely számlát küld az EInvoicing::send()-del |
Élesben tesztelve a Peppol teszthálózaton (2026-11-15: core- és hídfuttatás) |
| B2Brouter és e-invoice.be driver | A core offline szerződéstesztjei a szolgáltatók nyilvános API-leírásából írt fixture-ökkel, a core b2brouter-live és einvoicebe-live éles csoportjai; a manager, a konfiguráció, a doctor és a webhook-útválasztás tesztjei itt |
Élesben tesztelve a szolgáltatói sandbox ellen (szimulált hálózat) (2026-11-15, core) |
| Webhook-aláírások | Offline tesztek a szolgáltatók dokumentált sémája szerint (az e-invoice.be-nél a közzétett tesztvektorral is) | Offline ellenőrizve; a webhookokat nem teszteltük élesben (nyilvános HTTPS-végpont kellene) |
A core brick/math ^0.14.8-at kér, ezt a Laravel 13 is elfogadja.
A futtatások eredménye dátummal és commitokkal a core VERIFICATION.md fájljában van (angolul). A webhook-aláírásokat a szolgáltatók dokumentált sémája szerint offline ellenőrizzük (az e-invoice.be-ét a közzétett tesztvektorral is); a webhookokat nem teszteltük élesben.
A csomag alapértelmezett tesztfuttatása nem használ hálózatot; az éles smoke-futtatás ki van
zárva belőle (recommand-live csoport, Live testsuite), és csak akkor indul, ha a kulcs a
Peppol teszthálózaton lévő Recommand playgroundhoz tartozik. A core-ban opcionális éles csoportok
vannak:
recommand-live Recommand playground csapathoz, b2brouter-live B2Brouter sandboxhoz és
einvoicebe-live e-invoice.be sandbox céghez; lásd a core
TRANSPORT.md leírását.
Ismert korlátok (1.x-re halasztva)
- Még nincs operátori parancs olyan
pendingsorra, amelynek az állapotlekérései elfogytak; az ilyen sort a hozzáférési pontnál ellenőrizd (azeinvoicing:resolveazunconfirmedés az elhagyottsendingsorokat kezeli). - e-invoice.be: a postafiókot nálunk vágjuk a visszatekintési időnél; a szolgáltató
date_fromszűrőjét még nem használjuk. - Nincs védelem arra, hogy egy állapotmentes webhook második állapotlekérési láncot indítson; az
extra lánc a dokumentum
status_checkskeretén osztozik, így az összes lekérés astatus.max_attemptskeretén belül marad.
Egyik sem helyességi hiba.
Verziókezelés
A nyolc csomag mindig együtt, azonos verziószámmal jelenik meg, a szemantikus verziózás (Semantic
Versioning) szerint: az öt motorcsomag (intragile/php-einvoicing, az
intragile/einvoicing-rules-en16931, intragile/einvoicing-rules-xrechnung és
intragile/einvoicing-rules-facturx szabálycsomag, valamint az intragile/laravel-einvoicing) és a
három belépő csomag (intragile/laravel-xrechnung, intragile/laravel-zugferd és
intragile/laravel-peppol). Mindegyikből ugyanazt a minor verziót használd. A szabálycsomagok
Composer conflict bejegyzéssel kizárják a saját minor verziójuknál régebbi (és a következő major)
magot, így új szabályok sosem kerülnek olyan motor mellé, amely nem tudja futtatni őket.
Fejlesztés
composer test # PHPUnit
composer analyse # PHPStan, max szint
composer format # Pint
EINVOICING_PEPPOL_FROM=/path/to/peppol/sch vendor/bin/phpunit --group peppol-rules
Licenc
MIT. Lásd: LICENSE.
Fejlesztő és karbantartó: IntrAgile Kft.
Ez az oldal a csomag v1.0.0 verziójának README-jéből készült. Forrás a GitHubonúj lapon nyílik meg