README

Laravel client package for the Deliveo API.

Installation

composer require mavit/laravel-deliveo-api

Publish the config if you want to use .env defaults:

php artisan vendor:publish --tag=deliveo-config

Configuration

DELIVEO_BASE_URL=https://api.deliveo.eu
DELIVEO_LICENCE=
DELIVEO_API_KEY=
DELIVEO_SOURCE=
DELIVEO_TIMEOUT=30

Constructor arguments override config values:

use Mavit\LaravelDeliveo\Deliveo;

$deliveo = new Deliveo('demo', 'api-key', [
    'timeout' => 5,
    'source' => 'Test App',
    'base_url' => 'https://api.deliveo.eu',
]);

The constructor calls /test immediately. Invalid credentials, HTTP failures, invalid JSON, or Deliveo type=error responses throw DeliveoApiException.

Basic Usage

$deliveo->isAdministrative();
$deliveo->isClient();
$deliveo->apiKeyType();
$deliveo->customerId();
$deliveo->testResponse();

$deliveries = $deliveo->deliveries()->list();

Request payload arrays must use the field names from DeliveoAPI.yaml. The package sends POST payloads as form data and flattens nested arrays automatically.

Create Package

Package creation uses DTO/value objects and does not require database tables. POST payloads are sent as form data and package items are flattened automatically.

use Mavit\LaravelDeliveo\Data\DeliveoAddress;
use Mavit\LaravelDeliveo\Data\DeliveoItem;
use Mavit\LaravelDeliveo\Data\DeliveoPackage;

$package = new DeliveoPackage(
    sender: new DeliveoAddress(
        name: 'Nagy Adam',
        country: 'HU',
        zip: '1234',
        city: 'Budapest',
        address: 'Hungaria krt. 1.',
        phone: '+36123456789',
    ),
    consignee: new DeliveoAddress(
        name: 'Alex Muller',
        country: 'DE',
        zip: '12345',
        city: 'Berlin',
        address: 'Treskowallee 1',
        phone: '+491234567890',
    ),
    delivery: 4,
    items: [
        new DeliveoItem(
            weight: 5,
            x: 20,
            y: 30,
            z: 40,
            itemNo: 'ABC-001',
            customCode: 'CUSTOM-001',
        ),
    ],
    comment: 'Handle carefully',
);

$response = $deliveo->packages()->create($package);

$response->isSuccess();
$response->isWarning();
$response->ids();
$response->firstId();
$response->warnings();

Both Deliveo type=success and type=warning package create responses are treated as created responses. Warning details are available through warnings() and the original response through raw().

Query Packages

$package = $deliveo->packages()->find('DELI-123456789');

$packages = $deliveo->packages()->list(
    filters: [
        'last_modified' => [
            'geq' => '2020-01-01 00:00:00',
        ],
    ],
    fields: ['deliveo_id', 'sender', 'last_modified'],
    limit: 100,
    offset: 0,
);

$allPackages = $deliveo->packages()->listAll(
    filters: [
        'last_modified' => [
            'geq' => '2020-01-01 00:00:00',
        ],
    ],
    fields: ['deliveo_id', 'sender', 'last_modified'],
);

$log = $deliveo->packages()->log('DELI-123456789');

$updated = $deliveo->packages()->edit('DELI-123456789', [
    'comment' => 'Updated comment',
]);

// Administrative key only
$deliveo->packages()->status('DELI-123456789', ['status' => 'delivered']);
$deliveo->packages()->assignTo('DELI-123456789', ['location_id' => 12]);
$deliveo->packages()->pickup('DELI-123456789', ['location_id' => 12]);

// Destructive: only call this when you intentionally want to delete the shipment.
// $deleted = $deliveo->packages()->delete('DELI-123456789');

listAll() repeatedly calls /package with limit=10000 by default and returns the merged data rows. It stops when the API response max value is reached.

Write Response Wrappers

Simple write endpoints return DeliveoResponse:

$response = $deliveo->stock()->create([...]);

$response->isSuccess();
$response->isWarning();
$response->message();
$response->errorCode();
$response->data();
$response->warnings();
$response->raw();

List and detail endpoints return decoded arrays. Data-list helpers return the response data rows directly, while their listAll() variants return the merged data rows from every page. Package creation returns DeliveoPackageResponse, and PDF helpers return raw Laravel HTTP responses.

Stock

use Mavit\LaravelDeliveo\Data\DeliveoStockItem;

$reasons = $deliveo->unsuccessful()->list();

$items = $deliveo->stock()->list(limit: 1000, offset: 0);
$allItems = $deliveo->stock()->listAll();
$deliveo->stock()->find('SKU-001');

$created = $deliveo->stock()->create(new DeliveoStockItem(
    itemId: 'SKU-001',
    itemName: 'Product',
    itemWeight: 1.5,
    itemEan: '5991234567890',
));

$updated = $deliveo->stock()->edit('SKU-001', new DeliveoStockItem(
    itemName: 'Updated product',
    itemStockCorrection: 10,
    itemStockCorrectionReason: 'Inventory correction',
));

// Raw array payloads still work and must use DeliveoAPI.yaml field names.
$deliveo->stock()->create(['item_id' => 'SKU-002', 'item_name' => 'Second product']);

Locations

Administrative key only.

use Mavit\LaravelDeliveo\Data\DeliveoLocation;

$locations = $deliveo->locations()->list();

$created = $deliveo->locations()->create(new DeliveoLocation(
    type: 0,
    name: 'Main warehouse',
    alias: 'MAIN',
));

Addresses

use Mavit\LaravelDeliveo\Data\DeliveoSavedAddress;

$addresses = $deliveo->addresses()->list(limit: 1000, offset: 0, filter: 'Bud');
$allAddresses = $deliveo->addresses()->listAll(filter: 'Bud');
$address = $deliveo->addresses()->find(123);

$created = $deliveo->addresses()->create(new DeliveoSavedAddress(
    name: 'Office',
    zip: '1111',
    city: 'Budapest',
    address: 'Fo utca 1.',
    phone: '+3612345678',
    country: 'HU',
    email: 'office@example.com',
));

// Administrative key required when filtering by customer_id
$deliveo->addresses()->list(customerId: 131);
$deliveo->addresses()->listAll(customerId: 131);

Customers

Administrative key only.

use Mavit\LaravelDeliveo\Data\DeliveoCustomer;

$customers = $deliveo->customers()->list();
$allCustomers = $deliveo->customers()->listAll();
$customer = $deliveo->customers()->find(131);

$created = $deliveo->customers()->create(new DeliveoCustomer(
    name: 'Acme Kft',
    zip: '1111',
    city: 'Budapest',
    address: 'Fo utca 1.',
    phone: '+3612345678',
    country: 'HU',
    email: 'billing@example.com',
));

Quotes

use Mavit\LaravelDeliveo\Data\DeliveoQuote;

$quote = $deliveo->quotes()->create(new DeliveoQuote(
    sender: 'Sender Kft',
    senderCountry: 'HU',
    senderZip: '1111',
    senderCity: 'Budapest',
    senderAddress: 'Fo utca 1.',
    consignee: 'Consignee GmbH',
    consigneeCountry: 'DE',
    consigneeZip: '10115',
    consigneeCity: 'Berlin',
    consigneeAddress: 'Street 1',
    delivery: 4,
    cod: 0,
    shopId: 'PP_159',
    totalWeight: 5,
    totalVolume: 10,
));

Package Workflow

Administrative key only.

use Mavit\LaravelDeliveo\Data\DeliveoPackageAssignment;
use Mavit\LaravelDeliveo\Data\DeliveoPackagePickup;
use Mavit\LaravelDeliveo\Data\DeliveoPackageStatusChange;
use Mavit\LaravelDeliveo\Enums\PackageStatusPaymentMethod;

$deliveo->packages()->status('DEV26050441371', new DeliveoPackageStatusChange(
    state: 0,
    stateText: 'Delivered',
    receivedBy: 'Beru Lars',
    date: '2026-07-15 14:10:33',
    payment: PackageStatusPaymentMethod::Card,
));

$deliveo->packages()->assignTo('DEV26050441371', new DeliveoPackageAssignment(
    pickedUpLocationId: 44,
));

$deliveo->packages()->pickup('DEV26050441371', new DeliveoPackagePickup(
    locationId: 22,
    datetime: '2026-05-15 14:10:33',
));

Label PDFs

use Mavit\LaravelDeliveo\Enums\LabelSize;

$response = $deliveo->getLabel('DEV26050441371', LabelSize::A4);
$response = $deliveo->getLabel(['DEV1', 'DEV2'], LabelSize::A6);
$response = $deliveo->getSignature('DEV26050441371');
$response = $deliveo->getMplSending(['DEV1', 'DEV2']);

return response($response->body(), 200, [
    'Content-Type' => 'application/pdf',
]);

PDF helpers return raw Laravel HTTP responses. If Deliveo returns a JSON error, DeliveoApiException is thrown.

Endpoint Coverage

Error Handling

use Mavit\LaravelDeliveo\Exceptions\DeliveoApiException;

try {
    $deliveo->packages()->find('DELI-123456789');
} catch (DeliveoApiException $exception) {
    $status = $exception->status;
    $errorCode = $exception->deliveoErrorCode;
    $message = $exception->deliveoMessage;
}

Some Deliveo endpoints require an administrative API key.