> For the complete documentation index, see [llms.txt](https://api-portal.novapost.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-portal.novapost.com/metodi-1/metodi/readme/sdk-dlya-php.md). # SDK для PHP ## NovaPost API SDK > \

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

\ > \ > \Можливості / переваги:\\\ > \ > \Корисні посилання:\\
\\ > \ > \

Вимоги\

\ > \ > \\ > \ > \

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

\ > \ > Щоб розпочати роботу, встановіть SDK через \ href="" target="\_new">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\.\ > \

\ > \ > \

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

\ > \ > \\ > \ > \

\ > Для цього передайте власні сервіси у фабрику клієнта через\ > \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-застосунок.
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"SDK"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"paths":{"/sdk/php":{"patch":{"tags":["SDK"],"summary":"NovaPost API SDK","description":"

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

\n\nМожливості / переваги:\n\nКорисні посилання:
\n\n

Вимоги

\n\n\n\n

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

\n\nЩоб розпочати роботу, встановіть SDK через Composer, виконавши\nкоманду:\n\n
composer require novadigital/novapost-api-sdk
\n\n

Робота з SDK

\n\n

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

\n\nПісля встановлення SDK ініціалізуйте клієнт за допомогою\nNovaPostApiFactory.
Це дозволяє швидко створити клієнт\nдля взаємодії з API Nova Post.
Додайте до свого коду такий приклад:\n\n
 use NovaDigital\\NovaPost\\NovaPostApiFactory; use\nNovaDigital\\NovaPost\\Exception\\ApiException; use\nNovaDigital\\NovaPost\\Resources\\Division;\n\n$apiKey = 'YOUR_API_KEY';\n\ntry {\n  $novaPostApi = (new NovaPostApiFactory())($apiKey);\n  $searchParams = [\n    'textSearch' => 'berlin',\n    'divisionCategories' => [Division::DIVISION_CATEGORY_POSTOMAT]\n  ];\n  $divisions = $novaPostApi->divisions()->get($searchParams);\n} catch (ApiException $e) {\n    echo \"API Error: \" . $e->getMessage();\n}
\n\n

Приклад методу SDK

\n\nМетоди SDK мають ті самі назви та параметри, що й відповідні методи\nclient API.
Для розрахунку вартості доставки використайте такий\nприклад:\n\n
 try {\n  $shipmentData = [\n    // shipment calculation data\n  ];\n  $calculationResult = $novaPostApi->shipments()->calculate($shipmentData);\n} catch (ApiException $e) {\n  echo \"API Error: \" . $e->getMessage();\n}
\n\n

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

\n\n

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

\n\n

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

\n\n
    \n
  • Інтегрувати SDK із системою логування вашого фреймворку.
    • \n
  • Налаштувати HTTP-клієнт із кастомними параметрами або middleware.
    • \n
  • Використовувати власний механізм зберігання JWT-токенів.
    • \n
\n\n

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

\n\n

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

\n\n

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

\n\n
 use NovaDigital\\NovaPost\\DI\\ContainerBuilder; use\nNovaDigital\\NovaPost\\Exception\\ApiException; use\nNovaDigital\\NovaPost\\NovaPostApiFactory; use\nNovaDigital\\NovaPost\\Storage\\JwtTokenStorageInterface; use\nPsr\\Log\\LoggerInterface; use My\\Awesome\\MyLogger; use\nMy\\Awesome\\DbJwtTokenStorageProvider;\n\n$apiKey = 'YOUR_API_KEY';\n\ntry {\n  $containerBuilder = (new ContainerBuilder())\n    ->bind(LoggerInterface::class, MyLogger::class)\n    ->bind(JwtTokenStorageInterface::class, DbJwtTokenStorageProvider::class);\n\n  $novaPostApi = (new NovaPostApiFactory())(\n    apiKey: $apiKey,\n    containerBuilder: $containerBuilder\n  );\n\n  $payload = [\n    // calculation parameters\n  ];\n\n  $response = $novaPostApi->shipments()->calculate($payload);\n\n} catch (ApiException $e) {\n    echo 'API Error => ' . $e->getMessage() . ' (Code => ' . $e->getCode() . ')';\n}
\n\n

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

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

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

\n\nNovaPost API SDK відповідає таким стандартам PSR, що забезпечує\nсумісність, сучасний дизайн і високу якість коду:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
СтандартПризначення
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Для стилю коду
\n\nДотримання цих стандартів робить SDK надійним, передбачуваним і зручним\nдля інтеграції в будь-який сучасний PHP-застосунок.\n","responses":{"200":{"description":"OK"}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api-portal.novapost.com/metodi-1/metodi/readme/sdk-dlya-php.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.