a-posokhov/russianpost-sdk

Russian Post (pochta.ru) SDK

dev-master 2024-08-16 10:27 UTC

Requires

• php: >=7.1
• ext-intl: *
• ext-json: *
• ext-soap: *
• guzzlehttp/guzzle: ^6.3
• psr/log: ^1.1

Requires (Dev)

• illuminate/support: 5.1 - 5.8
• monolog/monolog: ^1.25
• phpunit/phpunit: ^7.5
• symfony/var-dumper: ^4.3

Suggests

• monolog/monolog: Для логирования и отладки

MIT

• Roman Sokharev
• JhaoDa

• delivery
• russian post
• pochta
• Почта России
• служба доставки

README

Содержание

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

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

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

Установка

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

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

composer require appwilio/russianpost-sdk

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

Логирование

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

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

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

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

$this->app->singleton('appwilio.russianpost.logger', 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'),
    ],
]
// ...

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

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

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

Если инфрмации по ШПИ (трек-комеру) не найдено, то выбрасывается исключение 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
}

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

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

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

$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
    }
}

Отправка

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

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

use GuzzleHttp\Client as GuzzleClient;

$dispatching = new DispatchingClient(
    new Authentication($login, $password, $token),
    new GuzzleClient()
);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

$response = $dispatching->services->checkRecipient(
    CheckRecipientRequest::create()
        ->addRecipient('123456 Москва, Варшавское шоссе, 37-45')
        ->addRecipient('654321 Владивосток, пер. Староконный, 12-98');
);

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

Документы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

$ vendor/bin/phpunit

Авторы

• greabock
• JhaoDa

Лиценция

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