diff --git a/README.md b/README.md index 291dad0..8b3459d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +Документація українською мовою доступна [за посиланням](https://github.com/lis-dev/nova-poshta-api-2/blob/master/README.ua.md) + [![Build Status](https://travis-ci.com/lis-dev/nova-poshta-api-2.svg?branch=master)](https://travis-ci.com/lis-dev/nova-poshta-api-2) # Nova Poshta API 2.0 diff --git a/README.ua.md b/README.ua.md new file mode 100644 index 0000000..61b3cde --- /dev/null +++ b/README.ua.md @@ -0,0 +1,277 @@ +Документация на русском языке доступна [по ссылке](https://github.com/lis-dev/nova-poshta-api-2/blob/master/README.md) + +[![Build Status](https://travis-ci.com/lis-dev/nova-poshta-api-2.svg?branch=master)](https://travis-ci.com/lis-dev/nova-poshta-api-2) + +# Nova Poshta API 2.0 +Клас надає доступ до функцій API 2.0 служби доставки Нова Пошта + +# Підготовка +## Отримання ключа API +Для використання API потрібно: +* зареєструватися на сайті [Нової Пошти](https://novaposhta.ua) +* На [сторінці налаштувань](https://my.novaposhta.ua/settings/index#apikeys) в особистому кабінеті сгенерувати ключ для роботи з API + +Після отримання ключа API надається можливість використовувати всі методи класу [офіційний сайт з документації](https://my.novaposhta.ua/data/API2-200215-1622-28.pdf) + +## Установка останньої версії класу для роботи з API +### Git +Необхідно виконати в командному рядку +```git +git clone https://github.com/lis-dev/nova-poshta-api-2 +``` +### Composer +Необхідно створити файл ``composer.json`` з наступним змістом +```json +{ + "require": { + "lis-dev/nova-poshta-api-2": "~0.1.0" + } +} +``` +і запустити з командного рядку команду ``php composer.phar install`` чи ``php composer.phar update`` +Або виконати в командному рядку +``` +composer require lis-dev/nova-poshta-api-2 +``` +### Альтернативна установка +Необхідно завантажити архів за посиланням +``` +https://github.com/lis-dev/nova-poshta-api-2/archive/master.zip +``` +# Формати даних +Для вхідних даних використовуються PHP масиви, відповідь сервера може бути отримана в форматі: +* як PHP масив +* JSON +* XML + +# Використання +## Підключення класу при установці через composer +```php +require __DIR__ . '/vendor/autoload.php'; +``` + +## Підключення класа за альтернативній установці +```php +require '/src/Delivery/NovaPoshtaApi2.php'; +``` + +## Створення екземпляру класа +Клас знаходиться в namespace `\LisDev\Delivery`. При створенні екземпляру класу необхідно +або використовувати Full Qualified Class Name: +```php +$np = new \LisDev\Delivery\NovaPoshtaApi2('Ваш_ключ_API_2.0'); +``` +або вказати namespace що використовується у секції use: +```php +use LisDev\Delivery\NovaPoshtaApi2; +... +$np = new NovaPoshtaApi2('Ваш_ключ_API_2.0'); +``` + +Більш детальну інформацію по роботі з namespace можно отримати [на сайті документації php](https://www.php.net/manual/ru/language.namespaces.rationale.php) + +## Створення екземпляра класу (з розширеними параметрами) +Якщо потрібно отримувати дані на мові, відмінної від російської, виключати Exception при помилці запросу, або за відсутності установленої бібліотеки curl на сервері +```php +$np = new NovaPoshtaApi2( + 'Ваш_ключ_API_2.0', + 'ru', // Мова повертаємих даних: ru (default) | ua | en + FALSE, // При помилці в запросі виключати Exception: FALSE (default) | TRUE + 'curl' // Використовуємий механізм запросу: curl (defalut) | file_get_content +); +``` + +## Отримання інформації про статус трек-номеру +```php +$result = $np->documentsTracking('59000000000000'); +``` + +## Отримання термінів доставки +```php +// Отримання коду міста за його назвою та області +$sender_city = $np->getCity('Белгород-Днестровский', 'Одесская'); +$sender_city_ref = $sender_city['data'][0]['Ref']; +// Отримання коду міста за його назвою та області +$recipient_city = $np->getCity('Киев', 'Киевская'); +$recipient_city_ref = $recipient_city['data'][0]['Ref']; +// Дата відправки вантажу +$date = date('d.m.Y'); +// Отримання приблизної дати прибуття вантажу між складами в різних містах +$result = $np->getDocumentDeliveryDate($sender_city_ref, $recipient_city_ref, 'WarehouseWarehouse', $date); +``` +## Отримання вартості доставки +```php +// Отримання коду міста за його назвою та області +$sender_city = $np->getCity('Белгород-Днестровский', 'Одесская'); +$sender_city_ref = $sender_city['data'][0]['Ref']; +// Отримання коду міста за його назвою та області +$recipient_city = $np->getCity('Киев', 'Киевская'); +$recipient_city_ref = $recipient_city['data'][0]['Ref']; +// Вага вантажу +$weight = 7; +// Ціна в грн +$price = 5450; +// Отримання вартості доставки вантажу з зазначеною вагою та вартістю між складами в різних містах +$result = $np->getDocumentPrice($sender_city_ref, $recipient_city_ref, 'WarehouseWarehouse', $weight, $price); +``` +## Генерація нової поштової накладної +```php +// Перед генерацією ЕН необхідно отримати дані відправника +// Отримання всіх відправників +$senderInfo = $np->getCounterparties('Sender', 1, '', ''); +// Вибір відправника у конкретному місті (у цьому випадку - першому за списком) +$sender = $senderInfo['data'][0]; +// Інформація склада відправника +$senderWarehouses = $np->getWarehouses($sender['City']); +// Генерація нової ЕН +$result = $np->newInternetDocument( + // Дані відправника + array( + // Дані користувача + 'FirstName' => $sender['FirstName'], + 'MiddleName' => $sender['MiddleName'], + 'LastName' => $sender['LastName'], + // Замість FirstName, MiddleName, LastName можна ввести зареєстровані ПІБ відправника чи найменування фірми для юридичних особ + // (можна отримати за допомогою методу getCounterparties('Sender', 1, '', '')) + // 'Description' => $sender['Description'], + // Необов'язкове поле, у випадку відсутності будуть використовуватися з даних контакта + // 'Phone' => '0631112233', + // Місто відправлення + // 'City' => 'Белгород-Днестровский', + // Область відправлення + // 'Region' => 'Одесская', + 'CitySender' => $sender['City'], + // Відділення відправника по ID (у цьому випадку - перше у списку) + 'SenderAddress' => $senderWarehouses['data'][0]['Ref'], + // Відділення за адресою + // 'Warehouse' => $senderWarehouses['data'][0]['DescriptionRu'], + ), + // Дані отримувача + array( + 'FirstName' => 'Сидор', + 'MiddleName' => 'Сидорович', + 'LastName' => 'Сиродов', + 'Phone' => '0509998877', + 'City' => 'Киев', + 'Region' => 'Киевская', + 'Warehouse' => 'Отделение №3: ул. Калачевская, 13 (Старая Дарница)', + ), + array( + // Дата відправлення + 'DateTime' => date('d.m.Y'), + // Тип доставки, додатково - getServiceTypes() + 'ServiceType' => 'WarehouseWarehouse', + // Тип оплати, додатково - getPaymentForms() + 'PaymentMethod' => 'Cash', + // Хто сплачує доставку + 'PayerType' => 'Recipient', + // Вартість вантажу в грн + 'Cost' => '500', + // Кількість місць + 'SeatsAmount' => '1', + // Опис вантажу + 'Description' => 'Кастрюля', + // Тип доставки, додатково - getCargoTypes + 'CargoType' => 'Cargo', + // Вага вантажу + 'Weight' => '10', + // Об'єм вантажу в м^3 + 'VolumeGeneral' => '0.5', + // Зворотня доставка + 'BackwardDeliveryData' => array( + array( + // Хто оплачує зворотню доставку + 'PayerType' => 'Recipient', + // Тип доставки + 'CargoType' => 'Money', + // Значення зворотньої доставки + 'RedeliveryString' => 4552, + ) + ) + ) +); +``` +## Отримання складів в зазначеному місті +```php +// В параметрах вказується місто і область (для більш точного пошуку) +$city = $np->getCity('Киев', 'Киевская'); +$result = $np->getWarehouses($city['data'][0]['Ref']); +``` +## Виклик довільного метода +```php +$result = $np + ->model('Имя_модели') + ->method('Имя_метода') + ->params(array( + 'Имя_параметра_1' => 'Значение_параметра_1', + 'Имя_параметра_2' => 'Значение_параметра_2', + )) + ->execute(); +``` + +# Реалізовані методи для роботи з моделями + +## Модель InternetDocument +* save +* update +* delete +* getDocumentPrice +* getDocumentDeliveryDate +* getDocumentList +* getDocument +* printDocument +* printMarkings +* documentsTracking +* newInternetDocument +* generateReport + +## Модель Counterparty +* save +* update +* delete +* cloneLoyaltyCounterpartySender +* getCounterparties +* getCounterpartyAddresses +* getCounterpartyContactPersons +* getCounterpartyByEDRPOU +* getCounterpartyOptions + +## Модель ContactPerson +* save +* update +* delete + +## Модель Address +* save +* update +* delete +* getCities +* getStreet +* getWarehouses +* getAreas +* findNearestWarehouse + +## Модель Common +* getTypesOfCounterparties +* getBackwardDeliveryCargoTypes +* getCargoDescriptionList +* getCargoTypes +* getDocumentStatuses +* getOwnershipFormsList +* getPalletsList +* getPaymentForms +* getTimeIntervals +* getServiceTypes +* getTiresWheelsList +* getTraysList +* getTypesOfPayers +* getTypesOfPayersForRedelivery + +# Тести +Актуальні тести та приклади використання класу знаходяться у файлі `tests/NovaPoshtaApi2Test.php` + +Для запуску тестів локально необхідно виконати в командному рядку +``` +composer install +NOVA_POSHTA_API2_KEY=Ваш_ключ_API_2.0 vendor/phpunit/phpunit/phpunit tests +```