PHPackages                             aunhurian/nova-poshta-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. aunhurian/nova-poshta-sdk

ActiveLibrary[API Development](/categories/api)

aunhurian/nova-poshta-sdk
=========================

PHP SDK для інтеграції з API Нової Пошти

1.0.0.3(1y ago)01MITPHPPHP ^7.4

Since Mar 29Pushed 1y ago1 watchersCompare

[ Source](https://github.com/AUnhurian/nova-poshta-sdk)[ Packagist](https://packagist.org/packages/aunhurian/nova-poshta-sdk)[ Docs](https://github.com/aunhurian/nova-poshta-sdk)[ RSS](/packages/aunhurian-nova-poshta-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (5)Versions (4)Used By (0)

Nova Poshta SDK для PHP
=======================

[](#nova-poshta-sdk-для-php)

PHP SDK для інтеграції з API Нової Пошти

[![PHP Version](https://camo.githubusercontent.com/204b1791e3a57f86a93de1422b2a6e584f5045431629c5b9abd4e28dbc8b5357/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344372e342d626c75652e737667)](https://www.php.net/)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE)

Вимоги
------

[](#вимоги)

- PHP 7.4 або вище
- Composer

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

[](#встановлення)

```
composer require aunhurian/nova-poshta-sdk
```

Або клонуйте репозиторій:

```
git clone https://github.com/aunhurian/nova-poshta-sdk.git
cd nova-poshta-sdk
composer install
```

Швидкий старт
-------------

[](#швидкий-старт)

```
// Створення екземпляру SDK
$apiKey = 'ваш_api_ключ';
$sdk = new \AUnhurian\NovaPoshta\SDK\NovaPoshtaSDK($apiKey);

// Отримання списку міст
$cities = $sdk->address()->getCities(null, 'Київ');

// Параметри для пошуку відділень
$warehouseParams = [
    'FindByString' => 'Відділення'
    // інші параметри
];

// Отримання списку відділень
$warehouses = $sdk->address()->getWarehouses(
    '8d5a980d-391c-11dd-90d9-001a92567626',
    'Відділення',
    1,
    20
);

// Відстеження посилки
$trackingInfo = $sdk->tracking()->getStatusDocuments('59000000000000');
```

Документація API Нової Пошти
----------------------------

[](#документація-api-нової-пошти)

Цей SDK базується на офіційному API Нової Пошти. Детальну документацію по API можна знайти за посиланням: [Документація API Нової Пошти](https://developers.novaposhta.ua/documentation)

Детальна документація SDK
-------------------------

[](#детальна-документація-sdk)

Детальний опис усіх доступних методів та їх параметрів SDK можна знайти в окремому документі: [Детальна документація API функцій SDK](API-DOCUMENTATION.md)

Структура SDK
-------------

[](#структура-sdk)

SDK розділений на модулі, кожен з яких відповідає за окрему частину API Нової Пошти:

- **AddressApi** - Робота з адресами, населеними пунктами, вулицями та відділеннями
- **CounterpartyApi** - Робота з контрагентами (клієнтами)
- **DocumentApi** - Створення, редагування та видалення накладних (ТТН)
- **TrackingApi** - Відстеження статусу посилок
- **CommonApi** - Отримання довідкової інформації

Детальний опис модулів
----------------------

[](#детальний-опис-модулів)

### AddressApi

[](#addressapi)

```
// Отримання списку областей
$areas = $sdk->address()->getAreas();

// Пошук населених пунктів
$settlements = $sdk->address()->searchSettlements('Київ');

// Отримання списку міст з фільтрацією
$cities = $sdk->address()->getCities(null, 'Київ', 1, 20);

// Отримання списку відділень
$warehouses = $sdk->address()->getWarehouses(
    '8d5a980d-391c-11dd-90d9-001a92567626',
    'Відділення',
    1,
    20
);

// Отримання типів відділень
$warehouseTypes = $sdk->address()->getWarehouseTypes();

// Отримання вулиць у місті
$streets = $sdk->address()->getStreet('city_ref', 'Хрещатик', 1, 10);
```

### CounterpartyApi

[](#counterpartyapi)

```
// Створення нового контрагента (фізична особа)
$counterparty = $sdk->counterparty()->save(
    'PrivatePerson',
    'Іван',
    'Петренко',
    'Васильович',
    '380991234567',
    'test@example.com'
);

// Створення нового контрагента (організація)
$counterparty = $sdk->counterparty()->save(
    'Organization',
    null,
    null,
    null,
    null,
    null,
    'ТОВ "Компанія"',
    '12345678'
);

// Пошук контрагентів
$counterparties = $sdk->counterparty()->getCounterparties(null, 'Пет', 1, 10);

// Отримання контактних осіб контрагента
$contactPersons = $sdk->counterparty()->getCounterpartyContactPersons(
    '005056801329',
    'Recipient'
);
```

### DocumentApi

[](#documentapi)

```
// Розрахунок вартості доставки
$cost = $sdk->document()->getDocumentPrice(
    '8d5a980d-391c-11dd-90d9-001a92567626',
    'db5c88de-391c-11dd-90d9-001a92567626',
    '1',
    'WarehouseWarehouse',
    500,
    1,
    1
);

// Розрахунок дати доставки
$date = $sdk->document()->getDocumentDeliveryDate(
    '8d5a980d-391c-11dd-90d9-001a92567626',
    'db5c88de-391c-11dd-90d9-001a92567626',
    'WarehouseWarehouse',
    '01.01.2023'
);

// Отримання списку накладних
$documents = $sdk->document()->getDocumentList(
    '01.01.2023',
    '01.02.2023',
    1,
    100
);

// Створення нової накладної (спрощений приклад)
$document = $sdk->document()->save([
    'PayerType' => 'Sender',
    'PaymentMethod' => 'Cash',
    'CargoType' => 'Cargo',
    'Weight' => 1,
    'ServiceType' => 'WarehouseWarehouse',
    'SeatsAmount' => 1,
    'Description' => 'Опис вантажу',
    'Cost' => 500,
    'CitySender' => '8d5a980d-391c-11dd-90d9-001a92567626',
    'Sender' => '5ace4a2e-13ee-11e5-add9-005056887b8d',
    'SenderAddress' => '2a8c3606-ab5b-11e9-8094-005056881c6b',
    'ContactSender' => '57b4218d-16d7-11e5-add9-005056887b8d',
    'SendersPhone' => '380991234567',
    'CityRecipient' => 'db5c88de-391c-11dd-90d9-001a92567626',
    'Recipient' => '7da56392-b64b-11e4-a77a-005056887b8d',
    'RecipientAddress' => '7da56392-b64b-11e4-a77a-005056887b8d',
    'ContactRecipient' => '57b4218d-16d7-11e5-add9-005056887b8d',
    'RecipientsPhone' => '380991234567',
]);
```

### TrackingApi

[](#trackingapi)

```
// Отримання статусу одного відправлення
$status = $sdk->tracking()->getStatusDocuments('59000000000000');

// Отримання статусу декількох відправлень
$statuses = $sdk->tracking()->getStatusDocumentsBatch([
    ['DocumentNumber' => '59000000000000'],
    ['DocumentNumber' => '59000000000001'],
]);

// Отримання повної історії відправлення
$history = $sdk->tracking()->getStatusHistory('59000000000000');
```

### CommonApi

[](#commonapi)

```
// Отримання типів вантажу
$cargoTypes = $sdk->common()->getCargoTypes();

// Отримання списку типів оплати
$paymentTypes = $sdk->common()->getTypesOfPayment();

// Отримання списку типів платників
$payerTypes = $sdk->common()->getTypesOfPayers();

// Отримання списку типів послуг
$serviceTypes = $sdk->common()->getServiceTypes();

// Отримання часових інтервалів доставки
$timeIntervals = $sdk->common()->getTimeIntervals(
    'db5c88de-391c-11dd-90d9-001a92567626',
    '01.01.2023'
);
```

Клас відповіді API
------------------

[](#клас-відповіді-api)

SDK містить клас `NovaPoshtaResponse` для роботи з відповідями API Нової Пошти. За замовчуванням SDK повертає тільки дані з відповіді, але ви можете отримати повний об'єкт відповіді, що містить додаткову інформацію:

```
// Отримання повної відповіді API
$response = $sdk->requestWithFullResponse('Address', 'getAreas', []);

// Отримання даних з відповіді
$data = $response->getData();

// Перевірка статусу відповіді
$isSuccess = $response->isSuccess();

// Отримання попереджень
$warnings = $response->getWarnings();

// Отримання інформаційних повідомлень
$info = $response->getInfo();

// Отримання статус-коду HTTP
$statusCode = $response->getStatusCode();

// Отримання сирих даних відповіді
$rawData = $response->getRawData();
```

Ви також можете використовувати прямий запит до API замість модульних методів:

```
// Пряме використання API через SDK
$cities = $sdk->request('Address', 'getCities', ['FindByString' => 'Київ']);

// Пряме використання API з повною відповіддю
$response = $sdk->requestWithFullResponse('Address', 'getCities', ['FindByString' => 'Київ']);
$cities = $response->getData();
```

Внесок у розробку
-----------------

[](#внесок-у-розробку)

Ми вітаємо внески від спільноти! Якщо ви хочете покращити SDK:

1. Форкніть репозиторій
2. Клонуйте його локально
3. Внесіть зміни
4. Відправте Pull Request

Детальні інструкції щодо внеску у розробку можна знайти у файлі [CONTRIBUTING.md](CONTRIBUTING.md).

Тестування
----------

[](#тестування)

SDK має повний набір тестів для перевірки функціональності. Щоб запустити тести, використовуйте:

```
# Запуск тестів з PHPUnit
vendor/bin/phpunit
```

Тести організовані за модулями API та використовують мокування HTTP-запитів для симуляції роботи з API Нової Пошти без фактичних мережевих запитів.

Детальний опис системи тестування можна знайти в [TESTING.md](TESTING.md).

Використання фейкових відповідей у ваших тестах
-----------------------------------------------

[](#використання-фейкових-відповідей-у-ваших-тестах)

SDK надає механізм для налаштування фейкових відповідей API для ваших інтеграційних тестів. Це може бути корисно, коли ви хочете протестувати взаємодію вашого додатку з API Нової Пошти без виконання реальних API-запитів.

```
// Створення екземпляру SDK
$sdk = new \AUnhurian\NovaPoshta\SDK\NovaPoshtaSDK('your_api_key');

// Налаштування фейкових відповідей
$mockResponses = [
    // Фейкова відповідь для запиту getAreas
    'Address.getAreas' => [
        'response' => [
            'success' => true,
            'data' => [
                [
                    'Ref' => '71508128-9b87-11de-822f-000c2965ae0e',
                    'Description' => 'Київська область',
                    'AreasCenter' => '8d5a980d-391c-11dd-90d9-001a92567626',
                ]
            ],
            'errors' => [],
            'warnings' => [],
            'info' => [],
        ],
    ],

    // Фейкова відповідь з перевіркою параметрів
    'Address.getCities' => [
        // Це спрацює тільки якщо параметри включають 'FindByString' => 'Київ'
        'params' => [
            'FindByString' => 'Київ',
        ],
        'response' => [
            'success' => true,
            'data' => [
                [
                    'Ref' => '8d5a980d-391c-11dd-90d9-001a92567626',
                    'Description' => 'Київ',
                ]
            ],
            'errors' => [],
            'warnings' => [],
            'info' => [],
        ],
    ],

    // Фейкова відповідь для невдалого запиту
    'Address.getWarehouses' => [
        'response' => [
            'success' => false,
            'data' => [],
            'errors' => ['Помилка API'],
            'warnings' => [],
            'info' => [],
        ],
        'statusCode' => 400,
    ],
];

// Встановлення фейкових відповідей
$sdk->setMockResponses($mockResponses);

// Тепер SDK буде використовувати фейкові відповіді замість реальних API-запитів
$areas = $sdk->address()->getAreas();
// $areas буде містити фейкові дані

// Для запитів з перевіркою параметрів
$cities = $sdk->address()->getCities(null, 'Київ');
// $cities буде містити фейкові дані, оскільки параметри збігаються

// Очищення фейкових відповідей для повернення до нормальної поведінки
$sdk->clearMockResponses();
```

Система фейкових відповідей підтримує зіставлення параметрів, що дозволяє визначати різні відповіді на основі вхідних параметрів. Це особливо корисно для тестування різних сценаріїв з одним і тим же методом API.

Кожна фейкова відповідь повинна бути структурована наступним чином:

- Використовуйте `'response'` для визначення повної структури відповіді (включаючи `success`, `data`, `errors` і т.д.)
- Опціонально використовуйте `'params'` для визначення параметрів, які повинні збігатися для використання цієї фейкової відповіді
- Опціонально встановіть `'statusCode'` (за замовчуванням 200), щоб симулювати різні HTTP-статуси

При використанні цієї функції у ваших тестах рекомендується завжди очищати фейкові відповіді після кожного тесту, щоб переконатися, що тести не впливають один на одного.

Винятки
-------

[](#винятки)

SDK використовує систему виключень для обробки помилок:

- `NovaPoshtaApiException` - Виключення, що виникає при помилках в API Нової Пошти
- `NovaPoshtaHttpException` - Виключення, що виникає при HTTP-помилках

```
try {
    $result = $sdk->address()->getAreas();
} catch (AUnhurian\NovaPoshta\SDK\Exceptions\NovaPoshtaApiException $e) {
    // Помилка API Нової Пошти
    echo "API помилка: " . $e->getMessage();
} catch (AUnhurian\NovaPoshta\SDK\Exceptions\NovaPoshtaHttpException $e) {
    // HTTP помилка (мережева помилка)
    echo "HTTP помилка: " . $e->getMessage();
} catch (Exception $e) {
    // Інші помилки
    echo "Помилка: " . $e->getMessage();
}
```

Ліцензія
--------

[](#ліцензія)

Цей проект ліцензований за ліцензією MIT - дивіться файл [LICENSE](LICENSE) для деталей.

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance46

Moderate activity, may be stable

Popularity1

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

407d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/20e46394c7c08adc5cb6d13e0d23b601a1aed6fa9b1ebc05926f80a89fac0aad?d=identicon)[ELWAHAB](/maintainers/ELWAHAB)

---

Top Contributors

[![AUnhurian](https://avatars.githubusercontent.com/u/25745274?v=4)](https://github.com/AUnhurian "AUnhurian (20 commits)")

---

Tags

apisdknova poshtaНова Поштановапоштаapi клієнт

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/aunhurian-nova-poshta-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/aunhurian-nova-poshta-sdk/health.svg)](https://phpackages.com/packages/aunhurian-nova-poshta-sdk)
```

###  Alternatives

[openai-php/laravel

OpenAI PHP for Laravel is a supercharged PHP API client that allows you to interact with the Open AI API

3.7k7.6M74](/packages/openai-php-laravel)[saloonphp/saloon

Build beautiful API integrations and SDKs with Saloon

2.4k9.6M468](/packages/saloonphp-saloon)[hubspot/api-client

Hubspot API client

23414.2M16](/packages/hubspot-api-client)[php-opencloud/openstack

PHP SDK for OpenStack APIs. Supports BlockStorage, Compute, Identity, Images, Networking and Metric Gnocchi

2292.2M24](/packages/php-opencloud-openstack)[mailchimp/transactional

458.9M16](/packages/mailchimp-transactional)[resend/resend-php

Resend PHP library.

564.7M21](/packages/resend-resend-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)