This page is also available in English.

Nye værktøjer: eCourier PHP SDK og Laravel-pakke

Albert Haff

Bygger du med PHP eller Laravel, er integration med eCourier API'et nu blevet en del nemmere. Vi har udgivet to open source-pakker: et framework-uafhængigt PHP SDK, og en Laravel-pakke.

Begge er tilgængelige på GitHub og Packagist i dag:

Hvorfor et SDK

eCourier API'et er et almindeligt REST API, så man kunne altid have brugt curl eller Guzzle direkte. Men fakturaer og kreditnotaer indeholder meget struktur — parter, linjer, totaler, momsopdelinger — og at bygge det som arrays i hånden bliver hurtigt fejlbehæftet. Tastefejl i array-nøgler, manglende påkrævede felter, ingen autocomplete.

SDK'et pakker i stedet hele API'et ind i typed dataobjekter, så din editor fortæller dig, hvad et dokument skal bruge, før API'et forstår det.

Installation af PHP SDK'et

composer require ecourier/ecourier

Kræver PHP 8.3+. Opret connectoren med en API-nøgle — præfikset (pk_test_ eller pk_live_) afgør, om det er test- eller produktionstilstand:

use Ecourier\EcourierConnector;

$ecourier = new EcourierConnector(apiKey: 'pk_test_your_key_here');

Hvert kald bliver autentificeret automatisk. Ingen headers du selv skal sætte op.

Afsendelse af en faktura

Byg fakturaen som et typed InvoiceDocumentData-objekt, og eCourier konverterer det til det korrekte UBL/XML-skema for dig:

use Ecourier\Data\Invoice\InvoiceDocumentData;
use Ecourier\Data\Invoice\InvoiceLineData;
use Ecourier\Data\Invoice\InvoicePartyData;
use Ecourier\Data\Invoice\InvoiceTotalsData;
use Ecourier\Data\Invoice\ParticipantIdentifier;
use Ecourier\Enums\Channel;
use Ecourier\Enums\Currency;
use Ecourier\Enums\DocumentType;
use Ecourier\Enums\IdentifierScheme;

$invoice = new InvoiceDocumentData(
    type: DocumentType::Invoice,
    id: 'INV-2024-001',
    issueDate: '2024-06-01',
    currency: Currency::DKK,
    supplier: new InvoicePartyData(
        participant: new ParticipantIdentifier(IdentifierScheme::DK_CVR, '12345678'),
    ),
    customer: new InvoicePartyData(
        participant: new ParticipantIdentifier(IdentifierScheme::DK_CVR, '87654321'),
    ),
    lines: [new InvoiceLineData(id: 1)],
    totals: new InvoiceTotalsData(
        subtotalAmount: '1000.00',
        taxAmount: '250.00',
        totalAmount: '1250.00',
    ),
);

$document = $ecourier->documents()->sendJson(Channel::Peppol, $invoice);

echo $document->id; // 01kmkdaf55vrrecfy70180tpr6

Genererer du allerede UBL XML et andet sted i jeres stack, behøver I ikke droppe det — sendXml() tager rå XML sammen med routing-headers, så SDK'et stadig håndterer levering og statussporing for jer.

Resten af API'et følger samme mønster. Companies, participants og network lookups er hver deres ressource på connectoren, og list-endpoints returnerer en lazy paginator, så I kan iterere gennem resultaterne — eller samle dem med collect() — uden at tænke på sidetal.

Tilføjelse af Laravel-pakken

Bruger I Laravel, sparer ecourier/ecourier-laravel jer for selv at binde connectoren, og giver jer konfiguration og webhook-håndtering ud af boksen:

composer require ecourier/ecourier-laravel
php artisan vendor:publish --tag=ecourier-config
ECOURIER_API_KEY=pk_test_your_key

Connectoren hentes fra containeren, så I kan bruge den, hvor I har brug for den:

use Ecourier\EcourierConnector;

$document = app(EcourierConnector::class)->documents()->find('doc_01xyz');

Håndtering af webhooks

Indgående webhooks registreres som standard på /webhooks/ecourier, bygget oven på spatie/laravel-webhook-client. Sæt en webhook-secret og lyt efter det parsede event:

ECOURIER_WEBHOOK_SECRET=your_webhook_secret
use Ecourier\Laravel\Events\EcourierWebhookReceived;

Event::listen(EcourierWebhookReceived::class, function (EcourierWebhookReceived $event) {
    $event->webhook; // Ecourier\Data\Webhook\DocumentWebhook — parset og typed
});

Ingen manuel signaturverificering, ingen parsing af rå payloads — når jeres listener kører, arbejder I allerede med et typed objekt.

Prøv det selv

Begge pakker er MIT-licenserede og åbne for bidrag. Giv dem en stjerne, opret issues, eller send en PR:

Støder I på noget, eller mangler der en ressource, hører vi gerne fra jer.