mavit/laravel-deliveo-api

Laravel client package for the Deliveo API.

dev-main 2026-07-09 18:25 UTC

Requires

• php: ^8.2
• illuminate/http: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0

Requires (Dev)

• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.0|^4.0
• phpunit/phpunit: ^10.0|^11.0|^12.0|^13.0

MIT

Published on Packagist.org on 2026-07-09 16:27 UTC

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: '[phone]',
    ),
    consignee: new DeliveoAddress(
        name: 'Alex Muller',
        country: 'DE',
        zip: '12345',
        city: 'Berlin',
        address: 'Treskowallee 1',
        phone: '[phone]',
    ),
    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: '[phone]',
    country: 'HU',
    email: '[e-mail]',
));

// 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: '[phone]',
    country: 'HU',
    email: '[e-mail]',
));

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;

$deliveo->packages()->status('DEV26050441371', new DeliveoPackageStatusChange(
    state: 0,
    stateText: 'Delivered',
    receivedBy: 'Beru Lars',
));

$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

Endpoint	Public API	Admin-only	Request type	Response type
GET /test	constructor, testResponse()	No	none	array helper
GET /delivery	deliveries()->list()	No	none	data array
GET /unsuccessful	unsuccessful()->list()	No	none	data array
GET /item	stock()->list(), stock()->listAll()	No	limit, offset	data array
POST /item	stock()->create()	No	array or DeliveoStockItem	DeliveoResponse
GET /item/{item_id}	stock()->find()	No	path id	array
POST /item/{item_id}/edit	stock()->edit()	No	array or DeliveoStockItem	DeliveoResponse
GET /locations	locations()->list()	Yes	limit, offset	data array
POST /locations/create	locations()->create()	Yes	array or DeliveoLocation	DeliveoResponse
GET /package	packages()->list(), packages()->listAll()	No	filters, fields, limit, offset	array
GET /package/{deliveo_id}	packages()->find()	No	path id	array
POST /package/create	packages()->create()	No	DeliveoPackage	DeliveoPackageResponse
POST /package/{deliveo_id}/edit	packages()->edit()	No	array	DeliveoResponse
POST /package/{deliveo_id}/status	packages()->status()	Yes	array or DeliveoPackageStatusChange	DeliveoResponse
POST /package/{deliveo_id}/assignto	packages()->assignTo()	Yes	array or DeliveoPackageAssignment	DeliveoResponse
POST /package/{deliveo_id}/pickup	packages()->pickup()	Yes	array or DeliveoPackagePickup	DeliveoResponse
GET /package_log/{deliveo_id}	packages()->log()	No	path id	array
POST /package/{deliveo_id}/delete	packages()->delete()	API decides	path id	DeliveoResponse
GET /label	getLabel()	No	id(s), LabelSize, lang	raw Response
GET /signature/{deliveo_id}	getSignature()	No	path id	raw Response
GET /address	addresses()->list(), addresses()->listAll()	Only with customerId	limit, offset, filter, customerId	data array
POST /address/create	addresses()->create()	No	array or DeliveoSavedAddress	DeliveoResponse
GET /address/{address_id}	addresses()->find()	No	path id	array
GET /customer	customers()->list(), customers()->listAll()	Yes	limit, offset	data array
POST /customer/create	customers()->create()	Yes	array or DeliveoCustomer	DeliveoResponse
GET /customer/{customer_id}	customers()->find()	Yes	path id	array
POST /mpl_sending	getMplSending()	No	id(s)	raw Response
POST /quote	quotes()->create()	No	array or DeliveoQuote	DeliveoResponse

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.