README

A sleek, fluent, and strongly-typed Laravel client for the Dokapi Peppol API. Built for modern PHP 8.3+ and Laravel 11/12 environments.

Introduction

Dokapi for Laravel provides a high-level, expressive interface for interacting with the Dokapi Peppol infrastructure. It abstracts away the complexities of OAuth2 authentication, token management, and raw API calls, allowing you to focus on building your application.

• Developer Experience First: A fluent, discoverable API that feels native to Laravel.
• Type Safety: Extensive use of DTOs ensures your IDE understands every response.
• Production Ready: Built-in OAuth2 caching, signature verification, and granular error handling.
• Future Proof: Fully optimized for PHP 8.3+ and Laravel 11/12.

Installation

You may install the package via Composer:

composer require andyfraussen/laravel-dokapi-client

Next, you should publish the configuration file:

php artisan vendor:publish --provider="AndyFraussen\Dokapi\DokapiServiceProvider" --tag="dokapi-config"

Configuration

After publishing the configuration, you may define your Dokapi credentials in your .env file:

DOKAPI_CLIENT_ID=your-client-id
DOKAPI_CLIENT_SECRET=your-client-secret
DOKAPI_BASE_URL=https://peppol-api.dokapi-stg.io/v1
DOKAPI_TOKEN_URL=https://dev-portal.dokapi.io/api/oauth2/token
DOKAPI_ACCESS_TOKEN=
DOKAPI_TIMEOUT=30
DOKAPI_CONNECT_TIMEOUT=10
DOKAPI_VERIFY=true
DOKAPI_USER_AGENT=andyfraussen/laravel-dokapi-client

The default DOKAPI_BASE_URL points to the staging environment defined in Dokapi's OpenAPI spec. Use the production base URL provided by Dokapi when you move to production. If you already have an access token, set DOKAPI_ACCESS_TOKEN to bypass OAuth2.

For advanced HTTP tuning (proxies, custom headers, TLS options), you can pass Guzzle options via the dokapi.http config key.

Usage

The Fluent API

The recommended way to interact with Dokapi is through the fluent API provided by the Dokapi facade.

use AndyFraussen\Dokapi\Facades\Dokapi;

// Send a document with a single call
$response = Dokapi::api()->outgoingDocuments->sendDto($payload, $xml);

echo $response->document->ulid;

Outgoing Documents

You can easily send Peppol documents using our expressive request builders:

use AndyFraussen\Dokapi\Dto\ParticipantIdentifier;
use AndyFraussen\Dokapi\Requests\OutgoingDocumentRequest;

$request = new OutgoingDocumentRequest(
    sender: ParticipantIdentifier::of('0208:0123456789'),
    receiver: ParticipantIdentifier::of('0208:9876543210'),
    c1CountryCode: 'BE',
    documentTypeIdentifier: $docType,
    processIdentifier: $process,
    externalReference: 'inv-2026-001'
);

$response = Dokapi::sendOutgoingDocument($request, $xml);

Error Handling

All non-2xx responses throw a DokapiRequestException subclass (auth, validation, not found, rate limit, server, or client errors). You can access the raw response body with getResponseBody() or a parsed ProblemDetail (when available) with getProblemDetail().

Participant registrations can also return a 207 response with a ProblemDetail payload. In that case, registerDto() returns a ProblemDetail instance instead of a success DTO.

Webhook Signature Verification

Security is paramount. Verify incoming webhooks with ease:

use AndyFraussen\Dokapi\Facades\Dokapi;

$isValid = Dokapi::webhooks()->verifySignature(
    payload: $request->getContent(),
    signature: $request->header('X-Dokapi-Signature'),
    secret: config('dokapi.webhook_secret')
);

Testing

composer test

Static Analysis

We maintain a high standard of code quality using Larastan (PHPStan):

composer phpstan

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT). Please see License File for more information.