---
title: "NovaPost API SDK"
method: PATCH
path: "/sdk/php"
tags: ["SDK"]
---

# NovaPost API SDK

`PATCH /sdk/php`

The Novapost API SDK is the official PHP SDK (Software Development Kit) for integration with the Nova Post API. With this package, you can quickly and conveniently connect such Nova Post features to your PHP application as shipment creation, parcel tracking, and other services.

**Features/Advantages:**  

*   **Official Nova Post support** — guaranteed relevance, stability, and developer assistance.
*   **Compliance with modern PHP standards** — compatibility with modern frameworks and libraries.
*   **Flexibility and extensibility** — replace logger, HTTP client, token storage.
*   **Easy integration** — installation via Composer, example usage included.

**Useful Links:**  

*   [Packagist — Official Package](https://packagist.org/packages/novadigital/novapost-api-sdk)
*   [GitHub Repository](https://github.com/NovaDigitalHub/novapost-api-sdk)
*   [Issue Tracker (Support & Feedback)](https://github.com/NovaDigitalHub/novapost-api-sdk/issues)

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

*   **Requires** — Runtime dependencies (required for production use):
    *   `php >= 8.0` — the package requires PHP 8.0+.
    *   `guzzlehttp/guzzle ^7.0` — HTTP client for making requests.
    *   `psr/container ^2.0` — compatibility with PSR dependency containers.
    *   `psr/log ^3.0` — PSR-compliant logging interfaces.
*   **Requires (Dev)** — Dev dependencies (needed only for development/CI):
    *   `phpstan/phpstan ^2.1` — static analysis.
    *   `phpunit/phpunit ^9.6` — unit tests.
    *   `squizlabs/php_codesniffer ^3.13` — code style/linting.
    *   `vlucas/phpdotenv ^5.6` — loading environment variables from `.env`.
*   **Suggests:** None
*   **Provides:** None
*   **Conflicts:** None
*   **Replaces:** None

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

To get started, install the SDK via [Composer](https://getcomposer.org/) by running the following command:

    composer require novadigital/novapost-api-sdk

Working with the SDK
--------------------

### Client Initialization

After installing the SDK, initialize the client using `NovaPostApiFactory`.  
This allows you to quickly create a client for interacting with the Nova Post API.  
Add the following example to your code:

     use NovaDigital\NovaPost\NovaPostApiFactory; use NovaDigital\NovaPost\Exception\ApiException; use NovaDigital\NovaPost\Resources\Division;
    $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();
    } 

### SDK Method Example

SDK methods have the same names and parameters as the corresponding client API methods.  
To calculate shipment cost, use this example:

     try {
      $shipmentData = [
        // shipment calculation data
    ]; $calculationResult = $novaPostApi->shipments()->calculate($shipmentData); } catch (ApiException $e) {
      echo "API Error: " . $e->getMessage();
    } 

Advanced Features
-----------------

The SDK allows you to replace standard services (logger, HTTP client, token storage, etc.) with your own implementations using the `ContainerBuilder` dependency container.

This is useful if you need to:

*   Integrate the SDK with your framework’s logging system.
*   Configure an HTTP client with custom parameters or middleware.
*   Use your own storage mechanism for JWT tokens.

To do this, pass your custom services to the client factory through **ContainerBuilder**.

### Using ContainerBuilder

For more flexible configuration, you can use `NovaDigital\NovaPost\DI\ContainerBuilder` to customize different 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\Log\LoggerInterface; use My\Awesome\MyLogger; use My\Awesome\DbJwtTokenStorageProvider;
    $apiKey = 'YOUR_API_KEY';
    try {
      $containerBuilder = (new ContainerBuilder())
        ->bind(LoggerInterface::class, MyLogger::class)
        ->bind(JwtTokenStorageInterface::class, DbJwtTokenStorageProvider::class);
    
      $novaPostApi = (new NovaPostApiFactory())(
        apiKey: $apiKey,
        containerBuilder: $containerBuilder
      );
    
      $payload = [
        // calculation parameters
      ];
    
      $response = $novaPostApi->shipments()->calculate($payload);
    
    } catch (ApiException $e) {
        echo 'API Error => ' . $e->getMessage() . ' (Code => ' . $e->getCode() . ')';
    } 

### Available Service Overrides

With **ContainerBuilder**, you can override the following services:

Service

Purpose

Psr\\Log\\LoggerInterface

Custom logging

Psr\\Http\\Client\\ClientInterface

Custom HTTP client configuration

NovaDigital\\NovaPost\\Storage\\JwtTokenStorageInterface

Custom JWT token storage

NovaDigital\\NovaPost\\Http\\ResponseHandlerInterface

Custom response processing

NovaDigital\\NovaPost\\Http\\RetryHandlerInterface

Custom retry logic

### PSR Compliance

The **NovaPost API SDK** complies with the following PSR standards, ensuring compatibility, modern design, and high code quality:

Standard

Purpose

**PSR-4: Autoloader**

For class autoloading

**PSR-11: Container Interface**

For a flexible dependency container

**PSR-3: Logger Interface**

Allows using 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**

For creating PSR-7 messages

**PSR-12: Extended Coding Standard**

For coding style

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

## Response `200`

OK

---

[API](https://skmtc.net/novapost/apis/api-nova-post.md) · [All operations](https://skmtc.net/novapost/apis/api-nova-post/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/novapost/api-nova-post/revisions/60e380005037/schema)