NovaPost API SDK

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
• GitHub Repository
• Issue Tracker (Support & Feedback)

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 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.