chen14 Aug 5 2015 at 13:29

PHP библиотека для интеграции с API Новой Почты

8 min

30K

Привет друзья.
Хочу поделиться PHP библиотекой (SDK) для интеграции с API 2 Новой Почты (НП). Но сначала несколько слов о Новой Почте.
Новая Почта является лидером экспресс-доставки и перевозки грузов по всей Украине. В Новой Почте много услуг, что делает ее лидером на украинском рынке перевозок. Склады есть во всех городах Украины, очень быстрая курьерская служба. Основные услуги, которые компания надает: доставка и возврат грузов в розничных сетях; доставка паллетированного груза; обратная доставка,; наложенный платёж за товар; вызов машины; хранение груза; упаковка груза, доставка груза по городу и прочее. Для упрощения создание ТТН можно использовать API компании, что даст возможность оптимизировать создания ТТН.

Возможности которые дает SDK:

Работа с адресами
Работа со справочниками
Работа с контрагентами
Методы для получения печатных форм документов
Работа с реестрами экспресс-накладных
Работа с экспресс-накладными:
- создавать экспресс-накладные
- редактировать данные в созданных экспресс-накладные (до передачи отправления)
- удалять/отменять созданные экспресс-накладные (до передачи отправления)
- загружать списки документов используя фильтры
- отслеживать статусы отправления

Подключить библиотеку (SDK)

Способ 1 (composer)

Создайте файл composer.json в корне Вашeго проекта:

{
      "require": {
          "serj1chen/nova-poshta-sdk-php": "2.0.*"
      }
}

Установить composer:

$ curl -sS https://getcomposer.org/installer | php
$ php composer.phar install

Подключить автолоадер composer:

include_once "vendor/autoload.php";

Способ 2 (git)

Клонировать репозиторий:

git clone git://github.com/serj1chen/nova-poshta-sdk-php

Подключить автолоадер SDK:

include_once "nova-poshta-sdk-php/lib/NovaPoshta/bootstrap.php";

Перед тем как начать работать с SDK, нужно получить API ключ. Переходим за ссылкой https://my.novaposhta.ua, заходим под своим логином в личный кабинет. Далее п.м. Налаштування-> API 2.0. Нажимаем кнопку Створити новий ключ, копируем созданный ключ.

Настройка SDK

   use NovaPoshta\Config;

   Config::setApiKey('<Ваш ключ>');
   Config::setFormat(Config::FORMAT_JSONRPC2);
   Config::setLanguage(Config::LANGUAGE_UA);

Возможные форматы передачи данных (формат указывать в метод setFormat):

FORMAT_JSON
FORMAT_JSONRPC2 (рекомендую)
FORMAT_XML

По дефолту будет установлен формат JSONRPC2.

Работа с моделями SDK

В документации НП работа разбита на модели:

Address: модель для работы с адресами. Примеры работы с моделью
Common: модель для работы со справочниками. Примеры работы с моделью
ContactPerson: модель для создания контактного лица. Примеры работы с моделью
Counterparty: модель для работы с данными контрагента. Примеры работы с моделью
InternetDocument: модель для оформления отправлений. Примеры работы с моделью
ScanSheet: модель для работы с реестрами приема-передачи отправлений. Примеры работы с моделью

Работа с методами моделей

Работа с методами модели: save, update, delete. Заполнить модель нужными значениями и вызвать нужный метод. Пример:

    use NovaPoshta\ApiModels\Counterparty;

    $counterparty = new Counterparty();
    $counterparty->setCounterpartyProperty('Recipient');
    $counterparty->setCityRef('db5c88d0-391c-11dd-90d9-001a92567626');
    $counterparty->setCounterpartyType('PrivatePerson');
    $counterparty->setFirstName('Пилипко');
    $counterparty->setLastName('Вася');
    $counterparty->setMiddleName('Сергеевич');
    $counterparty->setPhone('+380661122333');
    $counterparty->setEmail('test@i.ua');

    $result = $counterparty->save();

Работа с статическими методами. В методы передавать объект MethodParameters:

    use NovaPoshta\ApiModels\Counterparty;
    use NovaPoshta\MethodParameters\MethodParameters;

    $data = new MethodParameters();
    $data->CounterpartyProperty = 'Recipient';
    $data->Page = 1;
    $data->CityRef = '8d5a980d-391c-11dd-90d9-001a92567626';
    $data->FindByString = 'Петр';

    $result = Counterparty::getCounterparties($data);

Или можно использовать классы MethodParameters, которые наследуются от класса MethodParameters. Классы имеют сеттеры параметров, которые можно передать статическому методу модели. Названия классов с параметрами складываются с двух частей, с названия модели (ApiModels) и названия статического метода модели. Пример использования:

    use NovaPoshta\ApiModels\Counterparty;
    use NovaPoshta\MethodParameters\MethodParameters;
    use NovaPoshta\MethodParameters\Counterparty_getCounterparties;

    $data = new Counterparty_getCounterparties();
    $data->setCounterpartyProperty('Recipient');
    $data->setPage(1);
    $data->setCityRef('8d5a980d-391c-11dd-90d9-001a92567626');
    $data->setFindByString('Петр');

    $result = Counterparty::getCounterparties($data);

Логирования запросов

Если Вам нужно логировать данные отправки/получения запросов. Нужно создать класс который наследуется от Logger.php и передать экземпляр этого класса в метод setClassLogger файла Config.php.

use NovaPoshta\Logger;
use NovaPoshta\Config;

class Logger_example extends Logger
{
    public static function setOriginalData($toData, $fromData)
    {
        // ...
    }

    public static function setData($toData, $fromData)
    {
        // ...
    }
}

Config::setClassLogger($ new Logger_example());

Метод setOriginalData: запрос/ответ API Новой Почты. Параметры: toData — запрос (тип: string); fromData — ответ (тип: string).

Метод setData: запрос/ответ API Новой Почты у формате SDK. Параметры: toData — запрос (объект: DataContainer); fromData — ответ (объект: DataContainerResponse).

Создания экспресс накладной (ТТН)

Выбираем город отправителя:

    $data = new \NovaPoshta\MethodParameters\Address_getCities();
    $data->setFindByString('Полтава');
    $result = \NovaPoshta\ApiModels\Address::getCities($data);

    $citySender = $result->data[0]->Ref;

Выбираем город получателя:

   $result = \NovaPoshta\ApiModels\Address::getCities(); // список городов

   $cityRecipient = $result->data[60]->Ref;

Выбираем тип контрагента:

    $result = \NovaPoshta\ApiModels\Common::getTypesOfCounterparties();

    $counterpartyType = $result->data[1]->Ref; // со списка выбираем тип PrivatePerson

Создаем контрагента получателя:

    $counterparty = new \NovaPoshta\ApiModels\Counterparty();
    $counterparty->setCounterpartyProperty(\NovaPoshta\ApiModels\Counterparty::RECIPIENT);
    $counterparty->setCityRef($cityRecipient);
    $counterparty->setCounterpartyType($counterpartyType);
    $counterparty->setFirstName('Пилипко');
    $counterparty->setLastName('Вася');
    $counterparty->setMiddleName('Сергеевич');
    $counterparty->setPhone('+380661122333');
    $counterparty->setEmail('test@i.ua');
    $result = $counterparty->save();

    $counterpartyRecipient = $result->data[0]->Ref;

Если нет контрагента отправителя в городе Полтава, создаем там контрагента отправителя. Контрагент создастся через несколько минут:

    $data = new \NovaPoshta\MethodParameters\Counterparty_cloneLoyaltyCounterpartySender();
    $data->setCityRef($citySender);
    $result = \NovaPoshta\ApiModels\Counterparty::cloneLoyaltyCounterpartySender($data);

Если у Вас есть контрагент отправитель, то получаем его так же как контрагента получателя, только сюда: setCounterpartyProperty передаем \NovaPoshta\ApiModels\Counterparty::SENDER. Методом cloneLoyaltyCounterpartySender можно использовать только если Вы клиент лояльности, если Вы корпоративный клиент, то у Вас уже должен быть контрагент отправитель в нужном городе.
Теперь получим контрагента отправителя:

    $data = new \NovaPoshta\MethodParameters\Counterparty_getCounterparties();
    $data->setCityRef($citySender);
    $data->setCounterpartyProperty(\NovaPoshta\ApiModels\Counterparty::SENDER);
    $result = \NovaPoshta\ApiModels\Counterparty::getCounterparties($data);

    $counterpartySender = $result->data[0]->Ref;

Получим контактных персон для контрагентов:

    $data = new \NovaPoshta\MethodParameters\Counterparty_getCounterpartyContactPersons();
    $data->setRef($counterpartySender);
    $result = \NovaPoshta\ApiModels\Counterparty::getCounterpartyContactPersons($data);

    $contactPersonSender = $result->data[0]->Ref;

    $data = new \NovaPoshta\MethodParameters\Counterparty_getCounterpartyContactPersons();
    $data->setRef($counterpartyRecipient);
    $result = \NovaPoshta\ApiModels\Counterparty::getCounterpartyContactPersons($data);

    $contactPersonRecipient = $result->data[0]->Ref;

Для контрагента отправителя получим склад отправки:

    $data = new \NovaPoshta\MethodParameters\Address_getWarehouses();
    $data->setCityRef($citySender);
    $result = \NovaPoshta\ApiModels\Address::getWarehouses($data);

    $addressSender = $result->data[5]->Ref;

Создадим адрес для получателя:

    $address = new \NovaPoshta\ApiModels\Address();
    $address->setCounterpartyRef($counterpartyRecipient);
    $address->setBuildingNumber('2/2');
    $address->setFlat('22');
    $address->setNote('Первый подъезд');
    $address->setStreetRef('c55c9056-4148-11dd-9198-001d60451983');
    $result = $address->save();

    $addressRecipient = $result->data[0]->Ref;

Теперь получим тип услуги:

    $result = \NovaPoshta\ApiModels\Common::getServiceTypes();

    $serviceType = $result->data[3]->Ref; // Выбрали: WarehouseDoors

Выбираем плательщика:

    $result = \NovaPoshta\ApiModels\Common::getTypesOfPayers();

    $payerType = $result->data[1]->Ref; // Выбрали: Recipient

Форму оплаты:

    $result = \NovaPoshta\ApiModels\Common::getPaymentForms();
    $paymentMethod = $result->data[1]->Ref; // Выбрали: Cash

Тип груза:

    $result = \NovaPoshta\ApiModels\Common::getCargoTypes();

    $cargoType = $result->data[0]->Ref; // Выбрали: Cargo

Мы выбрали все данные которые нам нужны для создания ЭН. Создаем ЭН:

    // Контрагент отправитель
    $sender = new \NovaPoshta\Models\CounterpartyContact();
    $sender->setCity($citySender)
        ->setRef($counterpartySender)
        ->setAddress($addressSender)
        ->setContact($contactPersonSender)
        ->setPhone('+380660000000');

    // Контрагент получатель
    $recipient = new \NovaPoshta\Models\CounterpartyContact();
    $recipient->setCity($cityRecipient)
        ->setRef($counterpartyRecipient)
        ->setAddress($addressRecipient)
        ->setContact($contactPersonRecipient)
        ->setPhone('+380660000000');

    // Выбираем тип
    $result = \NovaPoshta\ApiModels\Common::getTypesOfPayersForRedelivery();
    $redeliveryPayer = $result->data[1]->Ref;

    // Выбираем тип обратной доставки
    $result = \NovaPoshta\ApiModels\Common::getBackwardDeliveryCargoTypes();
    $redeliveryCargoType = $result->data[1]->Ref;

    // Обратная доставка ценные бумаги
    $backwardDeliveryData = new \NovaPoshta\Models\BackwardDeliveryData();
    $backwardDeliveryData->setPayerType($redeliveryPayer);
    $backwardDeliveryData->setCargoType($redeliveryCargoType);
    $backwardDeliveryData->setRedeliveryString(452);

    $internetDocument = new \NovaPoshta\ApiModels\InternetDocument();
    $internetDocument->setSender($sender)
        ->setRecipient($recipient)
        ->setServiceType($serviceType)
        ->setPayerType($payerType)
        ->setPaymentMethod($paymentMethod)
        ->setCargoType($cargoType)
        ->setWeight(1)
        ->setSeatsAmount(1)
        ->setCost(452)
        ->setDescription('ТЦ')
        ->setDateTime('10.09.2015')
        ->addBackwardDeliveryData($backwardDeliveryData);
    $result = $internetDocument->save();

    $refInternetDocument = $result->data[0]->Ref;

Получить ссылку на печать ЭН:

    $data = new \NovaPoshta\MethodParameters\InternetDocument_printDocument();
    $data->addDocumentRef($refInternetDocument);
    $data->setCopies(\NovaPoshta\ApiModels\InternetDocument::PRINT_COPIES_FOURFOLD);

    $link = \NovaPoshta\ApiModels\InternetDocument::printDocument($data);

После печати ЭН, клеем ЭН на коробку и отправляем груз))

Надеюсь SDK Вам поможет интегрироваться с API Новой Почты.

Удачи!

Tags:

Hubs: