PHPackages smart-dato/correos-shipping-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. [HTTP & Networking](/categories/http) 4. / 5. smart-dato/correos-shipping-sdk ActiveLibrary[HTTP & Networking](/categories/http) smart-dato/correos-shipping-sdk =============================== Laravel package for integrating Correos shipping, labels, customs documents, and tracking via Saloon. v0.0.8(2mo ago)0279↓50%[3 PRs](https://github.com/smart-dato/correos-shipping-sdk/pulls)MITPHPPHP ^8.4CI passing Since Feb 6Pushed 1mo agoCompare [ Source](https://github.com/smart-dato/correos-shipping-sdk)[ Packagist](https://packagist.org/packages/smart-dato/correos-shipping-sdk)[ Docs](https://github.com/smart-dato/correos-shipping-sdk)[ GitHub Sponsors](https://github.com/SmartDato)[ RSS](/packages/smart-dato-correos-shipping-sdk/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (4)Dependencies (30)Versions (12)Used By (0) Correos Shipping SDK ==================== [](#correos-shipping-sdk) [![Latest Version on Packagist](https://camo.githubusercontent.com/4c503763f7b41f275c53f29881a8765fbf70734d91d3a018071e10befbcccc1e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736d6172742d6461746f2f636f7272656f732d7368697070696e672d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/smart-dato/correos-shipping-sdk)[![GitHub Tests Action Status](https://camo.githubusercontent.com/5c5b227d395062574fb2423c5dd618d26a3e0b0e40a39006e5c755971115e4fb/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f736d6172742d6461746f2f636f7272656f732d7368697070696e672d73646b2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/smart-dato/correos-shipping-sdk/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/f55215f6b0622143fc47867de93ef045ad93c797044a827aa80061b4e6e2d51c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f736d6172742d6461746f2f636f7272656f732d7368697070696e672d73646b2f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/smart-dato/correos-shipping-sdk/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/f8879a80afe44148a95c34262a26ad627afa4d2dae28f1fecbecfd64312723d3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f736d6172742d6461746f2f636f7272656f732d7368697070696e672d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/smart-dato/correos-shipping-sdk) Laravel package for integrating with the Correos (Spanish postal service) APIs. Supports shipment preregistration, label and customs document generation, and tracking. Built on [Saloon 3.x](https://docs.saloon.dev) for HTTP and [Spatie Laravel Data 4.x](https://spatie.be/docs/laravel-data) for DTOs. Requirements ------------ [](#requirements) - PHP 8.4+ - Laravel 11 or 12 Installation ------------ [](#installation) Install the package via Composer: ``` composer require smart-dato/correos-shipping-sdk ``` Publish the config file: ``` php artisan vendor:publish --tag="correos-shipping-sdk-config" ``` Configuration ------------- [](#configuration) Add the following environment variables to your `.env` file: ``` # OAuth credentials (CorreosID) CORREOS_OAUTH_CLIENT_ID=your-oauth-client-id CORREOS_OAUTH_CLIENT_SECRET=your-oauth-client-secret # API Gateway credentials CORREOS_GATEWAY_CLIENT_ID=your-gateway-client-id CORREOS_GATEWAY_CLIENT_SECRET=your-gateway-client-secret ``` The published config file (`config/correos-shipping-sdk.php`) contains all available options: ``` return [ 'oauth' => [ 'client_id' => env('CORREOS_OAUTH_CLIENT_ID'), 'client_secret' => env('CORREOS_OAUTH_CLIENT_SECRET'), 'token_url' => env('CORREOS_TOKEN_URL', 'https://apioauthcid.correos.es/Api/Authorize/Token'), 'scope' => env('CORREOS_OAUTH_SCOPE', 'AP3 LBS RCG'), ], 'gateway' => [ 'client_id' => env('CORREOS_GATEWAY_CLIENT_ID'), 'client_secret' => env('CORREOS_GATEWAY_CLIENT_SECRET'), ], 'base_urls' => [ 'preregister' => env('CORREOS_PREREGISTER_URL', 'https://api1.correos.es/admissions/preregister/api/v1'), 'labels' => env('CORREOS_LABELS_URL', 'https://api1.correos.es/support/labels/api/v1'), 'tracking' => env('CORREOS_TRACKING_URL', 'https://api1.correos.es/support/trackpub/api/v2'), ], 'verify_ssl' => env('CORREOS_VERIFY_SSL', true), 'force_ip_resolve' => env('CORREOS_FORCE_IP_RESOLVE'), ]; ``` For the **pre-production** environment, override the URLs: ``` CORREOS_TOKEN_URL=https://apioauthcid.correospre.es/Api/Authorize/Token CORREOS_PREREGISTER_URL=https://api1.correospre.es/admissions/preregister/api/v1 CORREOS_LABELS_URL=https://api1.correospre.es/support/labels/api/v1 CORREOS_TRACKING_URL=https://api1.correospre.es/support/trackpub/api/v2 ``` If the pre-production environment uses self-signed certificates, you can disable SSL verification: ``` CORREOS_VERIFY_SSL=false ``` > **Warning:** Never disable SSL verification in production. If the pre-production environment only allows IPv4 connections (e.g., CloudFront blocks IPv6), you can force IPv4 resolution: ``` CORREOS_FORCE_IP_RESOLVE=v4 ``` Usage ----- [](#usage) Resolve the SDK from the container (or use the `CorreosShipping` facade): ``` use SmartDato\CorreosShipping\CorreosShipping; $correos = app(CorreosShipping::class); ``` ### Preregister Shipments [](#preregister-shipments) ``` use SmartDato\CorreosShipping\Data\Preregister\DeliveryRequestData; $request = DeliveryRequestData::from([ 'shipments' => [ [ 'product' => 'PAFXB', 'deliveryMethod' => 'DOUAOF', 'contractNumber' => '12345678', 'clientNumber' => '1234567890', 'labellerCode' => '0001', 'packagesNumber' => '1', 'sender' => [ 'name' => 'My Company', 'address' => 'Calle Sender 1', 'locality' => 'Madrid', 'province' => '28', 'cp' => '28001', 'country' => 'ESP', ], 'addressee' => [ 'name' => 'John Doe', 'address' => 'Calle Receiver 2', 'locality' => 'Barcelona', 'province' => '08', 'cp' => '08001', 'country' => 'ESP', ], 'packages' => [ ['packageWeightGrams' => '500'], ], ], ], ]); // Validate before creating $validation = $correos->preregister()->validateShipments($request); // Create the shipment $response = $correos->preregister()->createShipments($request); $response->fileIdentifier; // "FILE001" $response->shipments[0]->shipmentCode; // "PQXYZ1234567890" $response->shipments[0]->packages[0]->packageCode; // "PQ1DR4A0000012345678" ``` ### Print Labels [](#print-labels) ``` use SmartDato\CorreosShipping\Data\Labels\PrintLabelsRequestData; $labelRequest = PrintLabelsRequestData::from([ 'documentationType' => 1, // 0=All, 1=Label, 2=CN22/CN23 'print' => [ 'shipments' => ['PQXYZ1234567890'], 'labelFormat' => 2, // 1=XML, 2=PDF, 3=ZPL 'labelPrintMode' => 1, // 1=A4, 2=Labeler ], ]); $labels = $correos->labels()->printLabels($labelRequest); $labels->pdf; // Base64-encoded PDF content ``` ### Print Customs Documents (DCAF/DDP) [](#print-customs-documents-dcafddp) ``` use SmartDato\CorreosShipping\Data\Labels\PrintDocumentsRequestData; $docRequest = PrintDocumentsRequestData::from([ 'documentationType' => 5, // 5=DCAF, 6=DDP 'documentData' => [ 'destinationName' => 'France', 'contractNumber' => '12345678', 'clientNumber' => '1234567890', ], ]); $document = $correos->labels()->printDocuments($docRequest); $document->pdf; // Base64-encoded PDF ``` ### Track Shipments [](#track-shipments) ``` $tracking = $correos->tracking()->searchShipment('PQ1DR4A0000012345678'); $tracking->code; // "PQ1DR4A0000012345678" $tracking->codProduct; // "PQDOM" $tracking->remitName; // Sender name $tracking->destiName; // Addressee name $tracking->events; // Array of TrackingEventData foreach ($tracking->events as $event) { $event->eventDate; // "06/02/2026" $event->eventCode; // "P010000V" $event->summaryText; // "Shipment preregistered" $event->location; // "CTA MADRID" } ``` ### Track Expeditions [](#track-expeditions) ``` $expedition = $correos->tracking()->getExpedition('EXP001234567890'); $expedition->refExpedition; // "EXP001234567890" $expedition->serviceDescription; // "Paq Premium" $expedition->clients; // Array of ExpeditionClientData $expedition->packages; // Array of ExpeditionPackageData ``` ### Other Preregister Operations [](#other-preregister-operations) ``` // Cancel a shipment $correos->preregister()->cancelShipment( AnnulmentRequestData::from(['packageCode' => 'PQ1DR4A0000012345678']) ); // Cancel an expedition $correos->preregister()->cancelExpedition( AnnulmentExpeditionRequestData::from(['expeditionCode' => 'EXP001234567890']) ); // Generate shipment codes $correos->preregister()->generateShipmentCode( GenerateShipmentCodeRequestData::from([ 'contractNumber' => '12345678', 'clientNumber' => '1234567890', 'labellerCode' => '0001', 'packagesNumber' => '1', 'product' => 'PAFXB', 'deliveryMethod' => 'DOUAOF', ]) ); // Modify a shipment $correos->preregister()->modifyShipment($deliveryRequestData); // Query shipments $correos->preregister()->queryShipments( QueryRequestData::from(['shipments' => ['PQ1DR4A0000012345678']]) ); // Get expedition packages $correos->preregister()->getExpeditionPackages('EXP001234567890'); // Search by client reference $correos->preregister()->getPackagesByReference('MY-REF-001'); // Backoffice queries $correos->preregister()->getBackofficeShipment('PQXYZ1234567890'); $correos->preregister()->getBackofficeErrors(contractNumber: '12345678'); $correos->preregister()->getBackofficeTotal(dateFrom: '01/01/2026', dateTo: '31/01/2026'); $correos->preregister()->getBackofficeWaiting(); ``` ### Using the Facade [](#using-the-facade) ``` use SmartDato\CorreosShipping\Facades\CorreosShipping; $response = CorreosShipping::preregister()->createShipments($request); $labels = CorreosShipping::labels()->printLabels($labelRequest); $tracking = CorreosShipping::tracking()->searchShipment('PQ1DR4A0000012345678'); ``` Available Enums --------------- [](#available-enums) The package provides typed enums for API constants: ``` use SmartDato\CorreosShipping\Enums\DocumentationType; // All, Label, CN22_CN23, DCAF, DDP use SmartDato\CorreosShipping\Enums\LabelFormat; // XML, PDF, ZPL use SmartDato\CorreosShipping\Enums\LabelPrintMode; // A4, Labeler use SmartDato\CorreosShipping\Enums\LabelOrderType; // InternationalPoBox, Company, LastName, PackageId, ClientReference use SmartDato\CorreosShipping\Enums\ShipmentType; // Documents, Goods, Gift, Samples, Returns, Other, Dangerous use SmartDato\CorreosShipping\Enums\DoiType; // European, DNI, NIE, Other, CIF use SmartDato\CorreosShipping\Enums\AdmissionMethod; // Office, Citypaq, DeliveryUnit use SmartDato\CorreosShipping\Enums\ErrorCodeLanguage; // Spanish, English ``` Error Handling -------------- [](#error-handling) API errors are thrown as `CorreosApiException`: ``` use SmartDato\CorreosShipping\Exceptions\CorreosApiException; try { $response = $correos->preregister()->createShipments($request); } catch (CorreosApiException $e) { $e->getMessage(); // Error message from the API $e->getCode(); // HTTP status code $e->errorCode; // Correos error code $e->moreInformation; // Additional error details } ``` Testing ------- [](#testing) ``` composer test # Run tests composer analyse # Static analysis (PHPStan level 5) composer format # Code style (Laravel Pint) composer test-coverage # Tests with coverage report ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](../../security/policy) on how to report security vulnerabilities. Credits ------- [](#credits) - [SmartDato](https://github.com/smart-dato) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 43 — FairBetter than 91% of packages Maintenance88 Actively maintained with recent releases Popularity16 Limited adoption so far Community9 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 66.7% 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 ~4 days Total 8 Last Release 68d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/c3006db55caec62526937fa2d941da32fc5e69e2ca86a52e87c8046da5958d82?d=identicon)[smart-dato](/maintainers/smart-dato) --- Top Contributors [![tschigo](https://avatars.githubusercontent.com/u/344100?v=4)](https://github.com/tschigo "tschigo (12 commits)")[![michael-tscholl](https://avatars.githubusercontent.com/u/178569346?v=4)](https://github.com/michael-tscholl "michael-tscholl (5 commits)")[![smartDato](https://avatars.githubusercontent.com/u/112470955?v=4)](https://github.com/smartDato "smartDato (1 commits)") --- Tags laravelSmartDatocorreos-shipping-sdk ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/smart-dato-correos-shipping-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/smart-dato-correos-shipping-sdk/health.svg)](https://phpackages.com/packages/smart-dato-correos-shipping-sdk) ``` ### Alternatives [binaryk/laravel-restify Laravel REST API helpers 651399.1k](/packages/binaryk-laravel-restify)[sunchayn/nimbus A Laravel package providing an in-browser API client with automatic schema generation, live validation, and built-in authentication with a touch of Laravel-tailored magic for effortless API testing. 29428.0k](/packages/sunchayn-nimbus)[muhammadhuzaifa/telescope-guzzle-watcher Telescope Guzzle Watcher provide a custom watcher for intercepting http requests made via guzzlehttp/guzzle php library. The package uses the on\_stats request option for extracting the request/response data. The watcher intercept and log the request into the Laravel Telescope HTTP Client Watcher. 98239.8k1](/packages/muhammadhuzaifa-telescope-guzzle-watcher)[vormkracht10/laravel-mails Laravel Mails can collect everything you might want to track about the mails that has been sent by your Laravel app. 24149.7k](/packages/vormkracht10-laravel-mails)[pdphilip/cf-request Cloudflare Laravel Request 2725.6k1](/packages/pdphilip-cf-request)[basillangevin/laravel-data-json-schemas Transforms Spatie Data objects into JSON Schemas with built-in validation 1312.2k1](/packages/basillangevin-laravel-data-json-schemas) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)