PHP code example of smart-dato / post-it-sdk

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

smart-dato / post-it-sdk example snippets

use SmartDato\PostIt\PostIt;

// Production (uses confirmed PRODUCTION_BASE_URL = https://apiw.gp.posteitaliane.it/gp/internet):
$client = PostIt::production(
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    scope: 'shipping',
);

// Or, for a custom base URL (test environment, on-premise, alternate contract):
$client = new PostIt(
    baseUrl: 'https://your-tenant.posteitaliane.it/gp/internet',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    scope: 'shipping',
    grantType: 'client_credentials',
);

use Illuminate\Support\Facades\Cache;

$client = PostIt::production(
    clientId: $account->client_id,
    clientSecret: $account->client_secret,
    scope: $account->scope,
    cache: Cache::store('redis'),
);

use SmartDato\PostIt\Data\AddressData;
use SmartDato\PostIt\Data\DeclarationData;
use SmartDato\PostIt\Data\ServicesData;
use SmartDato\PostIt\Data\WaybillData;
use SmartDato\PostIt\Data\WaybillRequestData;
use SmartDato\PostIt\Enums\PaymentMode;
use SmartDato\PostIt\Enums\PrintFormat;
use SmartDato\PostIt\Enums\Product;

$response = $client->createWaybill(new WaybillRequestData(
    costCenterCode: 'CC100',
    shipmentDate: new DateTimeImmutable(),
    waybills: [
        new WaybillData(
            clientReferenceId: 'ORDER-123',
            printFormat: PrintFormat::default(),      // '1011' — 10×11 cm
            product: Product::Express,                // 'APT000901'
            sender: new AddressData(
                nameSurname: 'Sender Co',
                contactName: 'Mario Rossi',
                address: 'Via Roma',
                streetNumber: '1',
                zipCode: '00100',
                city: 'Roma',
                cellphone: '393331111111',
                phone: '393331111111',
            ),
            receiver: new AddressData(
                nameSurname: 'Receiver Co',
                contactName: 'Luigi Bianchi',
                address: 'Via Milano',
                streetNumber: '2',
                zipCode: '20100',
                city: 'Milano',
                cellphone: '393332222222',
                phone: '393332222222',
            ),
            declared: [
                new DeclarationData(weightGrams: 1500, heightCm: 20, lengthCm: 30, widthCm: 40),
            ],
            services: new ServicesData(
                multicolloCode: 'APT000901',
                codAmount: 50.0,
                codPaymentMode: PaymentMode::CashOnDelivery,
            ),
        ),
    ],
));

$waybillNumber = $response->waybills[0]['code'];
$labelPdfUrl = $response->waybills[0]['downloadURL'];

use SmartDato\PostIt\Data\InternationalData;
use SmartDato\PostIt\Data\ItemData;
use SmartDato\PostIt\Enums\ReceiverType;

new WaybillData(
    clientReferenceId: 'ORDER-INT-1',
    printFormat: PrintFormat::A4,             // ZPL is not allowed for international
    product: Product::InternationalStandard,  // 'APT000904'
    sender: $sender,
    receiver: $receiver,                       // country e.g. 'GER1', countryName 'Germania'
    declared: [
        new DeclarationData(
            weightGrams: 3000, heightCm: 10, lengthCm: 50, widthCm: 25,
            description: 'Merce non destinata alla vendita',
            packagingCode: 'C',
            nationality: 'IT',
            items: [
                // 

$tracking = $client->trackShipment($waybillNumber);

foreach ($tracking->events as $event) {
    echo $event->statusCode.' '.$event->statusDescription.' @ '.$event->location.PHP_EOL;
}

$nations = $client->listNations();                 // NationsResponseData
foreach ($nations->nations as $nation) {
    echo $nation->iso4.' '.$nation->name.PHP_EOL;   // iso4, iso2, extraEu, states[], products[]
}

$taric = $client->listTaric();                      // extra-EU standard products only
echo $taric->taric[0]->code.' '.$taric->taric[0]->englishDescription;

// Detailed sheet for a country + product: allowed contents, 

use SmartDato\PostIt\Data\PickupAddressData;
use SmartDato\PostIt\Data\PickupBookingData;
use SmartDato\PostIt\Data\PickupContentData;
use SmartDato\PostIt\Data\PickupReportFilterData;
use SmartDato\PostIt\Data\DepositsListFilterData;
use SmartDato\PostIt\Data\DepositsReleaseData;
use SmartDato\PostIt\Enums\BookingType;
use SmartDato\PostIt\Enums\PickupOperation;
use SmartDato\PostIt\Enums\ReleaseAction;
use SmartDato\PostIt\Enums\TimeSlot;

// Book a pickup — `where` is the only mandatory address.
$booking = $client->bookPickup(new PickupBookingData(
    operation: PickupOperation::Add,
    bookingType: BookingType::Multiple,
    where: new PickupAddressData(givenName: 'Acme Srl', streetName: 'Via Roma', streetNumber: '1', town: 'Roma', region: 'RM', postCode: '00100', country: 'IT'),
    pickupDate: '20260610',                         // examples use YYYYMMDD
    timeSlot: TimeSlot::Morning,
    contents: [new PickupContentData(containerType: 'P', quantity: 3, weightKg: 5, heightCm: 20, widthCm: 30, lengthCm: 40)],
));
$booking->bookingId;

// Report (date range capped at 10 days), deposits list and release.
$report = $client->getPickupReport(new PickupReportFilterData(dateFrom: '2026-06-01', dateTo: '2026-06-08'));
$deposits = $client->listDeposits(new DepositsListFilterData(dateFrom: '20260601', dateTo: '20260608'));

$release = $client->releaseDeposit(new DepositsReleaseData(
    shipmentId: 'ZA123456789IT',
    releaseAction: ReleaseAction::DeliverToAnotherAddress,
    address: new PickupAddressData(givenName: 'Mario Rossi', streetName: 'Via Milano', streetNumber: '2', town: 'Milano', postCode: '20100'),
));
$release->failed();                                 // per-barcode outcomes that returned KO

use SmartDato\PostIt\Data\TransitTimeQueryData;
use SmartDato\PostIt\Data\LocationFinderQueryData;
use SmartDato\PostIt\Data\GreenIndexFilterData;
use SmartDato\PostIt\Data\ServicesQueryData;
use SmartDato\PostIt\Data\ServiceAddressData;
use SmartDato\PostIt\Data\DeclarationData;
use SmartDato\PostIt\Enums\DeliveryPointServiceType;
use SmartDato\PostIt\Enums\Product;

// Digital proof of delivery — request, then download (base64 → bytes).
$client->requestDigipod(['ZA123456789IT'], mail: '[email protected]');
$pod = $client->downloadDigipod('ZA123456789IT');
file_put_contents($pod->filename ?? 'pod.pdf', $pod->contents());

// PUDO master data by postal code + service type.
$points = $client->findDeliveryPoints('00152', DeliveryPointServiceType::PuntoPoste);

// Transit-time estimate (dates are sent as GMT Unix timestamps).
$transit = $client->getTransitTime(new TransitTimeQueryData(
    acceptanceChannel: 'SDA', productCode: 'PBS',
    originZip: '88833', destinationZip: '64010',
    startDate: new DateTimeImmutable('2026-06-20 18:00:00'),
));
$transit->transitTimes[0]->transitTime;          // e.g. 4 (days)

// International PUDO finder (PDB International Plus only — DHL passthrough).
$pudos = $client->findInternationalPudos(new LocationFinderQueryData(countryCode: 'FI', addressLocality: 'helsinky'));

// Available extra services + compatibility matrix (+ carrier for international).
$services = $client->getServices(new ServicesQueryData(
    costCenterCode: 'CDC-100', product: Product::Express,
    sender: new ServiceAddressData(zipCode: '00142', city: 'ROME', country: 'ITA1'),
    receiver: new ServiceAddressData(zipCode: '20100', city: 'MILANO', country: 'ITA1'),
    declared: [new DeclarationData(weightGrams: 1500, heightCm: 20, lengthCm: 30, widthCm: 40)],
));
$services->services;            // ['APT000912', ...]
$services->compatibilities;     // code => compatible codes

// Green Index emissions dashboard.
$green = $client->getGreenIndex(new GreenIndexFilterData(products: ['PDB Standard']));
$green->emissions?->totalEmissions;

use SmartDato\PostIt\Enums\PrintFormat;
use SmartDato\PostIt\Enums\Product;
use SmartDato\PostIt\Enums\PaymentMode;

PrintFormat::A4;            // 'A4'
PrintFormat::FORMAT_1011;   // '1011' (10×11 cm)
PrintFormat::ZPL;           // 'ZPL'
PrintFormat::default();     // PrintFormat::FORMAT_1011

PrintFormat::make('1011');  // PrintFormat::FORMAT_1011
Product::make('APT000901'); // Product::Express
PaymentMode::tryMake($raw); // PaymentMode|null

use Saloon\Http\Faking\MockClient;
use Saloon\Http\Faking\MockResponse;
use SmartDato\PostIt\Requests\AuthRequest;
use SmartDato\PostIt\Requests\CreateWaybillRequest;

MockClient::global([
    AuthRequest::class => MockResponse::make(['access_token' => 'fake'], 200),
    CreateWaybillRequest::class => MockResponse::make([
        'costCenterCode' => 'CC',
        'contractCode' => 'CT',
        'waybills' => [['code' => 'WB1', 'downloadURL' => 'https://...']],
    ], 200),
]);

// ... your code that calls $client->createWaybill(...) ...

MockClient::destroyGlobal();

bash
php artisan vendor:publish --tag=post-it-sdk-config