SDK for PHP

NovaPost API SDK

patch

https://api-stage.novapost.com/v.1.0https://api.novapost.com/v.1.0

/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

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

Responses

200

OK

No content

patch

/sdk/php

HTTPcURLJavaScriptPython

PATCH /v.1.0/sdk/php HTTP/1.1
Host: api-stage.novapost.com/
Accept: */*

200

OK

No content