PHPackages smart-dato/post-it-sdk - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. smart-dato/post-it-sdk ActiveLibrary[API Development](/categories/api) smart-dato/post-it-sdk ====================== Poste Italiane (POST\_IT) shipping API SDK for Laravel — Saloon-based client with typed DTOs. v0.0.4(1mo ago)033MITPHPPHP ^8.2 Since May 8Pushed 1mo agoCompare [ Source](https://github.com/smart-dato/post-it-sdk)[ Packagist](https://packagist.org/packages/smart-dato/post-it-sdk)[ Docs](https://github.com/smart-dato/post-it-sdk)[ RSS](/packages/smart-dato-post-it-sdk/feed)WikiDiscussions main Synced 3w ago READMEChangelog (1)Dependencies (14)Versions (6)Used By (0) Poste Italiane SDK for Laravel ============================== [](#poste-italiane-sdk-for-laravel) [![Latest Version on Packagist](https://camo.githubusercontent.com/01b2d45fdd1daa41144911bdc94de5032328d2aca11b2d1705d37c97516767e3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736d6172742d6461746f2f706f73742d69742d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/smart-dato/post-it-sdk)[![GitHub Tests Action Status](https://camo.githubusercontent.com/245397f9e56fb712c1e95eaca899782f618d54627b0c2692ce156b99ecac87f2/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f736d6172742d6461746f2f706f73742d69742d73646b2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/smart-dato/post-it-sdk/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/24eaedd0d7277d43944065cb98e55b1a4e8b5ca252e486a2fc28045748b682e0/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f736d6172742d6461746f2f706f73742d69742d73646b2f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/smart-dato/post-it-sdk/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/1a3414e69b7c09a8034a0ee542d2b29867c68b3d6d19797be61951741bc5beb7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f736d6172742d6461746f2f706f73742d69742d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/smart-dato/post-it-sdk) Saloon-based client for the Poste Italiane (POST\_IT) shipping API. - OAuth-style session authentication (`POST /user/sessions`) with per-account token caching — in-memory by default, or a shared cache across processes - Waybill creation (`POST /postalandlogistics/parcel/waybill`) — domestic **and** international, returns the label PDF URL - Shipment tracking (`POST /postalandlogistics/parcel/tracking`) — returns normalised events - International lookups — countries (`/international/nations`), country/product detail (`/international/nation/details`), TARIC codes (`/international/taric`), extra services & carrier (`/waybill/services`) and PUDO location finder (`/locationFinder`) - Pickups & deposits — book/edit/cancel a pickup (`/pickup`), pickup report (`/pickupReport`), deposits list (`/depositsList`) and release (`/depositsRelease`) - DigiPOD, delivery points, transit time & Green Index — proof-of-delivery request/download (`/digipodRequest`, `/digipodDownload`), PUDO master data (`/deliveryPoint`), transit-time estimates (`/transitTime`) and the emissions dashboard (`/gibp/dashboardGreenMeter`) - **Full coverage of the v1.9 manual** — every documented service has a typed `PostIt` method - Typed readonly DTOs for every request/response payload, with enums (`PrintFormat`, `Product`, `PaymentMode`, `ReceiverType`, `BookingType`, `TimeSlot`, `PickupOperation`, `ReleaseAction`, `DeliveryPointServiceType`) and a lenient `make()` factory - Mockable end-to-end via Saloon's `MockClient` Installation ------------ [](#installation) ``` composer require smart-dato/post-it-sdk ``` The service provider is auto-discovered. Optionally publish the config file: ``` php artisan vendor:publish --tag=post-it-sdk-config ``` Configuration ------------- [](#configuration) The SDK is **credential-free by default** — it does not read credentials from config or env. Pass them explicitly when constructing `PostIt`. The published config file (`config/post-it-sdk.php`) is provided as a convenience for single-account integrations that want to centralise defaults; multi-tenant applications typically store credentials per `CarrierAccount` row. ``` 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', ); ``` ### Token caching (multi-account) [](#token-caching-multi-account) By default the access token is cached **in-memory on the instance** and refreshed automatically as it nears the `expires_in` deadline. Pass a Laravel cache repository to share tokens **across requests and processes**: ``` use Illuminate\Support\Facades\Cache; $client = PostIt::production( clientId: $account->client_id, clientSecret: $account->client_secret, scope: $account->scope, cache: Cache::store('redis'), ); ``` The cache key is scoped per account — `post-it:token:{clientId}:{hash}`, where the hash folds in the base URL, scope, grant type, and secret. Several accounts may therefore share a single cache store and **will never be served each other's token**; a rotated secret transparently invalidates the cached entry. Creating a waybill ------------------ [](#creating-a-waybill) ``` 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']; ``` `PostItApiException` is thrown when the upstream returns `result.errorCode !== 0` or when the response is missing required fields. International shipments ----------------------- [](#international-shipments) For international products (`APT000903` / `APT000904` / `APT001013`) add an `InternationalData` block and the customs fields on each declaration. Sender and receiver require `contactName`, `email`, `phone`, and a `province` for US/Canada destinations. ``` 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: [ // required for APT000904 / APT001013; itemNumber is auto-assigned new ItemData(taric: '6109100010', totalValueCents: 5000, quantity: 2, totalWeightGrams: 1500, originCountry: 'IT'), ], ), ], international: new InternationalData( receiverType: ReceiverType::BusinessDelivery, currency: 'EUR', waybillTotalValue: '400', contentCode: '11', ), ); ``` The customs/`international` fields are only serialised when set, so domestic payloads are unaffected. Tracking a shipment ------------------- [](#tracking-a-shipment) ``` $tracking = $client->trackShipment($waybillNumber); foreach ($tracking->events as $event) { echo $event->statusCode.' '.$event->statusDescription.' @ '.$event->location.PHP_EOL; } ``` Each `TrackingEventData` also exposes `occurredAt` (`?DateTimeImmutable`), `phase`, and `synthesisStatusDescription`. Pass `fullHistory: false` to receive only the latest tracing state instead of the entire history. International lookups --------------------- [](#international-lookups) These supporting endpoints feed the data needed to compile international waybills. The country/TARIC lists take no request body. ``` $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, required docs, transit times, customs notes. $details = $client->getNationDetails('FRA1', Product::InternationalStandard->value); $details->carriers['EURODIS']->contents; // ContentTypeData[] with attachments + deliveryTimes $details->customsByProduct['APT000904']['customsInfo']; ``` Pickups & deposits ---------------------- [](#pickups--deposits) ``` 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 ``` The pickup/deposit responses report success via an `OK`/`KO` outcome; the SDK throws `PostItApiException` on failure (except per-barcode release outcomes, which are exposed on `DepositsReleaseResponseData::$items` / `failed()`). DigiPOD, delivery points, transit time & Green Index -------------------------------------------------------- [](#digipod-delivery-points-transit-time--green-index) ``` 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: 'ops@example.com'); $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; ``` > **Note:** date formats and a few field names differ between the manual's tables and its JSON examples (e.g. `pickupDate` as `YYYYMMDD` vs `YYYY-MM-DD`, `content`/`tipocontText`). The SDK follows the example payloads and passes dates through as strings — verify against the test environment for your contract. Enums for fixed values ---------------------- [](#enums-for-fixed-values) Documented fixed-value fields are typed enums. Each exposes a lenient `make()` factory (trims, matches case-insensitively on value **or** case name, throws `ValueError` on a miss) and a null-returning `tryMake()`: ``` 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 ``` `WaybillData::$printFormat` and `$product` accept the enum **or** a raw string, so contract-specific values not modelled here still pass through unchanged. Testing ------- [](#testing) The SDK tests itself with Saloon's `MockClient`. Consumer applications can do the same: ``` 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(); ``` Integration tests (live API) ---------------------------- [](#integration-tests-live-api) The default suite is fully mocked. A separate `tests/Integration` suite hits the real Poste Italiane **test environment** ("kindergarden", `PostIt::TEST_BASE_URL`). Those tests **skip themselves** unless the required env vars are set, so they never break CI: ``` export POST_IT_TEST_CLIENT_ID='...' # see docs/MANUALE WS PDB for the sandbox client/secret export POST_IT_TEST_CLIENT_SECRET='...' export POST_IT_TEST_SCOPE='api://8f0f2c58-19a8-45ef-9f9e-8bcb0acc7657/.default' # optional overrides export POST_IT_TEST_BASE_URL='https://apid.gp.posteitaliane.it/dev/kindergarden' export POST_IT_TEST_WAYBILL='ZA123456789IT' # tracking sample export POST_IT_TEST_COST_CENTER='CDC-...' # enables the live waybill-creation test composer test:integration ``` `PostIt::test(...)` is a convenience factory pointed at the test environment, mirroring `PostIt::production(...)`. Quality gate ------------ [](#quality-gate) ``` composer test # pint + phpstan + pest (mocked Unit + Feature) composer test:lint # pint --test composer test:types # phpstan analyse composer test:unit # pest (Unit + Feature) composer test:integration # pest (live API; skipped without POST_IT_TEST_* env) composer lint # pint (fix) ``` License ------- [](#license) MIT — see `LICENSE.md`. ### Health Score 39 — LowBetter than 84% of packages Maintenance91 Actively maintained with recent releases Popularity10 Limited adoption so far Community8 Small or concentrated contributor base Maturity40 Maturing project, gaining track record Bus Factor1 Top contributor holds 95.8% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~11 days Total 4 Last Release 42d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/c3006db55caec62526937fa2d941da32fc5e69e2ca86a52e87c8046da5958d82?d=identicon)[smart-dato](/maintainers/smart-dato) --- Top Contributors [![michael-tscholl](https://avatars.githubusercontent.com/u/178569346?v=4)](https://github.com/michael-tscholl "michael-tscholl (23 commits)")[![Xsaven](https://avatars.githubusercontent.com/u/1726771?v=4)](https://github.com/Xsaven "Xsaven (1 commits)") --- Tags laravelsaloonshippingsmart-datopost-itposte-italiane ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/smart-dato-post-it-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/smart-dato-post-it-sdk/health.svg)](https://phpackages.com/packages/smart-dato-post-it-sdk) ``` ### Alternatives [dedoc/scramble Automatic generation of API documentation for Laravel applications. 2.1k11.2M113](/packages/dedoc-scramble)[codebar-ag/laravel-docuware DocuWare integration with Laravel 1123.7k](/packages/codebar-ag-laravel-docuware)[defstudio/telegraph A laravel facade to interact with Telegram Bots 813336.8k3](/packages/defstudio-telegraph)[rawilk/profile-filament-plugin Profile & MFA starter kit for filament. 3914.8k](/packages/rawilk-profile-filament-plugin)[codebar-ag/laravel-zammad Zammad integration with Laravel 107.1k](/packages/codebar-ag-laravel-zammad)[lettermint/lettermint-laravel Official Lettermint driver for Laravel 1190.2k1](/packages/lettermint-lettermint-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)