README

Apaczka.pl API v2 client for Laravel. One integration ships parcels with InPost, DPD, DHL, UPS, Poczta Polska (Pocztex), Orlen Paczka and more:

HMAC-SHA256 signed requests, with the error envelope turned into exceptions
price valuation, orders, cancellation, labels (waybills) and handover protocols
courier pickups, parcel points (lockers, pickup points) and tracking
signed push tracking webhooks dispatched as Laravel events

Polska wersja dokumentacji

Installation

composer require beziworld/laravel-apaczka
php artisan vendor:publish --tag=apaczka-config   # optional

APACZKA_APP_ID=your-app-id         # panel: Settings > API (WebAPI application)
APACZKA_APP_SECRET=your-app-secret
APACZKA_SANDBOX=false              # true = panel-sandbox.apaczka.pl

Price and send a parcel

use Beziworld\Apaczka\Data\Address;
use Beziworld\Apaczka\Data\OrderRequest;
use Beziworld\Apaczka\Data\Parcel;
use Beziworld\Apaczka\Facades\Apaczka;

$order = new OrderRequest(
    serviceId: 41,                                       // InPost locker; ids come from serviceStructure()
    sender: new Address('ACME Shop', 'ul. Prosta 1', '00-001', 'Warszawa', email: 'shop@acme.pl', phone: '500600700'),
    receiver: new Address('Jan Kowalski', 'ul. Długa 5/3', '30-001', 'Kraków',
        email: 'jan@example.com', phone: '600700800', pointId: 'KRA01M'),   // locker or pickup point
    parcels: [new Parcel(length: 38, width: 64, height: 8, weight: 2.5)],
    content: 'Books',
    codAmount: 149.99,                                   // zloty; converted to grosze
    codBankAccount: '61109010140000071219812874',
    declaredValue: 200,
    pushTrackingUrl: route('apaczka.webhook'),
);

$prices = Apaczka::valuation($order);   // [41 => ['price' => 1200, 'price_gross' => 1476]] in grosze

$created = Apaczka::sendOrder($order);
$created->id;              // Apaczka order id
$created->waybillNumber;   // carrier waybill number

$pdf = Apaczka::waybill($created->id);   // label, binary PDF

Without pickupDate the parcel is dropped off by the sender. Pass pickupDate: now()->addDay(), pickupFrom: '10:00', pickupTo: '15:00' to order a courier with the order, or use Apaczka::pickup() / Apaczka::batchPickup() later.

sendOrder() is not idempotent and is never retried automatically: on a timeout, check Apaczka::orders() before sending again.

Other operations

Apaczka::serviceStructure();                    // services, options, parcel types
Apaczka::points('INPOST');                      // list<Point>: id, address, coordinates, cod/send/deliver
Apaczka::tracking('6800000000000');             // Tracking: service, events (newest first), isDelivered()
Apaczka::pickupHours('00-001', serviceId: 21);  // available courier windows
Apaczka::turnIn([123, 124]);                    // handover protocol, binary PDF
Apaczka::dispatchCode(123);                     // drop-off code
Apaczka::cancelOrder(123);
Apaczka::call('check_data/', ['vat_id' => 'PL5261040828']);   // any other API v2 method

Push tracking webhook

The package registers POST /apaczka/webhook (route name apaczka.webhook). Set its URL as the tracking webhook of the WebAPI application, or send it with each order as pushTrackingUrl. Every notification is verified with HMAC-SHA256 and dispatched as an event:

use Beziworld\Apaczka\Events\TrackingStatusChanged;

Event::listen(function (TrackingStatusChanged $event): void {
    $shipment = Shipment::where('apaczka_order_id', $event->notification->orderId)->first();
    $status = $event->notification->latest()?->status;   // e.g. ON_THE_WAY, DELIVERED, RETURNED
    // ...
});

Apaczka redelivers a notification until it gets HTTP 200, so make listeners idempotent. Webhook statuses differ from polling statuses (for example CANCELED versus CANCELLED; SENT means a COD payout). Webhook timestamps are Europe/Warsaw time.

Configuration: APACZKA_WEBHOOK_ENABLED, APACZKA_WEBHOOK_PATH, and apaczka.webhook.middleware (default api).

Errors

Apaczka answers every call with HTTP 200 and reports the outcome in the body. The client throws ApiException for every non-200 status, with apiStatus(), route() and isSignatureError(). Connection failures are thrown as ApiException too. Missing credentials raise InvalidConfiguration.

Development

composer install
composer ci   # pint --test, phpstan (level 8), pest

Author

Created and maintained by Kamil Ćwiertnia, beziworld.eu.

E-mail: biuro@beziworld.eu
Issues: GitHub issues

Need a shipping integration for your shop? Get in touch through beziworld.eu.

Other packages by the author

laravel-inpost · laravel-furgonetka · laravel-dpd · laravel-dhl-parcel · laravel-orlen-paczka

License

MIT. See LICENSE.md. This package is not affiliated with Apaczka.pl or Alsendo.

beziworld / laravel-apaczka

Package info

Security

Statistics