PHPackages                             novadigital/novapost-api-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. novadigital/novapost-api-sdk

ActiveLibrary[API Development](/categories/api)

novadigital/novapost-api-sdk
============================

PHP SDK for Nova Post API

1.1.0(4mo ago)2445↓50%GPL-3.0-or-laterPHPPHP >=8.0

Since Nov 10Pushed 4mo agoCompare

[ Source](https://github.com/NovaDigitalHub/novapost-api-sdk)[ Packagist](https://packagist.org/packages/novadigital/novapost-api-sdk)[ RSS](/packages/novadigital-novapost-api-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (7)Versions (3)Used By (0)

NovaPost API SDK for PHP
========================

[](#novapost-api-sdk-for-php)

This is the official PHP SDK for the [NovaPost API](https://api.novapost.com/developers/index.html). It provides a convenient and modern way to interact with the NovaPost API, allowing you to easily integrate shipping, tracking, and other services into your PHP application.

The SDK is built with modern best practices, including PSR compliance and a dependency injection container, making it flexible and easy to extend.

Installation
------------

[](#installation)

You can install the SDK via [Composer](https://getcomposer.org/):

```
composer require novadigital/novapost-api-sdk
```

Usage
-----

[](#usage)

### Initializing the Client

[](#initializing-the-client)

The easiest way to get started is by using the `NovaDigital\NovaPost\NovaPostApiFactory`. It allows you to configure and create a client instance with just a few lines of code.

```
use NovaDigital\NovaPost\NovaPostApiFactory;
use NovaDigital\NovaPost\Exception\ApiException;
use NovaDigital\NovaPost\Resources\Division;

// Your API key from your NovaPost account
$apiKey = 'YOUR_API_KEY';

try {
    $novaPostApi = (new NovaPostApiFactory())($apiKey);
    $searchParams = [
        'textSearch' => 'berlin',
        'divisionCategories' => [Division::DIVISION_CATEGORY_POSTOMAT]
    ];

    $divisions = $novaPostApi->divisions()->get($searchParams);
} catch (ApiException $e) {
    echo "API Error: " . $e->getMessage();
}
```

### Calculating Shipment Cost

[](#calculating-shipment-cost)

Here's how you can calculate the cost of a shipment:

```
try {
    $shipmentData = [
        // ... add your shipment calculation data here
    ];

    $calculationResult = $novaPostApi->shipments()->calculate($shipmentData);

    // Handle the result...

} catch (ApiException $e) {
    echo "API Error: " . $e->getMessage();
}
```

Advanced Usage: Overriding Services
-----------------------------------

[](#advanced-usage-overriding-services)

The SDK uses a PSR-11 dependency injection container, which gives you complete control over its internal components. You can replace any default service (like the logger or HTTP client) with your own implementation.

This is useful if you want to:

- Integrate the SDK with your framework's logging system.
- Customize the HTTP client with special middleware or configurations.
- Use a different JWT token storage mechanism.

To override a service, you can pass your own instance to the factory:

### Using ContainerBuilder

[](#using-containerbuilder)

For more advanced configuration, you can use the `NovaDigital\NovaPost\DI\ContainerBuilder` to customize various aspects of the client:

```
use NovaDigital\NovaPost\DI\ContainerBuilder;
use NovaDigital\NovaPost\Exception\ApiException;
use NovaDigital\NovaPost\NovaPostApiFactory;
use NovaDigital\NovaPost\Storage\JwtTokenStorageInterface;
use Psr\Http\Client\ClientExceptionInterface;
use Psr\Log\LoggerInterface;

use My\Awesome\MyLogger;
use My\Awesome\DbJwtTokenStorageProvider;

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();

$apiKey = $_ENV['API_KEY'] ?? '';
$useSandbox = (bool)($_ENV['USE_SANDBOX'] ?? true);

try {
    $containerBuilder = (new ContainerBuilder())
        ->bind(LoggerInterface::class, MyLogger::class)
        ->bind(JwtTokenStorageInterface::class, DbJwtTokenStorageProvider::class);

    $novaPostApi = (new NovaPostApiFactory())(apiKey: $apiKey, containerBuilder: $containerBuilder);

    $payload = [
        //calculation request params
    ];

    $response = $novaPostApi->shipments()->calculate($payload);
} catch (ApiException $e) {
    echo 'API Error => ' . $e->getMessage() . ' (Code => ' . $e->getCode() . ')\n';
}
```

This approach allows you to:

1. Replace any service in the dependency injection container
2. Maintain a clean, fluent interface for configuration
3. Keep your custom service implementations separate from the SDK
4. Test with mock services

### Available Service Overrides

[](#available-service-overrides)

You can override the following services using the `ContainerBuilder`:

- `Psr\Log\LoggerInterface`: For custom logging
- `Psr\Http\Client\ClientInterface`: For custom HTTP client configuration
- `NovaDigital\NovaPost\Storage\JwtTokenStorageInterface`: For custom JWT token storage
- `NovaDigital\NovaPost\Http\ResponseHandlerInterface`: For custom response handling
- `NovaDigital\NovaPost\Http\RetryHandlerInterface`: For custom retry logic

Each service can be overridden using the `bind` method on the `ContainerBuilder`.

PSR Standards Compliance
------------------------

[](#psr-standards-compliance)

This SDK adheres to the following PSR standards, ensuring interoperability and modern, high-quality code:

- **PSR-4: Autoloader**: For autoloading classes.
- **PSR-11: Container Interface**: For a flexible dependency injection container.
- **PSR-3: Logger Interface**: Allowing you to use any compatible logger.
- **PSR-7: HTTP Message Interface**: Used for all API requests and responses.
- **PSR-18: HTTP Client**: For sending HTTP requests.
- **PSR-17: HTTP Factories**: Used internally for creating PSR-7 messages.
- **PSR-12: Extended Coding Standard**: For coding styles.

This commitment to standards makes the SDK reliable, predictable, and easy to integrate into any modern PHP application.

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance75

Regular maintenance activity

Popularity19

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

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 ~48 days

Total

2

Last Release

134d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7762b4e78d05535e041c2bef4118a5d6e40eae41fa178f15faecd5ef6f50ee5a?d=identicon)[nova-poshta-global](/maintainers/nova-poshta-global)

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/novadigital-novapost-api-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/novadigital-novapost-api-sdk/health.svg)](https://phpackages.com/packages/novadigital-novapost-api-sdk)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[irazasyed/telegram-bot-sdk

The Unofficial Telegram Bot API PHP SDK

3.3k4.5M84](/packages/irazasyed-telegram-bot-sdk)[theodo-group/llphant

LLPhant is a library to help you build Generative AI applications.

1.5k311.5k5](/packages/theodo-group-llphant)[avalara/avataxclient

Client library for Avalara's AvaTax suite of business tax calculation and processing services. Uses the REST v2 API.

517.9M7](/packages/avalara-avataxclient)[alexacrm/dynamics-webapi-toolkit

Web API toolkit for Microsoft Dynamics 365 and Dynamics CRM

81324.1k1](/packages/alexacrm-dynamics-webapi-toolkit)[keboola/storage-api-client

Keboola Storage API PHP Client

10387.5k25](/packages/keboola-storage-api-client)

PHPackages © 2026

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