Skip to content

Latest commit

 

History

History
277 lines (257 loc) · 11.5 KB

README.ua.md

File metadata and controls

277 lines (257 loc) · 11.5 KB
Raw

Документация на русском языке доступна по ссылке

Build Status

Nova Poshta API 2.0

Клас надає доступ до функцій API 2.0 служби доставки Нова Пошта

Підготовка

Отримання ключа API

Для використання API потрібно:

Після отримання ключа API надається можливість використовувати всі методи класу офіційний сайт з документації

Установка останньої версії класу для роботи з API

Git

Необхідно виконати в командному рядку

git clone https://github.com/lis-dev/nova-poshta-api-2

Composer

Необхідно створити файл composer.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

require __DIR__ . '/vendor/autoload.php';

Підключення класа за альтернативній установці

require '<path_to_dir>/src/Delivery/NovaPoshtaApi2.php';

Створення екземпляру класа

Клас знаходиться в namespace \LisDev\Delivery. При створенні екземпляру класу необхідно або використовувати Full Qualified Class Name:

$np = new \LisDev\Delivery\NovaPoshtaApi2('Ваш_ключ_API_2.0');

або вказати namespace що використовується у секції use:

use LisDev\Delivery\NovaPoshtaApi2;
...
$np = new NovaPoshtaApi2('Ваш_ключ_API_2.0');

Більш детальну інформацію по роботі з namespace можно отримати на сайті документації php

Створення екземпляра класу (з розширеними параметрами)

Якщо потрібно отримувати дані на мові, відмінної від російської, виключати Exception при помилці запросу, або за відсутності установленої бібліотеки curl на сервері

$np = new NovaPoshtaApi2(
	'Ваш_ключ_API_2.0',
	'ru', // Мова повертаємих даних: ru (default) | ua | en
	FALSE, // При помилці в запросі виключати Exception: FALSE (default) | TRUE
	'curl' // Використовуємий механізм запросу: curl (defalut) | file_get_content
);

Отримання інформації про статус трек-номеру

$result = $np->documentsTracking('59000000000000');

Отримання термінів доставки

// Отримання коду міста за його назвою та області
$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);

Отримання вартості доставки

// Отримання коду міста за його назвою та області
$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);

Генерація нової поштової накладної

// Перед генерацією ЕН необхідно отримати дані відправника
// Отримання всіх відправників
$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,
            )
        )
    )
);

Отримання складів в зазначеному місті

// В параметрах вказується місто і область (для більш точного пошуку)
$city = $np->getCity('Киев', 'Киевская');
$result = $np->getWarehouses($city['data'][0]['Ref']);

Виклик довільного метода

$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