README

PHP/Laravel client for Delivery-Auto API v3.5.1 — references, tracking, calculator, receipt issuance, cabinet, and operation logs. Implements all 38 documented endpoints, with typed spatie/laravel-data request/response DTOs and Laravel-native HTTP retry/caching.

Requirements

• PHP 8.2+
• Laravel 11, 12, or 13
• spatie/laravel-data ^4.4

Installation

composer require sashalenz/delivery-auto-api

Publish the config:

php artisan vendor:publish --provider="Sashalenz\DeliveryAuto\DeliveryAutoServiceProvider" --tag="delivery-auto-api-config"

Configuration

// config/delivery-api.php
return [
    'url' => env('DELIVERY_API_URL', 'https://www.delivery-auto.com/api/v4/Public/'),

    // HMAC API keys — issued per company by Delivery-Auto, used for §6 (receipt) endpoints
    'public_key' => env('DELIVERY_API_PUBLIC_KEY'),
    'secret_key' => env('DELIVERY_API_SECRET_KEY'),

    // OPTIONAL — only for §5 (cabinet) and §7 (logs) endpoints, which require username/password
    'username' => env('DELIVERY_API_USERNAME'),
    'password' => env('DELIVERY_API_PASSWORD'),

    'shared_forms_url' => env('DELIVERY_API_SHARED_FORMS_URL', 'https://www.delivery-auto.com/'),
];

.env:

DELIVERY_API_PUBLIC_KEY=your-public-key
DELIVERY_API_SECRET_KEY=your-secret-key

Two auth mechanisms

Delivery-Auto v4 ships with two distinct auth flows:

• HMAC API key (PDF §6.1) — used by all §6 receipt-issuance endpoints. Header HMACAuthorization: amx {publicKey}:{timestamp}:{HmacSHA256}. Algorithm is SHA-256, not SHA-1 (this was an upstream documentation gap that the pre-2.0 release of this package got wrong).
• Login session — used by §5 personal-cabinet and §7 log endpoints. Username/password via PostLogin returns a session cookie that subsequent calls reuse via Laravel's HTTP client cookie jar.

Public reference, tracking, calculation, and communication endpoints (§1–4) need no auth.

Multi-sender (multiple HMAC keypairs)

If your app holds several Delivery-Auto company keypairs (one per sender / counterparty), pass them per call instead of relying on the global config:

use Sashalenz\DeliveryAuto\DeliveryAuto;

// Per-call factory
DeliveryAuto::receipt(
    publicKey: $sender->public_key,
    secretKey: $sender->secret_key,
)->postCreateReceipts($request);

// Or fluent — handy when you've already obtained a builder
DeliveryAuto::receipt()
    ->withCredentials($sender->public_key, $sender->secret_key)
    ->cache(300)
    ->getSenderList(new GetSenderListRequest);

Without overrides the builder falls back to config('delivery-auto-api.public_key') / secret_key. Cache keys include a hash of the public key, so two senders never share cached responses.

DeliveryAuto::tracking(...) accepts the same overrides for getStickers (the only HMAC method in that module).

Quick start — round-trip

use Sashalenz\DeliveryAuto\Delivery;
use Sashalenz\DeliveryAuto\ApiModels\Reference\RequestData\GetRegionListRequest;
use Sashalenz\DeliveryAuto\ApiModels\Tracking\RequestData\GetReceiptDetailsRequest;
use Sashalenz\DeliveryAuto\ApiModels\Calculation\RequestData\PostReceiptCalculateRequest;
use Sashalenz\DeliveryAuto\ApiModels\Calculation\RequestData\CategoryRequest;
use Sashalenz\DeliveryAuto\ApiModels\Receipt\RequestData\PostCreateReceiptsRequest;
use Sashalenz\DeliveryAuto\ApiModels\Receipt\RequestData\RegistrationReceiptRequest;
use Sashalenz\DeliveryAuto\Enums\Country;
use Sashalenz\DeliveryAuto\Enums\DeliveryScheme;
use Spatie\LaravelData\DataCollection;

// 1) Lookup — cached for an hour because regions rarely change
$regions = DeliveryAuto::reference()
    ->cache(3600)
    ->getRegionList(new GetRegionListRequest(country: Country::UA));

// 2) Calculate cost
$calc = DeliveryAuto::calculation()->postReceiptCalculate(new PostReceiptCalculateRequest(
    areasSendId:        '4fc948a7-3729-e311-8b0d-00155d037960',
    areasResiveId:      'e3ac6f68-3529-e311-8b0d-00155d037960',
    warehouseSendId:    '1c828aa6-70c8-e211-9902-00155d037919',
    warehouseResiveId:  'd908c5e1-b36b-e211-81e9-00155d012a15',
    InsuranceValue:     1000000,
    CashOnDeliveryValue: 5000,
    dateSend:           new DateTime('+2 days'),
    deliveryScheme:     DeliveryScheme::WarehouseDoor,
    category: new DataCollection(CategoryRequest::class, [[
        'categoryId' => '00000000-0000-0000-0000-000000000000',
        'countPlace' => 1, 'helf' => 1, 'size' => 1,
    ]]),
));
echo $calc->allSumma; // total cost

// 3) Issue a TTN
$created = DeliveryAuto::receipt()->postCreateReceipts(new PostCreateReceiptsRequest(
    receiptsList: new DataCollection(RegistrationReceiptRequest::class, [
        new RegistrationReceiptRequest(
            areasSendId:        '4fc948a7-3729-e311-8b0d-00155d037960',
            areasResiveId:      'e3ac6f68-3529-e311-8b0d-00155d037960',
            dateSend:           new DateTime('+2 days'),
            category: new DataCollection(CategoryRequest::class, [[
                'categoryId' => '00000000-0000-0000-0000-000000000000',
                'countPlace' => 1, 'helf' => 1, 'size' => 1,
            ]]),
            deliveryScheme:     DeliveryScheme::WarehouseWarehouse,
            warehouseSendId:    '1c828aa6-70c8-e211-9902-00155d037919',
            warehouseResiveId:  'd908c5e1-b36b-e211-81e9-00155d012a15',
            receiverName:       'Іванков Іван Іванович',
            receiverPhone:      '0500000000',
        ),
    ]),
));
$ttnNumber = $created[0]->Number;

// 4) Track
$details = DeliveryAuto::tracking()->getReceiptDetails(
    new GetReceiptDetailsRequest(number: $ttnNumber)
);
echo $details->Status->label(); // "Зарезервована" if just created

Modules

The seven module facades on DeliveryAuto::* mirror the seven sections of the PDF spec:

Reference

Tracking

Calculation

Communication

Cabinet (login-auth)

// Either pass credentials each time …
DeliveryAuto::cabinet()->postLogin(new PostLoginRequest(
    UserName: 'me@example.com', Password: 'secret'
));

// … or set DELIVERY_API_USERNAME / DELIVERY_API_PASSWORD env vars and call:
DeliveryAuto::cabinet()->loginFromConfig();

⚠️ The session is process-local. Multi-tenant web apps should call postLogin per request with the right credentials, not rely on loginFromConfig.

Receipt (HMAC-auth)

Logs (login-auth)

SendingRegister URL builder

§6.18 returns HTML, not JSON, so we expose only a URL builder (no HTTP call):

use Sashalenz\DeliveryAuto\SendingRegisterUrlBuilder;
use Sashalenz\DeliveryAuto\Enums\Culture;

$url = SendingRegisterUrlBuilder::url(
    id: '00123456',
    type: SendingRegisterUrlBuilder::FORM_TYPE_DETAILED,
    culture: Culture::UkUA,
);
// https://www.delivery-auto.com/uk-UA/SharedForms/SendingRegister?id=00123456&type=0

Caching

Every module method supports ->cache($seconds). seconds = -1 (default) means cache forever:

$regions = DeliveryAuto::reference()->cache(3600)->getRegionList(...);
$schemes = DeliveryAuto::calculation()->cache(86400)->getDeliveryScheme(...);

Cache keys are derived from (method, GET/POST, authMode, base64(serialize(params))) — same params hit the same entry.

⚠️ Don't cache user-scoped (cabinet/logs) calls — the session cookie is implicit, but params alone don't differentiate users.

Enums cheat-sheet

Use the enum in DTO requests directly: new GetRegionListRequest(country: Country::UA). In responses, EnumCast parses raw API integers into typed enum cases — match on them, never on raw strings.

Error handling

use Sashalenz\DeliveryAuto\Exceptions\DeliveryAutoException;
use Sashalenz\DeliveryAuto\Exceptions\DeliveryAutoApiUnavailableException;

try {
    $result = DeliveryAuto::receipt()->postCreateReceipts($request);
} catch (DeliveryAutoApiUnavailableException $e) {
    // Catch FIRST — vendor is down (5xx, ConnectionException, DNS, timeout).
    // Retry with backoff; route to monitoring as warning, not error.
    Log::warning('delivery-auto unavailable', ['exception' => $e]);
    throw $e; // or queue and retry
} catch (DeliveryAutoException $e) {
    // 4xx, application-level `status: false`. Real bug or invalid input.
    Log::error('delivery-auto request failed', ['exception' => $e]);
    throw $e;
}

The HTTP layer auto-retries 3× with 100ms backoff before exceptions surface. Both exceptions wrap the original via previous: $e so root cause survives in logs.

Bugsnag routing snippet

// app/Exceptions/Handler.php (or via Bugsnag::registerCallback)
Bugsnag::registerCallback(function (Bugsnag\Report $report) {
    if ($report->getOriginalError() instanceof DeliveryAutoApiUnavailableException) {
        $report->setSeverity('warning');
    }
});

Print labels & stickers

use Sashalenz\DeliveryAuto\ApiModels\Receipt\RequestData\GetPdfDocumentRequest;
use Sashalenz\DeliveryAuto\Enums\DocumentType;

// Returns base64-encoded PDF — `binary()` decodes to raw bytes.
$pdf = DeliveryAuto::receipt()->getPdfDocument(new GetPdfDocumentRequest(
    number: ['9900112233', '9900223344'],
    type:   DocumentType::StickersOneSheet,
));

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

For sticker JSON metadata (without the PDF render), use DeliveryAuto::tracking()->getStickers(...).

Testing

composer test           # run pest
composer test-coverage  # with coverage
composer analyse        # phpstan level 6
composer format-test    # pint

Changelog

See CHANGELOG.md. The 2.0 release is a breaking rewrite — see UPGRADING.md for migration notes from 1.x.

Security

If you discover a security vulnerability, please email sashalenz@gmail.com instead of opening a public issue.

Credits

• Oleksandr Petrovskyi
• All Contributors

License

MIT — see LICENSE.md.