Getting Started

Require the SDK: composer require sendynl/php-sdk:^3.1. Laravel package discovery should register the service provider; if not, add it to config/app.php.
Publish any package config (php artisan vendor:publish --tag=sendy-config) and set SENDY_API_KEY plus default shipper/sender details in .env.
Look first at the SDK client factory and the label/shipment resource classes. In v3 the paper type is no longer defaulted, so confirm how paper_type, label format, and alignment are passed.
First use case: create a single shipment and fetch its label, then move to bulk label generation. For bulk, request A6 paper and top-left positioning explicitly — v3.1.1 restores this for bulk labels, but explicit values document intent.

$label = Sendy::labels()->create([
    'shipment_id' => $shipment->id,
    'paper_type'  => 'A6',
    'position'    => 'top-left',
]);

Implementation Patterns

Bind the SDK client as a singleton in a small service provider so it can be injected into controllers, jobs, and actions instead of using static calls everywhere.
Run bulk label generation in a queued job. Bulk requests are I/O heavy; return immediately and notify via event/broadcast when the PDF is stored.
Store generated labels on a Laravel disk (Storage::disk('s3')->put(...)) and persist the SDK label ID in your own table so labels can be re-downloaded without regeneration.
Centralise label defaults in config/sendy.php (paper_type => 'A6', position => 'top-left') and merge per-request overrides. This matters more after v3 changed the defaulting behaviour.
In tests, use Http::fake() around the SDK's underlying HTTP client or bind a fake client implementation. Assert that bulk label requests include paper type and position.
For multi-tenant apps, resolve credentials per tenant through a factory or scoped binding rather than a global singleton.

Breaking change in v3: the SDK no longer defaults the paper type. If you upgraded from v2 and generate labels outside the bulk path, labels may render on the wrong size or fail validation. Set paper_type explicitly.
v3.1.1 specifically: bulk labels are pinned to A6 / top-left again (#18). If you are on v3.0.x, either upgrade to v3.1.1 or pass those options yourself.
Verify exact option names against the v3 source; v2 keys may have been renamed (paper vs paper_type, position vs alignment).
Bulk endpoints may return partial successes. Log per-item responses and persist failures rather than assuming all-or-nothing behaviour.
Watch rate limits and timeouts on large batches; chunk bulk requests and add retries with backoff.
Debug by logging raw request/response data around the SDK client. SDK exceptions can be generic, so include the label/shipment ID in logs.
Extension point: decorate the SDK client with your own wrapper for logging, retries, and metrics instead of forking the package.