> 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/changelog-1/documentation-1/sdk-dlya-php.md).

# SDK для PHP

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

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

* Офіційна підтримка Nova Post — гарантія актуальності, стабільності та підтримки від розробників.
* Відповідність сучасним стандартам PHP — сумісність із сучасними фреймворками та бібліотеками.
* Гнучкість і можливість розширення — можливість замінити логер, HTTP-клієнт, сховище токенів.
* Простота інтеграції — встановлення через Composer, приклади використання включені.

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

* [Packagist — Офіційний Пакет](https://packagist.org/packages/novadigital/novapost-api-sdk)
* [GitHub Repository](https://github.com/NovaDigitalHub/novapost-api-sdk)
* [Issue Tracker (підтримка та зворотний зв’язок)](https://github.com/NovaDigitalHub/novapost-api-sdk/issues)

### Вимоги

* **Requires** — залежності середовища виконання (обов’язкові для використання в продуктивному середовищі):
  * `php >= 8.0` — пакет потребує PHP 8.0 або новішої версії.
  * `guzzlehttp/guzzle ^7.0` — HTTP-клієнт для виконання запитів.
  * `psr/container ^2.0` — сумісність із контейнерами залежностей PSR.
  * `psr/log ^3.0` — інтерфейси логування, сумісні з PSR.
* **Requires (Dev)** — залежності для розробки (потрібні лише для розробки та CI):
  * `phpstan/phpstan ^2.1` — статичний аналіз коду.
  * `phpunit/phpunit ^9.6` — модульне тестування.
  * `squizlabs/php_codesniffer ^3.13` — перевірка стилю коду та відповідності стандартам кодування.
  * `vlucas/phpdotenv ^5.6` — завантаження змінних середовища з файлу `.env`.
* **Suggests:** Немає
* **Provides:** Немає
* **Conflicts:** Немає
* **Replaces:** Немає

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

Щоб розпочати роботу, встановіть SDK через [Composer](https://getcomposer.org/) виконавши таку команду:

```
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 мають ті самі назви та параметри, що й відповідні методи клієнтського API.\
Для розрахунку вартості відправлення використовуйте наступний приклад:

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

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

SDK дозволяє замінювати стандартні сервіси (логер, HTTP-клієнт, сховище токенів тощо) власними реалізаціями за допомогою контейнера залежностей  `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() . ')';
} 
```

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

За допомогою `ContainerBuilder` можна перевизначати наступні сервіси:

<table><thead><tr><th width="477">Сервіс</th><th>Призначення</th></tr></thead><tbody><tr><td>Psr\Log\LoggerInterface</td><td>Custom logging</td></tr><tr><td>Psr\Http\Client\ClientInterface</td><td>Custom HTTP client configuration</td></tr><tr><td>NovaDigital\NovaPost\Storage\JwtTokenStorageInterface</td><td>Custom JWT token storage</td></tr><tr><td>NovaDigital\NovaPost\Http\ResponseHandlerInterface</td><td>Custom response processing</td></tr><tr><td>NovaDigital\NovaPost\Http\RetryHandlerInterface</td><td>Custom retry logic</td></tr></tbody></table>

#### Відповідність стандартам PSR

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

<table><thead><tr><th width="367">Стандарт</th><th>Призначення</th></tr></thead><tbody><tr><td><strong>PSR-4: Autoloader</strong></td><td>For class autoloading</td></tr><tr><td><strong>PSR-11: Container Interface</strong></td><td>For a flexible dependency container</td></tr><tr><td><strong>PSR-3: Logger Interface</strong></td><td>Allows using any compatible logger</td></tr><tr><td><strong>PSR-7: HTTP Message Interface</strong></td><td>Used for all API requests and responses</td></tr><tr><td><strong>PSR-18: HTTP Client</strong></td><td>For sending HTTP requests</td></tr><tr><td><strong>PSR-17: HTTP Factories</strong></td><td>For creating PSR-7 messages</td></tr><tr><td><strong>PSR-12: Extended Coding Standard</strong></td><td>For coding style</td></tr></tbody></table>

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


---

# 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/changelog-1/documentation-1/sdk-dlya-php.md?ask=<question>
```

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.