appwilio / russianpost-sdk
Russian Post (pochta.ru) SDK
Installs: 14 905
Dependents: 0
Suggesters: 0
Security: 0
Stars: 45
Watchers: 7
Forks: 17
Open Issues: 6
Requires
- php: >=7.1
- ext-intl: *
- ext-json: *
- ext-soap: *
- guzzlehttp/guzzle: ^6.3
- psr/log: ^1.1
Requires (Dev)
- illuminate/support: ^5.8|^6.0|^7.0
- monolog/monolog: ^1.25|^2.0
- phpunit/phpunit: ^7.5
- symfony/var-dumper: ^4.3
Suggests
- monolog/monolog: Для логирования и отладки
README
Содержание
- Установка
- Трекинг
- Единичный доступ
- информация о наложенном платеже
- Пакетный доступ
- Единичный доступ
- Отправка
- Расчёт стоимости пересылки
- Получение баланса
- Нормализация и валидация данных
- Документы
- Форма Ф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
Авторы
Лиценция
Данный SDK распространяется под лицензией MIT.