SDK для бизнес-сервисов Почты России

Содержание

• Установка
• Трекинг
  • Единичный доступ
    • информация о наложенном платеже
  • Пакетный доступ
• Отправка
  • Расчёт стоимости пересылки
  • Получение баланса
  • Нормализация и валидация данных
    • ФИО
    • Адреса
    • Телефоны
    • Проверка благонадёжности получателя
  • Документы
    • Форма Ф7п для заказа
    • Форма Ф112ЭК для заказа
    • Пакет документов для заказа (до формирования партии)
    • Пакет документов для заказа (после формирования партии)
    • Пакет документов для партии
    • Акт осмотра содержимого партии
    • Форма Ф103 для партии
    • Генерация возвратного ярлыка на одной печатной странице
    • Подготовка и отправка электронной формы Ф103 для партии
  • Настройки пользователя
  • Заказы
    • Создание
    • Поиск по идентификатору магазина
    • Поиск по идентификатору Почты России
    • Редактирование
    • Удаление
    • Возврат в «Новые»
  • Партии
    • Создание партии заказов
    • Изменение дня отправки партии в ОПС
    • Перенос заказов в партию
    • Добавление заказов в партию
    • Удаление заказов из партии
    • Запрос данных о заказах в партии
    • Поиск партии по наименованию
    • Поиск всех партий
    • Поиск заказов по ШПИ
    • Поиск заказа по идентификатору Почты России
  • Архив
    • Запрос данных о партиях
    • Перевод партии в архив
    • Возврат партии из архива
  • Поиск ОПС
    • По индексу
    • По адресу
    • По координатам
    • Поиск индексов в населённом пункте
    • Почтовые сервисы ОПС
    • Почтовые сервисы ОПС по идентификатору группы сервисов
    • Выгрузка из паспорта ОПС
  • Долгосрочное хранение
    • Запрос данных о заказах

Работа с API пакетного трекинга и API отправки возможна только при наличии договора с Почтой России.

Работа с API единичного трекинга возможна как с договором, так и после простой регистрации (но с лимитом — 100 запросов в сутки).

Установка

Минимальные требования — PHP 7.1+, ext-soap, ext-json.

Для установки используйте менеджер пакетов Composer:

composer require appwilio/russianpost-sdk

При использовании фреймворка Laravel SDK автоматически регистрирует доступные сервисы.

Минимальная версия Laravel — 5.8.

Логирование

Для логирования запросов и ответов можно подключить любой логгер, реализующий стандарт PSR-3, например, Monolog:

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$log = (new Logger('pochta.ru'))
    ->pushHandler(new StreamHandler('path/to/your.log', Logger::INFO));

// SingleAccessClient, PacketAccessClient, DispatchingClient
$client->setLogger($log);

В случае использования фреймворка Laravel следует добавить логгер в контейнер под именем appwilio.russianpost.logger:

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$this->app->singleton('appwilio.russianpost.logger', static function () {
    return (new Logger('pochta.ru'))
        ->pushHandler(new StreamHandler('path/to/your.log', Logger::INFO));
});

Трекинг

Документация

Конфигурация в Laravel

Добавьте следющие ключи в services.php:

// ...
'russianpost' => [
    'tracking' => [
        'login' => \env('RUSSIAN_POST_TRACKING_LOGIN'),
        'password' => \env('RUSSIAN_POST_TRACKING_PASSWORD'),
    ],
],
// ...

Не забудьте перегенерировать кэш настроек, если они были закэшированы!

Единичный доступ

Конструктор класса SingleAccessClient принимает два параметра — логин и пароль от личного кабинета на сайте Почты России.

use Appwilio\RussianPostSDK\Tracking\SingleAccessClient;

$tracker = new SingleAccessClient($login = 'login', $password = 'secret');

Если информации по ШПИ (трек-комеру) не найдено, то выбрасывается исключение Appwilio\RussianPostSDK\Tracking\Exceptions\SingleAccessException с соответствующим сообщением.

Получение данных по ШПИ (трек-комеру)

$response = $tracker->getTrackingEvents('29014562148754');

Объект $response реализует интерфейс \IteratorAggregate, поэтому его можно сразу перебирать в цикле:

foreach ($response as $events) {
    $parameters = $events->getOperationParameters();
    
    echo $parameters->getOperationId();
    echo $parameters->getAttributeId();
    echo $parameters->getPerformedAt()->format('d.m.Y в h:i:s'); // 17.09.2019 в 17:20:48
}

Получение информации о наложенном платеже по ШПИ (трек-комеру)

$response = $tracker->getCashOnDeliveryEvents('29014562148754');

Объект $response реализует интерфейс \IteratorAggregate, поэтому его можно сразу перебирать в цикле:

foreach ($response as $event) {
    $parameters = $event->getOperationParameters();
    
    echo $parameters->getTransferNumber();
    echo $parameters->getPayment(); // 7410
    echo $parameters->getPerformedAt()->format('d.m.Y в h:i:s'); // 17.09.2019 в 17:20:48
}

Пакетный доступ

use Appwilio\RussianPostSDK\Tracking\PacketAccessClient;

$tracker = new PacketAccessClient($login = 'login', $password = 'secret');

Получение данных по ШПИ (трек-комеру)

$ticket = $tracker->getTicket(['29014562148754', 'RA325487125CN']); // максимум 3 000 треков

Рекомендуется подождать 15 минут перед запросом информации.

$response = $tracker->getTrackingEvents($ticket->getId());

echo $response->getPreparedAt()->format('d.m.Y в h:m:s');

Объект $response реализует интерфейс \IteratorAggregate, поэтому его можно сразу перебирать в цикле:

foreach ($response as $item) {
    echo $item->getBarcode();
    
    foreach ($item as $events) {
        echo $events->getOperationId();
        echo $events->getAttributeId();
        echo $events->getPerformedAt()->format('d.m.Y в h:m:s'); // 17.09.2019 в 17:20:48
    }
}

Отправка

Документация

Конфигурация

Конструктор класса DispatchingClient принимает три обязательных параметра: логин и пароль от личного кабинета на сайте Почты России, а так же токен доступа, который высылается на почту при подключении сервиса «Отправка» и может быть изменён в личном кабинете.

use GuzzleHttp\Client as GuzzleClient;
use Appwilio\RussianPostSDK\Dispatching\DispatchingClient;

$dispatching = new DispatchingClient(
    $login = 'login', $password = 'secret', $token = 'QWERTY', new GuzzleClient()
);

Конфигурация в Laravel

Добавьте следющие ключи в services.php:

// ...
'russianpost' => [
    'dispatching' => [
        'token' => \env('RUSSIAN_POST_DISPATCHING_TOKEN'),
        'login' => \env('RUSSIAN_POST_TDISPATCHING_LOGIN'),
        'password' => \env('RUSSIAN_POST_DISPATCHING_PASSWORD'),
        'guzzle' => [
            'timeout' => 5,
        ],
    ],
],
// ...

Не забудьте перегенерировать кэш настроек, если они были закэшированы!

Расчёт стоимости пересылки

use Appwilio\RussianPostSDK\Dispatching\Enum\MailType;
use Appwilio\RussianPostSDK\Dispatching\Enum\MailCategory;
use Appwilio\RussianPostSDK\Dispatching\Enum\MailEntryType;
use Appwilio\RussianPostSDK\Dispatching\Endpoints\Services\Requests\CalculationRequest;

$response = $dispatching->services->calculate(
    CalculationRequest::create('123456', 200)
        ->ofMailType(MailType::PARCEL_POSTAL())
        ->ofMailCategory(MailCategory::ORDINARY())
        ->ofEntriesType(MailEntryType::GOODS())
        ->fragile()
        ->withSmsNotice()
);

echo $response->getTotal()->getRate();
echo $response->getTotal()->getVAT(); // НДС

Нормализация и валидация данных

Нормализация ФИО

use Appwilio\RussianPostSDK\Dispatching\Endpoints\Services\Requests\NormalizeFioRequest;

$response = $dispatching->services->normalizeFio(
    NormalizeFioRequest::one('иванов иван иванович')
);

if ($response[0]->isUseful()) {
    echo $response[0]->getFirstName().' '.$response[0]->getLastName(); // Иван Иванов
}

Нормализация адресов

use Appwilio\RussianPostSDK\Dispatching\Endpoints\Services\Requests\NormalizeAddressRequest;

$response = $dispatching->services->normalizeAddress(
    NormalizeAddressRequest::one('Москва варшавское шоссе 37-45')
);

Нормализация телефонов

use Appwilio\RussianPostSDK\Dispatching\Endpoints\Services\Requests\NormalizePhoneRequest;

$response = $dispatching->services->normalizePhone(NormalizePhoneRequest::one('89001234567'));

Проверка благонадёжности получателя

use Appwilio\RussianPostSDK\Dispatching\Endpoints\Services\Requests\CheckRecipientRequest;

$response = $dispatching->services->checkRecipient(
    CheckRecipientRequest::one('Москва, Варшавское шоссе, 37-45', 'Иванов Иван Иванович', '+7 123 456-78-90')
);

$response[0]->isFraud(); // ненадёжный
$response[0]->isReliable(); // надёжный

use Appwilio\RussianPostSDK\Dispatching\Endpoints\Services\Requests\CheckRecipientRequest;

$request = CheckRecipientRequest::create();
$request->addRecipient('123456 Москва, Варшавское шоссе, 37-45', 'Иванов Иван Иванович', '+7 123 456-78-90');

$response = $dispatching->services->checkRecipient($request);

foreach ($response as $recipient) {
    echo $recipient->getAddress.': '.$recipient->isReliable();
}

Документы

$file = $dispatching->documents->orderF7Form('12345678');

echo $file->getClientFilename(); // f7p.pdf

// Сохранение
$file->moveTo("storage/printforms/12345678-{$file->getClientFilename()}");

// Перенаправление в браузер (Laravel)
return \response()->streamDownload(staticfunction () use ($file) {
    (string) $file->getStream();
}, $file->getClientName(), ['Content-Type' => $file->getClientMediaType()]);

Форма Ф7п для заказа

use Appwilio\RussianPostSDK\Dispatching\Enum\PrintType;

$pdf = $dispatching->documents->orderF7Form(
    '12345678', new \DateTime('2019-01-01'), PrintType::PAPER()
);

Форма Ф112ЭК для заказа

$pdf = $dispatching->documents->orderF112Form('12345678', new \DateTime('2019-01-01'));

Пакет документов для заказа (до формирования партии)

$zip = $dispatching->documents->orderFormsBundleBacklog('12345678', new \DateTime('2019-01-01'));

Пакет документов для заказа (после формирования партии)

use Appwilio\RussianPostSDK\Dispatching\Enum\PrintType;

$zip = $dispatching->documents->orderFormBundle(
    '12345678', new \DateTime('2019-01-01'), PrintType::THERMO()
);

Пакет документов для партии

$zip = $dispatching->documents->batchFormBundle('87654321');

Акт осмотра содержимого партии

$pdf = $dispatching->documents->batchCheckingForm('87654321');

Форма Ф103 для партии

$pdf = $dispatching->documents->batchF103Form('87654321');

Возвратный ярлык

use Appwilio\RussianPostSDK\Dispatching\Enum\PrintType;

$pdf = $dispatching->documents->easyReturnForm('29014562148754', PrintType::THERMO());

Запуск тестов

$ vendor/bin/phpunit

Авторы

• greabock
• JhaoDa

Лиценция

Данный SDK распространяется под лицензией MIT.