SDK для PHP

NovaPost API SDK

patch

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

/sdk/php

NovaPost API SDK — це офіційний PHP SDK (Software Development Kit) для інтеграції з API Nova Post. За допомогою цього пакета можна швидко та зручно підключити до PHP-застосунку такі можливості Nova Post, як створення відправлень, відстеження посилок та інші сервіси.

Можливості / переваги:

• Офіційна підтримка Nova Post — гарантована актуальність, стабільність і допомога розробникам.

• Відповідність сучасним стандартам PHP — сумісність із сучасними фреймворками та бібліотеками.

• Гнучкість і розширюваність — можливість замінити logger, HTTP client, token storage.

• Проста інтеграція — встановлення через Composer, наявні приклади використання.

Корисні посилання:

• Packagist — офіційний пакет

• GitHub-репозиторій

• Issue Tracker (підтримка та зворотний зв’язок)

Вимоги

• Основні залежності — runtime-залежності (потрібні для використання в production):

  • php >= 8.0 — пакет потребує PHP 8.0+.

  • guzzlehttp/guzzle ^7.0 — HTTP-клієнт для виконання запитів.

  • psr/container ^2.0 — сумісність із PSR dependency containers.

  • psr/log ^3.0 — інтерфейси логування, сумісні з PSR.

• Залежності для розробки — dev-залежності (потрібні лише для development/CI):

  • phpstan/phpstan ^2.1 — статичний аналіз.

  • phpunit/phpunit ^9.6 — unit-тести.

  • squizlabs/php_codesniffer ^3.13 — стиль коду / linting.

  • vlucas/phpdotenv ^5.6 — завантаження змінних середовища з .env.

• Suggests: None

• Provides: None

• Conflicts: None

• Replaces: None

Встановлення

Щоб розпочати роботу, встановіть SDK через Composer, виконавши команду:

composer require novadigital/novapost-api-sdk

Робота з SDK

Ініціалізація клієнта

Після встановлення SDK ініціалізуйте клієнт за допомогою NovaPostApiFactory. Це дозволяє швидко створити клієнт для взаємодії з API Nova Post. Додайте до свого коду такий приклад:

 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

Методи SDK мають ті самі назви та параметри, що й відповідні методи client API. Для розрахунку вартості доставки використайте такий приклад:

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

Розширені можливості

SDK дозволяє замінювати стандартні сервіси (logger, HTTP client, token storage тощо) власними реалізаціями, використовуючи dependency container ContainerBuilder.

Це корисно, якщо вам потрібно:

• Інтегрувати SDK із системою логування вашого фреймворку.

• Налаштувати HTTP-клієнт із кастомними параметрами або middleware.

• Використовувати власний механізм зберігання JWT-токенів.

Для цього передайте власні сервіси у фабрику клієнта через ContainerBuilder.

Використання ContainerBuilder

Для більш гнучкого налаштування можна використати NovaDigital\NovaPost\DI\ContainerBuilder для кастомізації різних аспектів клієнта.

 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() . ')';
} 

Доступні перевизначення сервісів

Сервіс	Призначення
Psr\Log\LoggerInterface	Кастомне логування
Psr\Http\Client\ClientInterface	Кастомна конфігурація HTTP-клієнта
NovaDigital\NovaPost\Storage\JwtTokenStorageInterface	Кастомне сховище JWT-токенів
NovaDigital\NovaPost\Http\ResponseHandlerInterface	Кастомна обробка відповідей
NovaDigital\NovaPost\Http\RetryHandlerInterface	Кастомна логіка retry

Відповідність PSR

NovaPost API SDK відповідає таким стандартам PSR, що забезпечує сумісність, сучасний дизайн і високу якість коду:

Стандарт	Призначення
PSR-4: Autoloader	Для автозавантаження класів
PSR-11: Container Interface	Для гнучкого контейнера залежностей
PSR-3: Logger Interface	Дозволяє використовувати будь-який сумісний logger
PSR-7: HTTP Message Interface	Використовується для всіх API-запитів і відповідей
PSR-18: HTTP Client	Для надсилання HTTP-запитів
PSR-17: HTTP Factories	Для створення PSR-7 повідомлень
PSR-12: Extended Coding Standard	Для стилю коду

Дотримання цих стандартів робить SDK надійним, передбачуваним і зручним для інтеграції в будь-який сучасний PHP-застосунок.

Responses

200

OK

patch

/sdk/php

HTTPcURLJavaScriptPython

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

200

OK

No content