PHPackages                             maxs94/internetmarke-rest-php - 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. maxs94/internetmarke-rest-php

ActiveLibrary[API Development](/categories/api)

maxs94/internetmarke-rest-php
=============================

Deutsche Post INTERNETMARKE REST client for PHP

v1.0.6(1mo ago)3102MITPHPPHP ^8.1CI passing

Since Jan 5Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/maxs94/internetmarke-rest-php)[ Packagist](https://packagist.org/packages/maxs94/internetmarke-rest-php)[ RSS](/packages/maxs94-internetmarke-rest-php/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (7)Dependencies (12)Versions (8)Used By (0)

Deutsche Post Internetmarke REST Client for PHP
===============================================

[](#deutsche-post-internetmarke-rest-client-for-php)

A modern PHP 8.1+ REST client for the Deutsche Post Internetmarke API. Create postage labels, access Portokasse, and integrate Internetmarke into your PHP applications.

[![Packagist Version](https://camo.githubusercontent.com/4a186238152db94e48d9bc0be24fa1a61c4c7b0c64fa388784a0cc333f9388eb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d61787339342f696e7465726e65746d61726b652d726573742d706870)](https://packagist.org/packages/maxs94/internetmarke-rest-php)[![PHP 8.1+](https://camo.githubusercontent.com/f695c08717b8c4e2dc50c0d326c81a37352934425837367f54d64818864d3c25/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6d61787339342f696e7465726e65746d61726b652d726573742d706870)](https://packagist.org/packages/maxs94/internetmarke-rest-php)[![License: MIT](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](LICENSE)[![Tests](https://github.com/maxs94/internetmarke-rest-php/actions/workflows/tests.yml/badge.svg)](https://github.com/maxs94/internetmarke-rest-php/actions/workflows/tests.yml)[![PHPStan](https://github.com/maxs94/internetmarke-rest-php/actions/workflows/phpstan.yml/badge.svg)](https://github.com/maxs94/internetmarke-rest-php/actions/workflows/phpstan.yml)

- [DHL Developer Portal](https://developer.dhl.com/api-reference/deutsche-post-internetmarke-post-paket-deutschland)
- [Portokasse](https://portokasse.deutschepost.de/portokasse/)

---

Install
-------

[](#install)

```
composer require maxs94/internetmarke-rest-php
```

---

Quick example
-------------

[](#quick-example)

```
use Maxs94\Internetmarke\Internetmarke;
use Maxs94\Internetmarke\Model\{Address, Position, ShoppingCartPDFRequest, ShoppingCartPosition};

$im  = new Internetmarke('client-id', 'client-secret', 'username', 'password');
$app = $im->getAppResource();

$cart   = $app->createShoppingCart();
$sender = (new Address())->setName('Max Mustermann')->setAddressLine1('Musterstraße 1')
            ->setPostalCode('94032')->setCity('Passau')->setCountry('DEU');
$receiver = (new Address())->setName('Erika Mustermann')->setAddressLine1('Beispielgasse 7')
            ->setPostalCode('10115')->setCity('Berlin')->setCountry('DEU');

$result = $app->checkoutShoppingCartAsPDF(
    (new ShoppingCartPDFRequest())
        ->setShopOrderId($cart->getShopOrderId())
        ->setTotal(95)  // euro cents
        ->setPositions([
            (new ShoppingCartPosition())
                ->setProductCode(68)  // Kompaktbrief
                ->setVoucherLayout(ShoppingCartPosition::VOUCHER_LAYOUT_ADDRESS_ZONE)
                ->setPosition(new Position(1, 1, 1))
                ->setSender($sender)
                ->setReceiver($receiver),
        ])
);

file_put_contents('stamp.pdf', file_get_contents($result->getLink()));
```

See the [`examples/`](examples/) directory for runnable scripts.

---

Features
--------

[](#features)

FeatureThis libraryAuto-generated SDKSOAP libsREST API✅✅❌PHP 8.1+ native✅✅✅Lightweight (1 dep)✅❌✅Typed DTOs✅✅✅Input validation✅❌❌Token auto-refresh✅❌N/APDF labels✅✅✅PNG labels✅✅✅Portokasse wallet✅✅✅Retoure (refunds)✅✅✅---

API coverage
------------

[](#api-coverage)

EndpointMethodPHP`GET /`Health check`ApiVersionResource::getVersion()``POST /user`Authenticatehandled internally by `TokenProvider``GET /user/profile`User profile`UserResource::getUserProfile()``PUT /app/wallet`Charge wallet`AppResource::chargeWallet(int $amount)``POST /app/shoppingcart`Create cart`AppResource::createShoppingCart()``GET /app/shoppingcart/{shopOrderId}`Retrieve cart`AppResource::getShoppingCart(string $shopOrderId)``POST /app/shoppingcart/pdf`Checkout PDF`AppResource::checkoutShoppingCartAsPDF(...)``POST /app/shoppingcart/png`Checkout PNG`AppResource::checkoutShoppingCartAsPNG(...)``GET /app/retoure`Retoure state`AppResource::getRetoure(...)``POST /app/retoure`Request retoure`AppResource::setRetoure(RetoureVouchersRequest $r)``GET /app/catalog`Catalog`AppResource::getCatalog(array $types)`---

Requirements
------------

[](#requirements)

- PHP 8.1+
- Composer
- GuzzleHTTP 7+ (pulled in automatically)

---

Usage
-----

[](#usage)

### Authentication

[](#authentication)

```
use Maxs94\Internetmarke\Internetmarke;

$im = new Internetmarke(
    clientId:     'your-client-id',
    clientSecret: 'your-client-secret',
    username:     'your-username',
    password:     'your-password',
);

// API version / health check
$version = $im->getApiVersionResource()->getVersion();
echo $version->getVersion(); // e.g. v1.1.4

// User profile
$profile = $im->getUserResource()->getUserProfile();
echo $profile->getFirstname() . ' ' . $profile->getLastname();
```

### Creating a PDF label

[](#creating-a-pdf-label)

```
use Maxs94\Internetmarke\Model\Address;
use Maxs94\Internetmarke\Model\Position;
use Maxs94\Internetmarke\Model\ShoppingCartPDFRequest;
use Maxs94\Internetmarke\Model\ShoppingCartPosition;

$app = $im->getAppResource();

// 1. Open a cart
$cart = $app->createShoppingCart();

// 2. Build the request
$request = (new ShoppingCartPDFRequest())
    ->setShopOrderId($cart->getShopOrderId())
    ->setTotal(95)  // euro cents — must match position prices
    ->setPositions([
        (new ShoppingCartPosition())
            ->setProductCode(68)
            ->setVoucherLayout(ShoppingCartPosition::VOUCHER_LAYOUT_ADDRESS_ZONE)
            ->setPosition(new Position(1, 1, 1))  // x, y, page
            ->setSender($sender)
            ->setReceiver($receiver),
    ]);

// 3. Checkout
$result = $app->checkoutShoppingCartAsPDF($request);

$pdfLink      = $result->getLink();           // link to the generated PDF
$manifestLink = $result->getManifestLink();   // posting receipt, if requested
$walletLeft   = $result->getWalletBallance(); // remaining balance in euro cents
```

For PNG labels, use `ShoppingCartPNGRequest` and `checkoutShoppingCartAsPNG()`.

Both checkout methods accept optional flags:

```
$app->checkoutShoppingCartAsPDF($request, validate: true);        // preview — no purchase
$app->checkoutShoppingCartAsPDF($request, directCheckout: true);  // skip cart step
```

### Catalog

[](#catalog)

```
use Maxs94\Internetmarke\Model\RetrieveCatalogResponse;

// motif images + product list
$catalog = $app->getCatalog([RetrieveCatalogResponse::TYPE_PUBLIC]);

// page formats (needed for PDF pageFormatId)
$formats = $app->getCatalog([RetrieveCatalogResponse::TYPE_PAGE_FORMATS]);

// both at once
$all = $app->getCatalog([
    RetrieveCatalogResponse::TYPE_PUBLIC,
    RetrieveCatalogResponse::TYPE_PAGE_FORMATS,
]);
```

### Wallet

[](#wallet)

```
$app->chargeWallet(500); // charge 5.00 EUR (amount in euro cents, minimum 1)
```

### Retoure

[](#retoure)

```
use Maxs94\Internetmarke\Model\RetoureVouchersRequest;
use Maxs94\Internetmarke\Model\ShoppingCart;
use Maxs94\Internetmarke\Model\Voucher;

// query retoure state
$state = $app->getRetoure(
    shopRetoureId:        '12345',
    startDate:            new \DateTimeImmutable('2024-01-01'),
    endDate:              new \DateTimeImmutable('2024-12-31'),
);

// request a refund
$voucher = Voucher::fromArray(['voucherId' => 'A00123C039...']);
$cart    = (new ShoppingCart())->setShopOrderId('98276337')->setVoucherList([$voucher]);

$response = $app->setRetoure((new RetoureVouchersRequest())->setShoppingCart($cart));
echo $response->getShopRetoureId();
```

---

Validation
----------

[](#validation)

All request-side models validate their fields against the OpenAPI spec constraints and throw `\InvalidArgumentException` on violation. Validation is eager — it fires in the setter, at the point of the bad assignment.

ConstraintExamplesString length`Address::setPostalCode` (exactly 5 chars), `Address::setCountry` (exactly 3), `shopOrderId` (1–18)Integer minimum`chargeWallet $amount` (≥1), `ShoppingCartPosition::productCode` (≥1), `VoucherPosition` coords (≥1)Enum`ShoppingCartPosition::voucherLayout`, `dpi`, `createShippingList`Array min items`ShoppingCart::setVoucherList` (≥1 item)---

Sandbox / custom base URI
-------------------------

[](#sandbox--custom-base-uri)

```
use Maxs94\Internetmarke\Config\ClientConfig;

$im = new Internetmarke(
    clientId:     'your-client-id',
    clientSecret: 'your-client-secret',
    username:     'your-username',
    password:     'your-password',
    config:       new ClientConfig('https://api-eu.dhl.com/post/de/shipping/im/v1'),
);
```

The default base URI points to production. Pass a `ClientConfig` with a different URL for sandbox testing.

---

Architecture
------------

[](#architecture)

```
src/
├── Authentication/   TokenProvider — OAuth token lifecycle
├── Config/           ClientConfig  — base URI
├── Exception/        ApiException
├── Http/             ApiClient, ApiClientInterface, Serializer
├── Model/            DTOs for all request/response payloads
├── Service/          ApiVersionResource, AppResource, UserResource
└── Validator/        StringLengthValidator, IntegerMinValidator, EnumValidator

```

`TokenProvider` and `ApiClient` implement interfaces (`TokenProviderInterface`, `ApiClientInterface`), making them easy to swap in tests or for custom HTTP adapters.

---

Development
-----------

[](#development)

```
composer install

make phpunit    # run tests
make phpstan    # static analysis
make csfix      # fix code style
```

---

Contributing
------------

[](#contributing)

- Add tests for any new behaviour.
- Run `make phpunit`, `make phpstan`, and `make csfix` before opening a PR.
- Keep backward-compatibility in mind; update docs when making breaking changes.

---

License
-------

[](#license)

MIT — see [LICENSE](LICENSE).

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance92

Actively maintained with recent releases

Popularity13

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity49

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

Every ~31 days

Recently: every ~46 days

Total

7

Last Release

40d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/a638d6d04f2fe0c0a4d4ade0cfd65824128010f395a841ce46515fab0fc749b4?d=identicon)[maxs94](/maintainers/maxs94)

---

Top Contributors

[![maxs94](https://avatars.githubusercontent.com/u/12135695?v=4)](https://github.com/maxs94 "maxs94 (39 commits)")

---

Tags

api-restdeutsche-postdhl-apiinternetmarkephpportokassestamp

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/maxs94-internetmarke-rest-php/health.svg)

```
[![Health](https://phpackages.com/badges/maxs94-internetmarke-rest-php/health.svg)](https://phpackages.com/packages/maxs94-internetmarke-rest-php)
```

###  Alternatives

[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3661.3M49](/packages/tencentcloud-tencentcloud-sdk-php)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

353.6k](/packages/eslazarev-wildberries-sdk)[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k832.6k55](/packages/neuron-core-neuron-ai)[files.com/files-php-sdk

Files.com PHP SDK

2482.9k](/packages/filescom-files-php-sdk)[volcengine/volcengine-php-sdk

119.5k](/packages/volcengine-volcengine-php-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)