PHPackages smart-dato/dhl-parcel-returns-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/dhl-parcel-returns-sdk ActiveLibrary[API Development](/categories/api) smart-dato/dhl-parcel-returns-sdk ================================= Laravel SDK for the DHL Parcel DE Returns API 0.0.1(1mo ago)010↓87.5%[1 PRs](https://github.com/smart-dato/dhl-parcel-returns-sdk/pulls)MITPHPPHP ^8.4CI passing Since Jun 4Pushed 1mo agoCompare [ Source](https://github.com/smart-dato/dhl-parcel-returns-sdk)[ Packagist](https://packagist.org/packages/smart-dato/dhl-parcel-returns-sdk)[ Docs](https://github.com/smart-dato/dhl-parcel-returns-sdk)[ GitHub Sponsors](https://github.com/SmartDato)[ RSS](/packages/smart-dato-dhl-parcel-returns-sdk/feed)WikiDiscussions main Synced 1w ago READMEChangelog (1)Dependencies (15)Versions (3)Used By (0) DHL Parcel DE Returns SDK for Laravel ===================================== [](#dhl-parcel-de-returns-sdk-for-laravel) [![Latest Version on Packagist](https://camo.githubusercontent.com/ad283e7fdfe4c4d62c488e4bbcf43c68e7824e96e24b9ec41b67e4ff9df39e77/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736d6172742d6461746f2f64686c2d70617263656c2d72657475726e732d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/smart-dato/dhl-parcel-returns-sdk)[![GitHub Tests Action Status](https://camo.githubusercontent.com/4c80642225ccb9115e22a7209924d14c51513c690447d48ec45c4e131473cf93/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f736d6172742d6461746f2f64686c2d70617263656c2d72657475726e732d73646b2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/smart-dato/dhl-parcel-returns-sdk/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/d6da5a99d13c789509c100d8ed08abc6961d023c041342694e2eb965a8b8ba2f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f736d6172742d6461746f2f64686c2d70617263656c2d72657475726e732d73646b2f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/smart-dato/dhl-parcel-returns-sdk/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/527f0dea418bbb8ff6b0c6c87cb81dcde93768e6be471578717abb46b8c61a82/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f736d6172742d6461746f2f64686c2d70617263656c2d72657475726e732d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/smart-dato/dhl-parcel-returns-sdk) A Laravel package for the [DHL Parcel DE Returns API](https://developer.dhl.com/api-reference/parcel-de-returns-post-parcel-germany). Create return labels on demand and look up return receiver locations. Built on [Saloon](https://docs.saloon.dev) and [Spatie Laravel Data](https://spatie.be/docs/laravel-data). Installation ------------ [](#installation) ``` composer require smart-dato/dhl-parcel-returns-sdk ``` Publish the config file: ``` php artisan vendor:publish --tag="dhl-parcel-returns-sdk-config" ``` Add your credentials to `.env`: ``` # OAuth2 (recommended — Basic Auth is deprecated by DHL): DHL_PARCEL_RETURNS_API_KEY=your-client-id DHL_PARCEL_RETURNS_CLIENT_SECRET=your-client-secret DHL_PARCEL_RETURNS_USERNAME=your-business-customer-username DHL_PARCEL_RETURNS_PASSWORD=your-business-customer-password # Or legacy API key only: # DHL_PARCEL_RETURNS_API_KEY=your-api-key # Or legacy Basic Auth: # DHL_PARCEL_RETURNS_USERNAME=your-username # DHL_PARCEL_RETURNS_PASSWORD=your-password # Enable sandbox for testing: # DHL_PARCEL_RETURNS_SANDBOX=true ``` OAuth2 mode is enabled automatically when `DHL_PARCEL_RETURNS_CLIENT_SECRET` is set together with the API key, username and password. The SDK then exchanges the credentials for a Bearer token against the DHL ROPC token endpoint and caches the token in memory until it expires. Usage ----- [](#usage) ### Create a return label [](#create-a-return-label) ``` use SmartDato\DhlParcelReturns\Data\Orders\ContactAddressData; use SmartDato\DhlParcelReturns\Data\Orders\ReturnOrderData; use SmartDato\DhlParcelReturns\Data\Orders\ValueData; use SmartDato\DhlParcelReturns\Data\Orders\WeightData; use SmartDato\DhlParcelReturns\Enums\Currency; use SmartDato\DhlParcelReturns\Enums\LabelType; use SmartDato\DhlParcelReturns\Enums\WeightUom; use SmartDato\DhlParcelReturns\Facades\DhlParcelReturns; $confirmation = DhlParcelReturns::orders()->create( data: new ReturnOrderData( receiverId: 'deu', shipper: new ContactAddressData( name1: 'Max Mustermann', addressStreet: 'Charles-de-Gaulle Str.', addressHouse: '20', postalCode: '53113', city: 'Bonn', email: 'max@mustermann.de', ), customerReference: 'Order #12345', itemWeight: new WeightData(WeightUom::Kilograms, 1), itemValue: new ValueData(value: 10, currency: Currency::Eur), ), labelType: LabelType::Both, ); $confirmation->shipmentNo; // "999991587211" $confirmation->label->b64; // base64-encoded shipment label $confirmation->qrLabel?->b64; // base64-encoded QR label (when requested) $confirmation->qrLink; // deep link to import the QR code into the Post & DHL app $confirmation->routingCode; // "40327653113+99000933090010" ``` ### International returns with customs (CN23) [](#international-returns-with-customs-cn23) ``` use SmartDato\DhlParcelReturns\Data\Orders\CommodityData; use SmartDato\DhlParcelReturns\Data\Orders\CustomsDetailsData; use SmartDato\DhlParcelReturns\Enums\CountryOfOrigin; $confirmation = DhlParcelReturns::orders()->create( data: new ReturnOrderData( receiverId: 'che', shipper: $shipper, itemWeight: new WeightData(WeightUom::Grams, 1200), itemValue: new ValueData(value: 1012.99), customsDetails: new CustomsDetailsData( items: [ new CommodityData( itemDescription: 'T-Shirt', packagedQuantity: 1, itemWeight: new WeightData(WeightUom::Grams, 500), itemValue: new ValueData(value: 1000), countryOfOrigin: CountryOfOrigin::FRA, hsCode: '61099090', ), ], ), ), ); ``` ### Look up return locations [](#look-up-return-locations) ``` use SmartDato\DhlParcelReturns\Enums\Country; use SmartDato\DhlParcelReturns\Facades\DhlParcelReturns; $receivers = DhlParcelReturns::locations()->get( country: Country::Deu, postalCode: '53113', maxResult: 10, ); foreach ($receivers as $receiver) { $receiver->receiverId; $receiver->billingNumber; $receiver->receiverAddress->city; } ``` All filters are optional — call `->get()` with no arguments to list every receiver configured for your account. ### API version (healthcheck) [](#api-version-healthcheck) ``` $version = DhlParcelReturns::general()->version(); $version->version; // "v1.0.0" $version->env; // "production" ``` This endpoint requires no authentication. ### Using without the Facade [](#using-without-the-facade) You can create a `DhlParcelReturns` instance directly using `DhlParcelReturns::make()`. This is useful when you prefer not to use the facade, need different credentials per request, or want to support multi-tenant setups: ``` use SmartDato\DhlParcelReturns\DhlParcelReturns; // With OAuth2 (recommended) $dhl = DhlParcelReturns::make([ 'api_key' => 'your-client-id', 'client_secret' => 'your-client-secret', 'username' => 'your-business-customer-username', 'password' => 'your-business-customer-password', 'sandbox' => true, ]); // Or with legacy API key $dhl = DhlParcelReturns::make([ 'api_key' => 'your-api-key', 'sandbox' => true, ]); $confirmation = $dhl->orders()->create($data); ``` You can also optionally pass a custom `base_url` if needed: ``` $dhl = DhlParcelReturns::make([ 'api_key' => 'your-api-key', 'base_url' => 'https://api-eu.dhl.com/parcel/de/shipping/returns/v1', ]); ``` Label types ----------- [](#label-types) EnumReturns`LabelType::ShipmentLabel`Shipment label only`LabelType::QrLabel`QR label only`LabelType::Both`Both documents (default)Error handling -------------- [](#error-handling) Any non-2xx response throws a `SmartDato\DhlParcelReturns\Exceptions\DhlParcelReturnsApiException`. It parses the DHL RFC 7807 error body, exposing the `title`/`detail` as the message and the HTTP status as the code: ``` use SmartDato\DhlParcelReturns\Exceptions\DhlParcelReturnsApiException; try { DhlParcelReturns::orders()->create($data); } catch (DhlParcelReturnsApiException $e) { $e->getMessage(); // "Unprocessable: ..." $e->getCode(); // 422 $e->detail; // RFC 7807 detail $e->instance; // RFC 7807 instance URI } ``` Testing ------- [](#testing) ``` composer test ``` 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 38 — LowBetter than 83% of packages Maintenance92 Actively maintained with recent releases Popularity6 Limited adoption so far Community6 Small or concentrated contributor base Maturity42 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 Unknown Total 1 Last Release 50d 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 (2 commits)") --- Tags laravelsaloonshippingdhlSmartDatoreturnsdhl-parcel ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/smart-dato-dhl-parcel-returns-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/smart-dato-dhl-parcel-returns-sdk/health.svg)](https://phpackages.com/packages/smart-dato-dhl-parcel-returns-sdk) ``` ### Alternatives [codebar-ag/laravel-docuware DocuWare integration with Laravel 1123.7k](/packages/codebar-ag-laravel-docuware)[rawilk/profile-filament-plugin Profile & MFA starter kit for filament. 3914.8k](/packages/rawilk-profile-filament-plugin)[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)