Почта россии api коды ошибок


Latest Stable Version
Total Downloads
License
Telegram Chat

SDK для интеграции с программным комплексом Почты России.

Посмотреть все проекты или подарить автору кофе можно тут.

Содержание

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

Changelog

  • 0.9.21 — Обновлены зависимости psr/log, решение issue #46, актуализирован список статусов отправлений, добавлены новые конечные статусы Почты России;
  • 0.9.20 — Исправлена совместимость с PHP 8.2 и добавлена поддержка Guzzle 7.5 в зависимостях Composer. За исправление спасибо NickMitin;
  • 0.9.19 — Добавлена поддержка Guzzle 7.4 в зависимостях Composer;
  • 0.9.18 — Испралвена передача ecom-data. За исправление спасибо Stanislav Naumuk;
  • 0.9.17 — Испралвены ошибки в сеттерах у Item.php. За исправление спасибо SERGEY;
  • 0.9.16 — Актуализированы свойства вложения в заказ. За исправление спасибо SERGEY;
  • 0.9.15 — Добавлена возможность задать таймаут в тарификаторе. За исправление спасибо DarWiM;
  • 0.9.14 — Добавлена поддержка Guzzle 7.3 в зависимостях Composer;
  • 0.9.13 — Добавлено поле комментарий к заказу при создании заказа V1 и V2;
  • 0.9.12 — Исправлена ошибка с отсутствующим $result->historyRecord в ответе API Почты. За исправление спасибо Nikita Burichenko;
  • 0.9.11 — Добавлена поддержка Guzzle 7.2 в зависимостях Composer;
  • 0.9.10 — Добавлена поддержка флага useOnlineBalance в методе отправки электронной формы Ф103;
  • 0.9.9 — Исправлена ошибка при переключении клиента в трекинге. За исправление спасибо Alliance-X;
  • 0.9.8 — Исправлены функции для работы с ОПС. За обнаружение и исправление спасибо Sergey Voronov;
  • 0.9.7 — Исправлена работы GET методов API. За обнаружение спасибо GrayWolfy;
  • 0.9.6 — Добавлена функция создания заказа V2 с возвратом ШК и номеров клиентской ИС, спасибо GrayWolfy за помощь;
  • 0.9.5 — Актуализирован список статусов отправления, изменено поведение пакетного трекинга, подробнее тут;
  • 0.9.4 — Добавлена поддержка Guzzle 7.1 в зависимостях Composer;
  • 0.9.3 — Добавлена поддержка Guzzle 7 в зависимостях Composer;
  • 0.9.2 — У заказа у вложений в декларацию добавлено новое поле trademark (Торговая марка), спасибо PankovAlxndr за актуализацию;
  • 0.9.1 — Актуализация списка статусов отправления, добавлена генерация печатных форм для заказа до формирования партии, подробнее тут;
  • 0.9.0 — Актуализация списка статусов отправления, легкий возврат, выгрузка из паспорта ОПС, подробнее тут;
  • 0.8.6 — Исправление ошибки API отправки с desc в ответе вместо sub-code;
  • 0.8.5 — Зависимость с Guzzle 6.3+ вместо строгой 6.3;
  • 0.8.3 — Доработана поддержка расчета тарифов для посылок EKOM, спасибо Konstantin Shevsky за доработку;
  • 0.8.2 — Актуализированы параметры запроса и ответа тарификатора, за актуализацию выражаем благодарность Konstantin Shevsky;
  • 0.8.1 — Добавлена функция получения списка ПВЗ для ЕКОМ, исправлена ошибка создания http-клиента к API;
  • 0.8.0 — Описание можно посмотреть тут;
  • 0.7.4 — Добавлено сохранение ошибок расчета тарифа в объект CalculateInfo с разделением на сообщение и код ошибки;
  • 0.7.3 — Исправлена ошибка при сохранении документов;
  • 0.7.2 — Актуализирован список статусов отправлений Почты России;
  • 0.7.1 — Доработана генерация RussianPostException, спасибо toporchillo за исправление. Добавлена расширенная информация в логировании;
  • 0.7.0 — Описание можно посмотреть тут;
  • 0.6.6 — Исправлено формирование и проверка параметров для запроса на создание заказа;
  • 0.6.5 — Реализованы функции работы с архивом;
  • 0.6.0 — Долгожданная работа с заказами, подробнее тут;
  • 0.5.4 — Правки composer.json;
  • 0.5.3 — Описание можно посмотреть тут;
  • 0.5.2 — Исправлена ошибка получения информации о сроках доставки в формате HTML;
  • 0.5.1 — Описание можно посмотреть тут;
  • 0.5.0 — Описание можно посмотреть тут;
  • 0.4.12 — Скорректировано описание упрощенной версии расчета тарифов, добавлен метод получения списка точек сдачи;
  • 0.4.11 — Актуализирован список статусов Почты России;
  • 0.4.10 — Актуализирован расчет стоимости пересылки (Упрощенная версия), за актуализацию спасибо rik43;
  • 0.4.9 — Исправлена ошибка выставления флага isFinal в пакетном трекинге отправлений, за обнаружение спасибо Dmitry Sobchenko;
  • 0.4.8 — Изменен адрес калькулятора Почты России, старый будет отключен 01.01.2019;
  • 0.4.7 — Актуализация списка статусов;
  • 0.4.6 — Было принято решение исключить зависимость с symfony/yaml и понизить требуемую версию PHP до 5.5+. Подробнее в разделе Конфигурация;
  • 0.4.5 — Актуализация списка статусов, признак конечного статуса в пакетном трекинге;
  • 0.4.0 — Единичный и пакетный трекинг отправлений;
  • 0.3.0 — Нормализация данных, упрощенный расчет стоимости отправки;
  • 0.2.0 — Расчет стоимости отправки тарификатором Почты России.

Установка

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

composer require lapaygroup/russianpost

Тарификатор Почты России

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

Для получения списка категорий нужно вызвать метод parseToArray класса \LapayGroup\RussianPost\CategoryList

<?php
  $CategoryList = new \LapayGroup\RussianPost\CategoryList();
  $categoryList = $CategoryList->parseToArray();
?>

В $categoryList мы получим ассоциативный массив из категорий, их подкатегорий и видов почтовых отправлений с возможными опциями и списком параметров, которые нужно передать для расчета тарифа. По этим данным можно легко и быстро построить форму-калькулятор аналогичную тарификатору Почты России.

Если нужно исключить категории из выборки, то перед вызовом parseToArray вызываем метод setCategoryDelete и передаем ему массий ID категорий, которые нужно исключить.

<?php
  $CategoryList = new \LapayGroup\RussianPost\CategoryList();
  $CategoryList->setCategoryDelete([100,200,300]);
  $categoryList = $CategoryList->parseToArray();
?>

Расчет стоимости отправки

objectId, список параметров в $params и список дополнительных услуг $service берутся из массива $categoryList.

<?php
try {
  $objectId = 2020; // Письмо с объявленной ценностью
  // Минимальный набор параметров для расчета стоимости отправления
  $params = [
              'weight' => 20, // Вес в граммах
              'sumoc' => 10000, // Сумма объявленной ценности в копейках
              'from' => 109012 // Почтовый индекс места отправления
              ];

  // Список ID дополнительных услуг
  // 2 - Заказное уведомление о вручении
  // 21 - СМС-уведомление о вручении
  $services = [2,21];

  $TariffCalculation = new \LapayGroup\RussianPost\TariffCalculation();
  $calcInfo = $TariffCalculation->calculate($objectId, $params, $services);
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostTarrificatorException $e) {
    // Обработка ошибок тарификатора
    $errors = $e->getErrors(); // Массив вида [['msg' => 'текст ошибки', 'code' => код ошибки]]
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
    // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
    // Обработка нештатной ситуации
}

?>

$calcInfo — это объект класса LapayGroup\RussianPost\CalculateInfo
Доступные методы:

  • getCategoryItemId() — ID вида отправления
  • getCategoryItemName() — название вида отправления
  • getWeight() — вес отправления в граммах
  • getTransportationName() — способ пересылки
  • getPay() — итого стоимоть без НДС
  • getPayNds() — итого стоимоть c НДС
  • getPayMark() — итого стоимость при оплате марками
  • getGround() — почтовый сбор без НДС
  • getGroundNds() — почтовый сбор с НДС
  • getCover() — страхование без НДС
  • getCoverNds() — страхование с НДС
  • getService() — дополнительные услуги без НДС
  • getServiceNds() — ополнительные услуги с НДС
  • getTariffList() — массив тарифов из которых складывается итоговая стоимость доставки

Массив тарифов состоит из объектов класса LapayGroup\RussianPost\Tariff
Доступные методы:

  • getId() — ID тарифа
  • getName() — название тарифа
  • getValue() — стоимость без НДС
  • getValueNds() — стоимость с НДС
  • getValueMark() — стоимость при оплате марками

Полученная информация может быть отображена так:

Процесс тарификации:
Способ пересылки: НАЗЕМНО (код РТМ2: 1).
Плата за пересылку письма с объявленной ценностью /230/ : 106.20 с НДС
Плата за объявленную ценность /215/ : 3.54 с НДС
Заказное уведомление о вручении /213/ услуга 2: 56.64 с НДС
СМС-уведомление о вручении /119/ услуга 21: 10.00 с НДС

Результат:
Почтовый сбор: 106.20 (с НДС).
Страхование: 3.54 (с НДС).
Дополнительные услуги: 66.64 (с НДС).
Итого сумма без НДС: 149.47.
Итого сумма с НДС 18%: 176.38.

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

Для использования сервисов Почты России, не считая тарификатор, необходимы аутентификационные данные.
Их можно хранить в ассоциативном массиве или yaml-файле. В примерах ниже я буду использовать yaml-файл, а парсить его с помощью symfony/yaml.

Информацию о аутентификационных данных можно получить здесь и здесь.

На запросы к API отправки Почтой России установлены лимиты на количество запросов в сутки. Для их увеличения необходимо написать письмо на почту support.parcel@russianpost.ru.

Отладка

Для логирования запросов и ответов используется стандартный PSR-3 логгер.
Рассмотрим пример логирования используя Monolog.

<?php
    use Monolog\Logger;
    use Monolog\Handler\StreamHandler;

    $log = new Logger('name');
    $log->pushHandler(new StreamHandler('log.txt', Logger::INFO));

    // Логирование расчета тарифа
    $tariffCalculation = new \LapayGroup\RussianPost\TariffCalculation();
    $tariffCalculation->setLogger($log);

    $res = $tariffCalculation->calculate(23030, ['from' => 101000, 'to' => 101000, 'weight' => 100, 'sumoc' => 0]);


    // Логирования API отправки
    $otpravkaApi = new \LapayGroup\RussianPost\Providers\OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $otpravkaApi->setLogger($log);

    $addressList = new \LapayGroup\RussianPost\AddressList();
    $addressList->add('115551 Кширское шоссе 94-1, 1');
    $result = $otpravkaApi->clearAddress($addressList);


    // Логирование API трекинга
    $config['auth']['tracking']['login'] = 'login';
    $config['auth']['tracking']['password'] = 'password';

    $Tracking = new \LapayGroup\RussianPost\Providers\Tracking('single', $config);
    $Tracking->setLogger($log);

    $result = $Tracking->getOperationsByRpo('10944022440321');

Лог в файле выглядит так:

[2019-09-26 12:00:59] name.INFO: Russian Post Tariff API GET request /v1/calculate: from=101000&to=101000&weight=100&sumoc=0&date=20190926&object=23030&jsontext=1 [] []
[2019-09-26 12:01:04] name.INFO: Russian Post Tariff API GET response /v1/calculate: {"caption": "Ошибки тарификации", "version": "1.11.37.333", "data": {"id": 23030, "typ": 23, "cat": 3, "dir": 0, "name": "Посылка онлайн обыкновенная", "seq": 50, "date": 20190926, "date-first": 20190821}, "error": ["Неверное значение параметра \"Индекс места отправления\" (from). Не указано значение. (1301)"], "errors": [{"msg":"Неверное значение параметра \"Индекс места отправления\" (from). Не указано значение.","code":1301}]} {"Server":["nginx"],"Date":["Thu, 26 Sep 2019 12:00:53 GMT"],"Content-Type":["text/plain;charset=utf-8"],"Content-Length":["603"],"Connection":["keep-alive"],"Access-Control-Allow-Origin":["*"],"http_status":200} []

[2019-09-26 11:59:10] name.INFO: Russian Post Otpravka API POST request /1.0/tariff: {"fragile":true,"index-from":109440,"index-to":644015,"mail-category":"ORDINARY","mail-type":"POSTAL_PARCEL","mass":1000,"payment-method":"CASHLESS","with-order-of-notice":false,"with-simple-notice":false} [] []
[2019-09-26 11:59:11] name.INFO: Russian Post Otpravka API POST response /1.0/tariff: {   "delivery-time" : {     "max-days" : 3,     "min-days" : 1   },   "fragile-rate" : {     "rate" : 7075,     "vat" : 1415   },   "ground-rate" : {     "rate" : 30658,     "vat" : 6132   },   "notice-payment-method" : "CASHLESS",   "payment-method" : "CASHLESS",   "total-rate" : 30658,   "total-vat" : 6132 } {"Server":["nginx"],"Date":["Thu, 26 Sep 2019 11:59:11 GMT"],"Content-Type":["application/json;charset=UTF-8"],"Transfer-Encoding":["chunked"],"Connection":["keep-alive"],"Expires":["0"],"Cache-Control":["no-cache, no-store, max-age=0, must-revalidate"],"X-XSS-Protection":["1; mode=block"],"Pragma":["no-cache"],"X-Frame-Options":["DENY"],"X-Content-Type-Options":["nosniff"],"Strict-Transport-Security":["max-age=31536000; includeSubDomains"],"http_status":200} []

[2019-07-19 12:14:10] name.INFO: Russian Post Tracking API request:   <?xml version="1.0" encoding="UTF-8"?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:ns1="http://russianpost.org/operationhistory/data" xmlns:ns2="http://russianpost.org/operationhistory"><env:Body><ns2:getOperationHistory><ns1:OperationHistoryRequest><ns1:Barcode>10944022440321</ns1:Barcode><ns1:MessageType>0</ns1:MessageType><ns1:Language>RUS</ns1:Language></ns1:OperationHistoryRequest><ns1:AuthorizationHeader><ns1:login>login</ns1:login><ns1:password>password</ns1:password></ns1:AuthorizationHeader></ns2:getOperationHistory></env:Body></env:Envelope>  [] []

Трекинг почтовых отправлений (РПО)

Реализует функции API Почты России для работы с отправлениями.
Для работы данных функций необходим конфигурационный файл с логином и паролем от сервиса Почты России.

Для работы используется экземпляр класса LapayGroup\RussianPost\Providers\Tracking.

Входные параметры:

  • $service — Единочный (single) / Пакетный (pack);
  • $config — Массив данных для подключения к API;
  • $timeout — Таймаут HTTP соединения, по умолчанию 60 сек. (Для сервисов Почты России лучше использовать 120 сек.).

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

Метод getOperationsByRpo используется для получения информации о конкретном отправлении.
Возвращает подробную информацию по всем операциям, совершенным над отправлением.
Пример вызова:

<?php
  use Symfony\Component\Yaml\Yaml;
  use LapayGroup\RussianPost\Providers\Tracking;

  $Tracking = new Tracking('single', Yaml::parse(file_get_contents('path_to_config.yaml')));
  $result = $Tracking->getOperationsByRpo('10944022440321');
?>

$result — Массив с объектами операций над отправлением в формате Почты России.

Метод getNpayInfo позволяет получить информацию об операциях с наложенным платежом, который связан
с конкретным почтовым отправлением.

Пример вызова:

<?php
  use Symfony\Component\Yaml\Yaml;
  use LapayGroup\RussianPost\Providers\Tracking;

  $Tracking = new Tracking('single', Yaml::parse(file_get_contents('path_to_config.yaml')));
  $result = $Tracking->getNpayInfo('10944022440321');
?>

$result — Массив с объектами операций с наложенным платежом в формате Почты России.

Пакетный доступ (включается через поддержу почты или через заявку на странице трекинга)

Метод getTickets создает заявку в сервисе Почты России на предоставление информации
по всем операциям по списку отправлений. На практике сервис Почты России не может отдать ответ
по заявке с 3000 отправлений на финальной стадии из-за размера HTTP пакета, поэтому данная функция
разбивает список на части по 500 отправлений в каждой и создает по каждой заявку.

Пример вызова:

<?php
  use Symfony\Component\Yaml\Yaml;
  use LapayGroup\RussianPost\Providers\Tracking;

  $Tracking = new Tracking('pack', Yaml::parse(file_get_contents('path_to_config.yaml')));
  $result = $Tracking->getTickets(['10944022440321', '11172522364055', '10944022490302']);
?>

$result — Ассоциативный массив данных, который содержит ключи:

  • tickets — одномерный массив с номерами успешно созданных заявок
  • not_create — одномерный массив с номерами РПО, по которым не удалось создать заявку
    (на практике бывает часто, требуется повторный запрос на создание по этим РПО)
Array
(
    [not_create] => Array
        (
        )

    [tickets] => Array
        (
            [0] => 20180506151902355WANVOUGROWKXUN
        )

)

Метод getOperationsByTicket возвращает массив с информацией по отправлениям по ранее созданной заявке.

Пример вызова:

<?php
  use Symfony\Component\Yaml\Yaml;
  use LapayGroup\RussianPost\Providers\Tracking;

  $Tracking = new Tracking('pack', Yaml::parse(file_get_contents('path_to_config.yaml')));
  $result = $Tracking->getOperationsByTicket('20180506151902355WANVOUGROWKXUN');
?>

$result — Ассоциативный массив данных ключи которого — номера РПО, а значение — массив
объектов в формате Почты России расширенный свойствами:

  • OperCtgName — текстовое название подтипа операции;
  • isFinal — признак конечного статуса (после получения запрашивать статусы у этого РПО не требуется).
Array
(
    [10944022440321] => Array
        (
            [0] => stdClass Object
                (
                    [OperTypeID] => 1
                    [OperCtgID] => 2
                    [OperName] => Прием
                    [DateOper] => 28.04.2018 19:48:47
                    [IndexOper] => 109440
                    [OperCtgName] => Партионный
                    [isFinal] => false
                )

Данные

Реализует функции API Почты России для работы с данными.
Для работы данных функций необходимы аутентификационные данные. Подробнее в разделе Конфигурация.

В случае возникновеня ошибок при обмене выбрасывает исключение \LapayGroup\RussianPost\Exceptions\RussianPostException
в котором будет текст и код ошибки от API Почты России и дамп сырого ответа с HTTP-кодом.

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

Разделяет и помещает сущности переданных адресов (город, улица) в соответствующие поля возвращаемого объекта.
Параметр id (идентификатор записи) используется для установления соответствия переданных и полученных записей,
так как порядок сортировки возвращаемых записей не гарантируется. Метод автоматически ищет и возвращает индекс
близлежащего ОПС по указанному адресу.

Адрес считается корректным к отправке, если в ответе запроса:

  • quality-code=GOOD, POSTAL_BOX, ON_DEMAND или UNDEF_05;
  • validation-code=VALIDATED, OVERRIDDEN или CONFIRMED_MANUALLY.

Пример вызова:

<?php
  use Symfony\Component\Yaml\Yaml;
  use LapayGroup\RussianPost\Providers\OtpravkaApi;

  try {
      $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));

      $addressList = new \LapayGroup\RussianPost\AddressList();
      $addressList->add('115551 Кширское шоссе 94-1, 1');
      $result = $otpravkaApi->clearAddress($addressList);

      /*
      Array
      (
          [0] => Array
              (
                  [address-type] => DEFAULT
                  [corpus] => 1
                  [house] => 94
                  [id] => 0
                  [index] => 115551
                  [original-address] => 115551 Кширское шоссе 94-1, 1
                  [place] => г. Москва
                  [quality-code] => GOOD
                  [region] => г. Москва
                  [room] => 1
                  [street] => шоссе Каширское
                  [validation-code] => VALIDATED
              )

      )
     */
  }

  catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
      // Обработка ошибочного ответа от API ПРФ
  }

  catch (\Exception $e) {
      // Обработка нештатной ситуации
  }
?>

$addressList — это объект класса LapayGroup\RussianPost\AddressList содержащий список адресов для нормализации.

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

Очищает, разделяет и помещает значения ФИО в соответствующие поля возвращаемого объекта.
Параметр id (идентификатор записи) используется для установления соответствия переданных и полученных записей,
так как порядок сортировки возвращаемых записей не гарантируется.

Пример вызова:

<?php
  use Symfony\Component\Yaml\Yaml;
  use LapayGroup\RussianPost\Providers\OtpravkaApi;

  try {
      $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));

      $fioList = new \LapayGroup\RussianPost\FioList();
      $fioList->add('Иванов Петр игоревич');
      $result = $otpravkaApi->clearFio($fioList);

      /*
       Array
       (
           [0] => Array
               (
                   [id] => 0
                   [middle-name] => Игоревич
                   [name] => Петр
                   [original-fio] => Иванов Петр игоревич
                   [quality-code] => EDITED
                   [surname] => Иванов
               )

       )
       */
  }

  catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
      // Обработка ошибочного ответа от API ПРФ
  }

  catch (\Exception $e) {
      // Обработка нештатной ситуации
  }
?>

$fioList — это объект класса LapayGroup\RussianPost\FioList содержащий список ФИО для нормализации.

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

Принимает номера телефонов в неотформатированном виде, который может включать пробелы, символы: +-().
Очищает, разделяет и помещает сущности телефона (код города, номер) в соответствующие поля возвращаемого объекта.
Параметр id (идентификатор записи) используется для установления соответствия переданных и полученных записей,
так как порядок сортировки возвращаемых записей не гарантируется.

Пример вызова:

<?php
  use Symfony\Component\Yaml\Yaml;
  use LapayGroup\RussianPost\Providers\OtpravkaApi;

  try {
      $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));

      $phoneList = new \LapayGroup\RussianPost\PhoneList();
      $phoneList->add('9260120935');
      $result = $otpravkaApi->clearPhone($phoneList);

      /*
       Array
         (
             [0] => Array
                 (
                     [id] => 0
                     [original-phone] => 9260120935
                     [phone-city-code] => 926
                     [phone-country-code] => 7
                     [phone-extension] =>
                     [phone-number] => 0120935
                     [quality-code] => GOOD
                 )

         )
       */
  }

  catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
      // Обработка ошибочного ответа от API ПРФ
  }

  catch (\Exception $e) {
      // Обработка нештатной ситуации
  }
?>

$phoneList — это объект класса LapayGroup\RussianPost\PhoneList содержащий список номеров телефлонов для нормализации.

Расчет стоимости пересылки (Упрощенная версия)

Расчитывает стоимость пересылки в зависимости от указанных входных данных. Индекс ОПС точки отправления берется из профиля клиента.
Возвращаемые значения указываются в копейках.

Важно! Индекс отправления должен быть указан одного из пунктов сдачи, иначе будет возвращена ошибка 1001!

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

use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

$OtpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
$list = $OtpravkaApi->shippingPoints();

Пример вызова:

<?php
  use Symfony\Component\Yaml\Yaml;
  use LapayGroup\RussianPost\Providers\OtpravkaApi;
  use LapayGroup\RussianPost\ParcelInfo;

  try {
      $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));

      $parcelInfo = new ParcelInfo();
      $parcelInfo->setIndexFrom($list[0]['operator-postcode']); // Индекс пункта сдачи из функции $OtpravkaApi->shippingPoints()
      $parcelInfo->setIndexTo(644015);
      $parcelInfo->setMailCategory('ORDINARY'); // https://otpravka.pochta.ru/specification#/enums-base-mail-category
      $parcelInfo->setMailType('POSTAL_PARCEL'); // https://otpravka.pochta.ru/specification#/enums-base-mail-type
      $parcelInfo->setWeight(1000);
      $parcelInfo->setFragile(true);

      $tariffInfo = $otpravkaApi->getDeliveryTariff($parcelInfo);
      echo $tariffInfo->getTotalRate()/100 . ' руб.';

      /*
       LapayGroup\RussianPost\TariffInfo Object
       (
           [totalRate:LapayGroup\RussianPost\TariffInfo:private] => 30658
           [totalNds:LapayGroup\RussianPost\TariffInfo:private] => 6132
           [aviaRate:LapayGroup\RussianPost\TariffInfo:private] => 0
           [aviaNds:LapayGroup\RussianPost\TariffInfo:private] => 0
           [deliveryMinDays:LapayGroup\RussianPost\TariffInfo:private] => 1
           [deliveryMaxDays:LapayGroup\RussianPost\TariffInfo:private] => 3
           [fragileRate:LapayGroup\RussianPost\TariffInfo:p rivate] => 7075
           [fragileNds:LapayGroup\RussianPost\TariffInfo:private] => 1415
           [groundRate:LapayGroup\RussianPost\TariffInfo:private] => 30658
           [groundNds:LapayGroup\RussianPost\TariffInfo:private] => 6132
           [insuranceRate:LapayGroup\RussianPost\TariffInfo:private] => 0
           [insuranceNds:LapayGroup\RussianPost\TariffInfo:private] => 0
           [noticeRate:LapayGroup\RussianPost\TariffInfo:private] => 0
           [noticeNds:LapayGroup\RussianPost\TariffInfo:private] => 0
           [oversizeRate:LapayGroup\RussianPost\TariffInfo:private] => 0
           [oversizeNds:LapayGroup\RussianPost\TariffInfo:private] => 0
       )
       */
  }

  catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
      // Обработка ошибочного ответа от API ПРФ
  }

  catch (\Exception $e) {
      // Обработка нештатной ситуации
  }
?>

$parcelInfo — это объект класса LapayGroup\RussianPost\ParcelInfo содержащий данные по отправлению.
$tariffInfo — это объект класса LapayGroup\RussianPost\tariffInfo содержащий данные по расчитанному тарифу.

Расчет стоимости пересылки ЕКОМ

Стоимость пересылки для ЕКОМ расчитывается по аналогичному вышеуказанному алгоритму, за исключением некоторых входных параметров.

Пример вызова:

<?php
  use Symfony\Component\Yaml\Yaml;
  use LapayGroup\RussianPost\Providers\OtpravkaApi;
  use LapayGroup\RussianPost\ParcelInfo;

  try {
      $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));

      $parcelInfo = new ParcelInfo();
      $parcelInfo->setIndexFrom($list[0]['operator-postcode']); // Индекс пункта сдачи из функции $OtpravkaApi->shippingPoints()
      $parcelInfo->setMailCategory('ORDINARY'); // https://otpravka.pochta.ru/specification#/enums-base-mail-category
      $parcelInfo->setWeight(1000);
      $parcelInfo->setFragile(true);

      // Параметры только для ЕКОМ
      $parcelInfo->setMailType('ECOM'); // Вид РПО ЕКОМ https://otpravka.pochta.ru/specification#/enums-base-mail-type
      $parcelInfo->setDeliveryPointindex(644015); // Вместо индекса назначения указывается индекс ПВЗ
      $parcelInfo->setEntriesType('SALE_OF_GOODS'); // Категория вложения https://otpravka.pochta.ru/specification#/enums-base-entries-type
      $parcelInfo->setFunctionalityChecking(true); // Признак услуги проверки работоспособности
      $parcelInfo->setGoodsValue(1588000); // Стоимость
      $parcelInfo->setWithFitting(true); // Признак услуги 'Возможность примерки'

      $tariffInfo = $otpravkaApi->getDeliveryTariff($parcelInfo);
      echo $tariffInfo->getTotalRate()/100 . ' руб.';

      /*
       LapayGroup\RussianPost\TariffInfo Object
       (
           [functionalityCheckingRate:LapayGroup\RussianPost\TariffInfo:private] => 30658
           [functionalityCheckingNds:LapayGroup\RussianPost\TariffInfo:private] => 6132
           [withFittingRate:LapayGroup\RussianPost\TariffInfo:private] => 0
           [withFittingNds:LapayGroup\RussianPost\TariffInfo:private] => 0
       )
       */
  }

  catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
      // Обработка ошибочного ответа от API ПРФ
  }

  catch (\Exception $e) {
      // Обработка нештатной ситуации
  }
?>

Расчет сроков доставки

Расчитывает сроки доставки по типам отправлений используя API доставки Почты России

Пример вызова:

<?php
  use Symfony\Component\Yaml\Yaml;
  use LapayGroup\RussianPost\Providers\OtpravkaApi;

  try {
      $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
      $res = $otpravkaApi->getDeliveryPeriod(\LapayGroup\RussianPost\PostType::EMS, 115551, 115551);

      /*
       Array
       (
           [version] => 1.2.10.28
           [date] => 20190621
           [datefirst] => 20190411
           [posttype] => 7
           [posttypename] => EMS
           [from] => 115551
           [fromname] => МОСКВА 551
           [to] => 115551
           [toname] => МОСКВА 551
           [route] => 43-45000000-45000000
           [routename] => МОСКВА 551-МОСКВА 551
           [delivery] => Array
               (
                   [min] => 1
                   [max] => 1
               )

       )
       */
  }

  catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
      // Обработка ошибочного ответа от API ПРФ
  }

  catch (\Exception $e) {
      // Обработка нештатной ситуации
  }
?>

Отображение баланса

Отображает баланс расчетного счета. Возвращаемые значения указываются в копейках.

Пример вызова:

<?php

  use Symfony\Component\Yaml\Yaml;
  use LapayGroup\RussianPost\Providers\OtpravkaApi;
  try {
      $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
      $result = $otpravkaApi->getBalance();

      /*
       Array
       (
           [balance] => 0
           [balance-date] => 2019-06-21
           [work-with-balance] => 1
       )
       */
    }

    catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
        // Обработка ошибочного ответа от API ПРФ
    }

    catch (\Exception $e) {
        // Обработка нештатной ситуации
    }
?>

Неблагонадёжный получатель

Актуально для отправлений с наложенным платежом. Определяет, является ли получатель благонадёжным, есть ли прецеденты невыкупа.

Пример вызова:

<?php
  use Symfony\Component\Yaml\Yaml;
  use LapayGroup\RussianPost\Providers\OtpravkaApi;

  $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));

  $recepient = new \LapayGroup\RussianPost\Entity\Recipient();
  $recepient->setAddress('650905 ЯГУНОВСКИЙ, КЕМЕРОВСКАЯ ОБЛАСТЬ, УЛ БЕЛОЗЕРНАЯ, ДОМ 21,КВ 1');
  $recepient->setName('Иванов Петр Николаевич');
  $recepient->setPhone('79260112367');

  try {
      $res = $otpravkaApi->untrustworthyRecipient($recepient);
      /*
       Array
       (
           [raw-address] => 650905 ЯГУНОВСКИЙ, КЕМЕРОВСКАЯ ОБЛАСТЬ, УЛ БЕЛОЗЕРНАЯ,ДОМ 21,КВ 1
           [raw-full-name] => Иванов Петр Николаевич
           [raw-telephone] => 79260112367
           [unreliability] => RELIABLE
       )
       */
  }

  catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
      // Обработка ошибочного ответа от API ПРФ
  }

  catch (\Exception $e) {
      // Обработка нештатной ситуации
  }


  // Обработка списка получателей
  $recepients[0] = $recepient;
  $recepients[1] = $recepient;

  try {
        $res = $otpravkaApi->untrustworthyRecipients($recepients);
        /*
         Array
         (
             [0] => Array
                 (
                     [raw-address] => 650905 ЯГУНОВСКИЙ, КЕМЕРОВСКАЯ ОБЛАСТЬ, УЛ БЕЛОЗЕРНАЯ,ДОМ 21,КВ 1
                     [raw-full-name] => Иванов Петр Николаевич
                     [raw-telephone] => 79260112367
                     [unreliability] => RELIABLE
                 ),
             [1] => Array
                  (
                      [raw-address] => 650905 ЯГУНОВСКИЙ, КЕМЕРåОВСКАЯ ОБЛАСТЬ, УЛ БЕЛОЗЕРНАЯ,ДОМ 21,КВ 1
                      [raw-full-name] => Иванов Петр Николаевич
                      [raw-telephone] => 79260112367
                      [unreliability] => RELIABLE
                  )
         )
         */
    }

    catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
        // Обработка ошибочного ответа от API ПРФ
    }

    catch (\Exception $e) {
        // Обработка нештатной ситуации
    }
?>

Заказы

Реализует функции API Почты России для работы с заказами.
Для работы данных функций необходимы аутентификационные данные. Подробнее в разделе Конфигурация.

В случае возникновеня ошибок при обмене выбрасывает исключение \LapayGroup\RussianPost\Exceptions\RussianPostException
в котором будет текст и код ошибки от API Почты России и дамп сырого ответа с HTTP-кодом.

Получение списка ПВЗ

Возвращает список ПВЗ для заказов ЕКОМ.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $pvz_list = $otpravkaApi->getPvzList();
    /*
    Array
    (
        [0] => Array
            (
                [address] => Array
                    (
                        [addressType] => DEFAULT
                        [house] => 186
                        [index] => 656067
                        [manualInput] =>
                        [place] => г. Барнаул
                        [region] => край Алтайский
                        [street] => ул. Попова
                    )

                [brand-name] => Почта России
                [card-payment] =>
                [cash-payment] =>
                [closed] =>
                [contents-checking] => 1
                [delivery-point-index] => 656067
                [delivery-point-type] => DELIVERY_POINT
                [functionality-checking] =>
                [id] => 33815
                [latitude] => 53.341753
                [legal-name] => УФПС Алтайского края - филиал ФГУП "Почта России", Барнаульский почтамт, Отделение почтовой связи Барнаул  656067
                [legal-short-name] => БАРНАУЛ 67
                [longitude] => 83.667594
                [partial-redemption] =>
                [temporary-closed] =>
                [with-fitting] =>
                [work-time] => Array
                    (
                        [0] => пн, открыто: 08:00 - 20:00
                        [1] => вт, открыто: 08:00 - 20:00
                        [2] => ср, открыто: 08:00 - 20:00
                        [3] => чт, открыто: 08:00 - 20:00
                        [4] => пт, открыто: 08:00 - 20:00
                        [5] => сб, открыто: 09:00 - 18:00
                        [6] => вс, выходной
                    )

            )

        [1] => Array
            (
                [address] => Array
                    (
                        [addressType] => DEFAULT
                        [corpus] => 2
                        [house] => 8
                        [index] => 119526
                        [manualInput] =>
                        [place] => г. Москва
                        [region] => г. Москва
                        [street] => ул. 26-ти Бакинских Комиссаров
                    )

                [brand-name] => Почта России
                [card-payment] =>
                [cash-payment] =>
                [closed] =>
                [contents-checking] => 1
                [delivery-point-index] => 119526
                [delivery-point-type] => DELIVERY_POINT
                [functionality-checking] =>
                [id] => 35009
                [latitude] => 55.659170
                [legal-name] => УФПС г. Москвы-филиал ФГУП Почта России ММП 6 ОПС 526
                [legal-short-name] => МОСКВА 526
                [longitude] => 37.491359
                [partial-redemption] =>
                [temporary-closed] =>
                [with-fitting] =>
                [work-time] => Array
                    (
                        [0] => пн, открыто: 08:00 - 20:00
                        [1] => вт, открыто: 08:00 - 20:00
                        [2] => ср, открыто: 08:00 - 20:00
                        [3] => чт, открыто: 08:00 - 20:00
                        [4] => пт, открыто: 08:00 - 20:00
                        [5] => сб, открыто: 09:00 - 18:00
                        [6] => вс, открыто: 09:00 - 14:00
                    )

            )
    */
}

catch (\InvalidArgumentException $e) {
  // Обработка ошибки заполнения параметров
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Создание заказа

Создает новый заказ. Автоматически рассчитывает и проставляет плату за пересылку.
Метод asArr() проверяет заполнение необходимых для создания заказа полей и в случае незаполнения выбрасывает \InvalidArgumentException.

Важно!
Для внутренних отправлений должен задаваться цифровой почтовый индекс $order->setIndexTo(115551).
Для зарубежных отправлений должен задаваться зарубежный почтовый индекс $order->setStrIndexTo(‘ab5551’).
По умолчанию выбран динамический ДТИ. Для изменения диапазона ДТИ нужно обратиться в службу поддержки Почты России.

Пример создания заказа:

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;
use LapayGroup\RussianPost\Entity\Order;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));

    $orders = [];
    $order = new Order();
    $order->setIndexTo(115551);
    $order->setPostOfficeCode(109012);
    $order->setGivenName('Иван');
    $order->setHouseTo('92');
    $order->setCorpusTo('3');
    $order->setMass(1000);
    $order->setOrderNum('2');
    $order->setPlaceTo('Москва');
    $order->setRecipientName('Иванов Иван');
    $order->setRegionTo('Москва');
    $order->setStreetTo('Каширское шоссе');
    $order->setRoomTo('1');
    $order->setSurname('Иванов');
    $orders[] = $order->asArr();

    $result = $otpravkaApi->createOrders($orders);

    // Успешный ответ
    /*Array
    (
        [result-ids] => Array
            (
                [0] => 115322331
            )

    )
    */

    // Ответ с ошибкой
    /*Array
    (
        [errors] => Array
            (
                [0] => Array
                    (
                        [error-codes] => Array
                            (
                                [0] => Array
                                    (
                                        [code] => EMPTY_INDEX_TO
                                        [description] => Почтовый индекс не указан
                                    )

                            )

                        [position] => 0
                    )

            )

    )*/
}

catch (\InvalidArgumentException $e) {
  // Обработка ошибки заполнения параметров
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Создание заказа V2

Создает новый заказ. Автоматически рассчитывает и проставляет плату за пересылку.
Метод asArr() проверяет заполнение необходимых для создания заказа полей и в случае незаполнения выбрасывает \InvalidArgumentException.

Важно!
Для внутренних отправлений должен задаваться цифровой почтовый индекс $order->setIndexTo(115551).
Для зарубежных отправлений должен задаваться зарубежный почтовый индекс $order->setStrIndexTo(‘ab5551’).
По умолчанию выбран динамический ДТИ. Для изменения диапазона ДТИ нужно обратиться в службу поддержки Почты России.

Пример создания заказа:

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;
use LapayGroup\RussianPost\Entity\Order;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));

    $orders = [];
    $order = new Order();
    $order->setIndexTo(115551);
    $order->setPostOfficeCode(109012);
    $order->setGivenName('Иван');
    $order->setHouseTo('92');
    $order->setCorpusTo('3');
    $order->setMass(1000);
    $order->setOrderNum('2');
    $order->setPlaceTo('Москва');
    $order->setRecipientName('Иванов Иван');
    $order->setRegionTo('Москва');
    $order->setStreetTo('Каширское шоссе');
    $order->setRoomTo('1');
    $order->setSurname('Иванов');
    $orders[] = $order->asArr();

    $result = $otpravkaApi->createOrdersV2($orders);

    // Успешный ответ
    /*Array
    (
        [orders] => Array
            (
                [barcode] => 80093053624992
                [order-num] => 3
                [result-id] => 310115153
            )
    )*/

    // Ответ с ошибкой
    /*Array
    (
        [errors] => Array
            (
                [0] => Array
                    (
                        [error-codes] => Array
                            (
                                [0] => Array
                                    (
                                        [code] => EMPTY_INDEX_TO
                                        [description] => Почтовый индекс не указан
                                    )

                            )

                        [position] => 0
                    )

            )

    )*/
}

catch (\InvalidArgumentException $e) {
  // Обработка ошибки заполнения параметров
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Редактирование заказа

Изменение ранее созданного заказа. Автоматически рассчитывает и проставляет плату за пересылку.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;
use LapayGroup\RussianPost\Entity\Order;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));

    $order = new Order();
    $order->setIndexTo(115551);
    $order->setPostOfficeCode(109012);
    $order->setGivenName('Иван');
    $order->setHouseTo('92');
    $order->setCorpusTo('3');
    $order->setMass(1000);
    $order->setOrderNum('333'); // Меняем внутренний номер заказа
    $order->setPlaceTo('Москва');
    $order->setRecipientName('Иванов Иван');
    $order->setRegionTo('Москва');
    $order->setStreetTo('Каширское шоссе');
    $order->setRoomTo('1');
    $order->setSurname('Иванов');

    $result = $otpravkaApi->editOrder($order, 115322331);

    // Успешный ответ
    /*Array
    (
        [result-ids] => Array
            (
                [0] => 115322331
            )

    )
    */

    // Ответ с ошибкой
    /*Array
      (
          [error-codes] => Array
              (
                  [0] => Array
                      (
                          [code] => EMPTY_INDEX_TO
                          [description] => Почтовый индекс не указан
                      )

              )

          [position] => 0
      )*/
}

catch (\InvalidArgumentException $e) {
  // Обработка ошибки заполнения параметров
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Удаление заказов

Удаление заказов, который еще не добавлены в партию.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->deleteOrders([115322331]);
    /*
    Array Успешный ответ
    (
        [result-ids] => Array
            (
                [0] => 115322331
            )
    )

    Array Ответ с ошибкой
    (
        [errors] => Array
            (
                [0] => Array
                    (
                        [error-code] => NOT_FOUND
                        [position] => 0
                    )

            )
    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Поиск заказа

Ищет заказы по назначенному магазином идентификатору.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->findOrderByShopId(1);
    /*
    Array
    (
        [0] => Array
            (
                [address-type-to] => DEFAULT
                // По умолчанию выбран динамический ДТИ. Для изменения диапазона ДТИ нужно обратиться в службу поддержки Почты России
                [barcode] => 80082240994512
                [corpus-to] => 3
                [delivery-time] => Array
                    (
                        [max-days] => 1
                    )

                [given-name] => Иван
                [ground-rate] => 16500
                [ground-rate-with-vat] => 19800
                [ground-rate-wo-vat] => 16500
                [house-to] => 92
                [id] => 115322331
                [index-to] => 115551
                [mail-category] => ORDINARY
                [mail-direct] => 643
                [mail-rank] => WO_RANK
                [mail-type] => POSTAL_PARCEL
                [manual-address-input] =>
                [mass] => 1000
                [mass-rate] => 16500
                [mass-rate-with-vat] => 19800
                [mass-rate-wo-vat] => 16500
                [order-num] => 1
                [payment-method] => CASHLESS
                [place-to] => Москва
                [postmarks] => Array
                    (
                        [0] => NONSTANDARD
                    )

                [postoffice-code] => 109012
                [recipient-name] => Иванов Иван
                [region-to] => Москва
                [room-to] => 1
                [str-index-to] => 115551
                [street-to] => Каширское шоссе
                [surname] => Иванов
                [total-rate-wo-vat] => 16500
                [total-vat] => 3300
                [transport-type] => SURFACE
                [version] => 0
        )
    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Поиск заказа по идентификатору

Ищет заказ по идентификатору Почты России.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->findOrderById(115322331);
    /*
    Array
    (
        [address-type-to] => DEFAULT
        [barcode] => 80082240994512
        [corpus-to] => 3
        [delivery-time] => Array
            (
                [max-days] => 1
            )

        [given-name] => Иван
        [ground-rate] => 16500
        [ground-rate-with-vat] => 19800
        [ground-rate-wo-vat] => 16500
        [house-to] => 92
        [id] => 115322331
        [index-to] => 115551
        [mail-category] => ORDINARY
        [mail-direct] => 643
        [mail-rank] => WO_RANK
        [mail-type] => POSTAL_PARCEL
        [manual-address-input] =>
        [mass] => 1000
        [mass-rate] => 16500
        [mass-rate-with-vat] => 19800
        [mass-rate-wo-vat] => 16500
        [order-num] => 1
        [payment-method] => CASHLESS
        [place-to] => Москва
        [postmarks] => Array
            (
                [0] => NONSTANDARD
            )

        [postoffice-code] => 109012
        [recipient-name] => Иванов Иван
        [region-to] => Москва
        [room-to] => 1
        [str-index-to] => 115551
        [street-to] => Каширское шоссе
        [surname] => Иванов
        [total-rate-wo-vat] => 16500
        [total-vat] => 3300
        [transport-type] => SURFACE
        [version] => 0
    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Возврат заказов в «Новые»

Метод переводит заказы из партии в раздел Новые. Партия должна быть в статусе CREATED.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->returnToNew([115527611]);
    /*
    Array Успешный ответ
    (
        [result-ids] => Array
            (
                [0] => 115527611
            )

    )

    Array Ответ с ошибкой
    (
        [errors] => Array
            (
                [0] => Array
                    (
                        [error-code] => NOT_FOUND
                        [position] => 0
                    )

            )
    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Партии

Реализует функции API Почты России для работы с партиями.
Для работы данных функций необходимы аутентификационные данные. Подробнее в разделе Конфигурация.

В случае возникновеня ошибок при обмене выбрасывает исключение \LapayGroup\RussianPost\Exceptions\RussianPostException
в котором будет текст и код ошибки от API Почты России и дамп сырого ответа с HTTP-кодом.

Создание партии из N заказов

Автоматически создает партию и переносит указанные подготовленные заказы в эту партию.
Если заказы относятся к разным типам и категориям – создается несколько партий.
Заказы распределяются по соответствующим партиям.
Каждому перенесенному заказу автоматически присваивается ШПИ.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->createBatch([115527611], new DateTimeImmutable('2019-09-20'));
    /*
     Array Успешный ответ
        (
        [batches] => Array
            (
                [0] => Array
                    (
                        [batch-name] => 24
                        [batch-status] => CREATED
                        [batch-status-date] => 2019-09-03T11:37:17.589Z
                        [combined-batch-mail-types] => Array
                            (
                                [0] => POSTAL_PARCEL
                            )

                        [courier-order-statuses] => Array
                            (
                                [0] => NOT_REQUIRED
                            )

                        [international] =>
                        [list-number-date] => 2019-09-20
                        [mail-category] => COMBINED
                        [mail-category-text] => Комбинированно
                        [mail-rank] => WO_RANK
                        [mail-type] => COMBINED
                        [mail-type-text] => Комбинированно
                        [payment-method] => CASHLESS
                        [postmarks] => Array
                            (
                                [0] => NONSTANDARD
                            )

                        [postoffice-code] => 109012
                        [postoffice-name] => ОПС 109012
                        [shipment-avia-rate-sum] => 0
                        [shipment-avia-rate-vat-sum] => 0
                        [shipment-completeness-checking-rate-sum] => 0
                        [shipment-completeness-checking-rate-vat-sum] => 0
                        [shipment-contents-checking-rate-sum] => 0
                        [shipment-contents-checking-rate-vat-sum] => 0
                        [shipment-count] => 1
                        [shipment-ground-rate-sum] => 16500
                        [shipment-ground-rate-vat-sum] => 3300
                        [shipment-insure-rate-sum] => 0
                        [shipment-insure-rate-vat-sum] => 0
                        [shipment-inventory-rate-sum] => 0
                        [shipment-inventory-rate-vat-sum] => 0
                        [shipment-mass] => 1000
                        [shipment-mass-rate-sum] => 16500
                        [shipment-mass-rate-vat-sum] => 3300
                        [shipment-notice-rate-sum] => 0
                        [shipment-notice-rate-vat-sum] => 0
                        [shipment-sms-notice-rate-sum] => 0
                        [shipment-sms-notice-rate-vat-sum] => 0
                        [shipping-notice-type] => SIMPLE
                        [transport-type] => SURFACE
                        [use-online-balance] =>
                        [wo-mass] =>
                    )
            )

        [result-ids] => Array
            (
                [0] => 115527611
            )
    )

    Array Ответ с ошибкой
    (
        [errors] => Array
            (
                [0] => Array
                    (
                        [error-code] => NOT_FOUND
                        [error-description] => Отправление не найдено
                        [position] => 0
                    )
            )
    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Изменение дня отправки в почтовое отделение

Изменяет (устанавливает) новый день отправки в почтовое отделение.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->changeBatchSendingDay(25, new DateTimeImmutable('2019-09-08'));

}
catch (\InvalidArgumentException $e) {
    // Обработка ошибки
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Перенос заказов в партию

Переносит подготовленные заказы в указанную партию.
Если часть заказов не может быть помещена в партию (тип и категория партии не соответствует типу и категории заказа) —
возвращается json объект с указанием индекса заказа в переданном массиве и типом ошибки, остальные заказы помещаются в указанную партию.
Каждому перенесенному заказу автоматически присваивается ШПИ.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->moveOrdersToBatch('24', [115685148]);
    /*Array
    (
        [result-ids] => Array
            (
                [0] => 115685148
            )

    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Поиск партии по наименованию

Возвращает параметры партии по ее наименованию (batch-name).

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->findBatchByName('24');
    /*
    Array
      (
          [batch-name] => 24
          [batch-status] => CREATED
          [batch-status-date] => 2019-09-03T11:37:17.589Z
          [combined-batch-mail-types] => Array
              (
                  [0] => POSTAL_PARCEL
              )

          [courier-order-statuses] => Array
              (
                  [0] => NOT_REQUIRED
              )

          [international] =>
          [list-number-date] => 2019-09-16
          [mail-category] => COMBINED
          [mail-category-text] => Комбинированно
          [mail-rank] => WO_RANK
          [mail-type] => COMBINED
          [mail-type-text] => Комбинированно
          [payment-method] => CASHLESS
          [postmarks] => Array
              (
                  [0] => NONSTANDARD
              )

          [postoffice-code] => 109012
          [postoffice-name] => ОПС 109012
          [shipment-avia-rate-sum] => 0
          [shipment-avia-rate-vat-sum] => 0
          [shipment-completeness-checking-rate-sum] => 0
          [shipment-completeness-checking-rate-vat-sum] => 0
          [shipment-contents-checking-rate-sum] => 0
          [shipment-contents-checking-rate-vat-sum] => 0
          [shipment-count] => 2
          [shipment-ground-rate-sum] => 33000
          [shipment-ground-rate-vat-sum] => 6600
          [shipment-insure-rate-sum] => 0
          [shipment-insure-rate-vat-sum] => 0
          [shipment-inventory-rate-sum] => 0
          [shipment-inventory-rate-vat-sum] => 0
          [shipment-mass] => 2000
          [shipment-mass-rate-sum] => 33000
          [shipment-mass-rate-vat-sum] => 6600
          [shipment-notice-rate-sum] => 0
          [shipment-notice-rate-vat-sum] => 0
          [shipment-sms-notice-rate-sum] => 0
          [shipment-sms-notice-rate-vat-sum] => 0
          [shipping-notice-type] => SIMPLE
          [transport-type] => SURFACE
          [use-online-balance] =>
          [wo-mass] =>
      )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Поиск заказов с ШПИ

Возвращает данные заказа в партии по присвоенному ему ШПИ.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->findOrderByRpo(80083740712514);
    /*
    Array
    (
        [0] => Array
            (
                [address-type-to] => DEFAULT
                [barcode] => 80083740712514
                [batch-category] => COMBINED
                [batch-name] => 24
                [batch-status] => CREATED
                [completeness-checking] =>
                [corpus-to] => 3
                [delivery-time] => Array
                    (
                        [max-days] => 1
                    )

                [given-name] => Иван
                [ground-rate] => 16500
                [ground-rate-with-vat] => 19800
                [ground-rate-wo-vat] => 16500
                [house-to] => 92
                [id] => 115527611
                [index-to] => 115551
                [legal-hid] => 15b12c4c-96ff-4548-8e15-aeab82c8e927
                [mail-category] => ORDINARY
                [mail-direct] => 643
                [mail-rank] => WO_RANK
                [mail-type] => POSTAL_PARCEL
                [manual-address-input] =>
                [mass] => 1000
                [mass-rate] => 16500
                [mass-rate-with-vat] => 19800
                [mass-rate-wo-vat] => 16500
                [order-num] => 223
                [payment-method] => CASHLESS
                [place-to] => Москва
                [pochtaid-hid] => 816284
                [postmarks] => Array
                    (
                        [0] => NONSTANDARD
                    )

                [postoffice-code] => 109012
                [recipient-name] => Иванов Иван
                [region-to] => Москва
                [room-to] => 1
                [str-index-to] => 115551
                [street-to] => Каширское шоссе
                [surname] => Иванов
                [total-rate-wo-vat] => 16500
                [total-vat] => 3300
                [transport-type] => SURFACE
                [version] => 0
            )

    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Добавление заказов в партию

Создает массив заказов и помещает непосредственно в партию.
Автоматически рассчитывает и проставляет плату за пересылку.
Каждому заказу автоматически присваивается ШПИ.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $orders = []; // Массив заказов
    $result = $otpravkaApi->addOrdersToBatch('24', $orders); // Ответ аналогичен созданию заказов
}

catch (\InvalidArgumentException $e) {
  // Обработка ошибки заполнения параметров
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Удаление заказов из партии

Удаляет заказы, которые уже были добавлены в партию.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->deleteOrdersInBatch([115527611]);
    /*
     Array Успешный ответ
    (
        [result-ids] => Array
            (
                [0] => 115685148
            )
    )

    Array Ответ с ошибкой
    (
        [errors] => Array
            (
                [0] => Array
                    (
                        [error-code] => NOT_FOUND
                        [position] => 0
                    )

            )
    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Запрос данных о заказах в партии

Возвращает заказы в партии по заданным параметрам.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->getOrdersInBatch(25);
    /*
    Array
    (
        [0] => Array
            (
                [address-type-to] => DEFAULT
                [barcode] => 80084740397510
                [batch-category] => COMBINED
                [batch-name] => 25
                [batch-status] => CREATED
                [completeness-checking] =>
                [corpus-to] => 3
                [delivery-time] => Array
                    (
                        [max-days] => 1
                    )

                [given-name] => Иван
                [ground-rate] => 16500
                [ground-rate-with-vat] => 19800
                [ground-rate-wo-vat] => 16500
                [house-to] => 92
                [human-operation-name] => Присвоен трек-номер
                [id] => 115689758
                [index-to] => 115551
                [last-oper-attr] => ID_ASSIGNED
                [last-oper-date] => 2019-09-03T11:48:20.759Z
                [last-oper-type] => ID_ASSIGNMENT
                [legal-hid] => 15b12c4c-96ff-4548-8e15-aeab82c8e927
                [mail-category] => ORDINARY
                [mail-direct] => 643
                [mail-rank] => WO_RANK
                [mail-type] => POSTAL_PARCEL
                [manual-address-input] =>
                [mass] => 1000
                [mass-rate] => 16500
                [mass-rate-with-vat] => 19800
                [mass-rate-wo-vat] => 16500
                [order-num] => 2
                [payment-method] => CASHLESS
                [place-to] => Москва
                [pochtaid-hid] => 816284
                [postmarks] => Array
                    (
                        [0] => NONSTANDARD
                    )

                [postoffice-code] => 109012
                [recipient-name] => Иванов Иван
                [region-to] => Москва
                [room-to] => 1
                [str-index-to] => 115551
                [street-to] => Каширское шоссе
                [surname] => Иванов
                [total-rate-wo-vat] => 16500
                [total-vat] => 3300
                [transport-type] => SURFACE
                [version] => 1
            )
    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Поиск всех партий

Возвращает партии по заданным фильтрам.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->getAllBatches(); // Может вызываться с фильтрами
    /*
    Array
    (
        [0] => Array
            (
                [batch-name] => 24
                [batch-status] => CREATED
                [batch-status-date] => 2019-09-03T11:37:17.589Z
                [combined-batch-mail-types] => Array
                    (
                        [0] => POSTAL_PARCEL
                    )

                [courier-order-statuses] => Array
                    (
                        [0] => NOT_REQUIRED
                    )

                [international] =>
                [list-number-date] => 2019-09-16
                [mail-category] => COMBINED
                [mail-category-text] => Комбинированно
                [mail-rank] => WO_RANK
                [mail-type] => COMBINED
                [mail-type-text] => Комбинированно
                [payment-method] => CASHLESS
                [postmarks] => Array
                    (
                        [0] => NONSTANDARD
                    )

                [postoffice-address] => ул Никольская, д.7-9, стр.3, г Москва
                [postoffice-code] => 109012
                [postoffice-name] => ОПС 109012
                [shipment-avia-rate-sum] => 0
                [shipment-avia-rate-vat-sum] => 0
                [shipment-completeness-checking-rate-sum] => 0
                [shipment-completeness-checking-rate-vat-sum] => 0
                [shipment-contents-checking-rate-sum] => 0
                [shipment-contents-checking-rate-vat-sum] => 0
                [shipment-count] => 1
                [shipment-ground-rate-sum] => 16500
                [shipment-ground-rate-vat-sum] => 3300
                [shipment-insure-rate-sum] => 0
                [shipment-insure-rate-vat-sum] => 0
                [shipment-inventory-rate-sum] => 0
                [shipment-inventory-rate-vat-sum] => 0
                [shipment-mass] => 1000
                [shipment-mass-rate-sum] => 16500
                [shipment-mass-rate-vat-sum] => 3300
                [shipment-notice-rate-sum] => 0
                [shipment-notice-rate-vat-sum] => 0
                [shipment-sms-notice-rate-sum] => 0
                [shipment-sms-notice-rate-vat-sum] => 0
                [shipping-notice-type] => SIMPLE
                [transport-type] => SURFACE
                [use-online-balance] =>
                [wo-mass] =>
            )
    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Поиск заказа в партии по id

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->findOrderInBatch(115689758);
    /*
    Array
    (
        [address-type-to] => DEFAULT
        [barcode] => 80084740397510
        [batch-category] => COMBINED
        [batch-name] => 25
        [batch-status] => CREATED
        [completeness-checking] =>
        [corpus-to] => 3
        [delivery-time] => Array
            (
                [max-days] => 1
            )

        [given-name] => Иван
        [ground-rate] => 16500
        [ground-rate-with-vat] => 19800
        [ground-rate-wo-vat] => 16500
        [house-to] => 92
        [human-operation-name] => Присвоен трек-номер
        [id] => 115689758
        [index-to] => 115551
        [last-oper-attr] => ID_ASSIGNED
        [last-oper-date] => 2019-09-03T11:48:20.759Z
        [last-oper-type] => ID_ASSIGNMENT
        [legal-hid] => 15b12c4c-96ff-4548-8e15-aeab82c8e927
        [mail-category] => ORDINARY
        [mail-direct] => 643
        [mail-rank] => WO_RANK
        [mail-type] => POSTAL_PARCEL
        [manual-address-input] =>
        [mass] => 1000
        [mass-rate] => 16500
        [mass-rate-with-vat] => 19800
        [mass-rate-wo-vat] => 16500
        [order-num] => 2
        [payment-method] => CASHLESS
        [place-to] => Москва
        [pochtaid-hid] => 816284
        [postmarks] => Array
            (
                [0] => NONSTANDARD
            )

        [postoffice-code] => 109012
        [recipient-name] => Иванов Иван
        [region-to] => Москва
        [room-to] => 1
        [str-index-to] => 115551
        [street-to] => Каширское шоссе
        [surname] => Иванов
        [total-rate-wo-vat] => 16500
        [total-vat] => 3300
        [transport-type] => SURFACE
        [version] => 1
    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Документы

Реализует функции API Почты России для работы с документами.
Для работы данных функций необходимы аутентификационные данные. Подробнее в разделе Конфигурация.

В случае возникновеня ошибок при обмене выбрасывает исключение \LapayGroup\RussianPost\Exceptions\RussianPostException
в котором будет текст и код ошибки от API Почты России и дамп сырого ответа с HTTP-кодом.

Все функции работы с документами принимают параметр action, который принимает два значения:

  • OtpravkaApi::DOWNLOAD_FILE — выводит соответствующие header для скачивания файла в браузере;
  • OtpravkaApi::PRINT_FILE — возврат объекта GuzzleHttp\Psr7\UploadedFile с данными о файле.

Важно! Перед печатью любого документа нужно зафиксировать изменения в партии вызовом функции sendingF103form():

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $otpravkaApi->sendingF103form(28);
    $otpravkaApi->sendingF103form(28, true); // С онлайн балансом

}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Генерация пакета документации

Генерирует и возвращает zip архив с 4-мя файлами:

  • Export.xls , Export.csv — список с основными данными по заявкам в составе партии
  • F103.pdf — форма ф103 по заявкам в составе партии
  • В зависимости от типа и категории отправлений, формируется комбинация из сопроводительных документов в формате pdf ( формы: f7, f112, f22)
<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->generateDocPackage(28, OtpravkaApi::PRINT_FILE);
    /*
    GuzzleHttp\Psr7\UploadedFile Object
    (
        [clientFilename:GuzzleHttp\Psr7\UploadedFile:private] => all-pdf.zip
        [clientMediaType:GuzzleHttp\Psr7\UploadedFile:private] => application/zip; charset=UTF-8
        [error:GuzzleHttp\Psr7\UploadedFile:private] => 0
        [file:GuzzleHttp\Psr7\UploadedFile:private] =>
        [moved:GuzzleHttp\Psr7\UploadedFile:private] =>
        [size:GuzzleHttp\Psr7\UploadedFile:private] => 290398
        [stream:GuzzleHttp\Psr7\UploadedFile:private] => GuzzleHttp\Psr7\Stream Object
            (
                [stream:GuzzleHttp\Psr7\Stream:private] => Resource id #56
                [size:GuzzleHttp\Psr7\Stream:private] => 290398
                [seekable:GuzzleHttp\Psr7\Stream:private] => 1
                [readable:GuzzleHttp\Psr7\Stream:private] => 1
                [writable:GuzzleHttp\Psr7\Stream:private] => 1
                [uri:GuzzleHttp\Psr7\Stream:private] => php://temp
                [customMetadata:GuzzleHttp\Psr7\Stream:private] => Array
                    (
                    )

            )

    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Генерация печатной формы Ф7п

Генерирует и возвращает pdf файл с формой ф7п для указанного заказа. Опционально в файл прикрепляется форма Ф22 (посылка онлайн).
Если параметр sending-date не передается, берется текущая дата.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->generateDocF7p(123645924, OtpravkaApi::PRINT_FILE, new DateTimeImmutable('now'));
    /*
    GuzzleHttp\Psr7\UploadedFile Object
    (
        [clientFilename:GuzzleHttp\Psr7\UploadedFile:private] => f7p.pdf
        [clientMediaType:GuzzleHttp\Psr7\UploadedFile:private] => application/pdf; charset=UTF-8
        [error:GuzzleHttp\Psr7\UploadedFile:private] => 0
        [file:GuzzleHttp\Psr7\UploadedFile:private] =>
        [moved:GuzzleHttp\Psr7\UploadedFile:private] =>
        [size:GuzzleHttp\Psr7\UploadedFile:private] => 99776
        [stream:GuzzleHttp\Psr7\UploadedFile:private] => GuzzleHttp\Psr7\Stream Object
            (
                [stream:GuzzleHttp\Psr7\Stream:private] => Resource id #56
                [size:GuzzleHttp\Psr7\Stream:private] => 99776
                [seekable:GuzzleHttp\Psr7\Stream:private] => 1
                [readable:GuzzleHttp\Psr7\Stream:private] => 1
                [writable:GuzzleHttp\Psr7\Stream:private] => 1
                [uri:GuzzleHttp\Psr7\Stream:private] => php://temp
                [customMetadata:GuzzleHttp\Psr7\Stream:private] => Array
                    (
                    )

            )

    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Генерация печатной формы Ф112ЭК

Генерирует и возвращает pdf-файл с заполненной формой Ф112ЭК для указанного заказа. Только для заказа с «наложенным платежом».
Если заказ не имеет данного атрибута, метод вернет ошибку. Если параметр sending-date не передается, берется текущая дата.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->generateDocF112ek(123645924, OtpravkaApi::PRINT_FILE);
    /*
    GuzzleHttp\Psr7\UploadedFile Object
    (
        [clientFilename:GuzzleHttp\Psr7\UploadedFile:private] => f112.pdf
        [clientMediaType:GuzzleHttp\Psr7\UploadedFile:private] => application/pdf; charset=UTF-8
        [error:GuzzleHttp\Psr7\UploadedFile:private] => 0
        [file:GuzzleHttp\Psr7\UploadedFile:private] =>
        [moved:GuzzleHttp\Psr7\UploadedFile:private] =>
        [size:GuzzleHttp\Psr7\UploadedFile:private] => 149702
        [stream:GuzzleHttp\Psr7\UploadedFile:private] => GuzzleHttp\Psr7\Stream Object
            (
                [stream:GuzzleHttp\Psr7\Stream:private] => Resource id #56
                [size:GuzzleHttp\Psr7\Stream:private] => 149702
                [seekable:GuzzleHttp\Psr7\Stream:private] => 1
                [readable:GuzzleHttp\Psr7\Stream:private] => 1
                [writable:GuzzleHttp\Psr7\Stream:private] => 1
                [uri:GuzzleHttp\Psr7\Stream:private] => php://temp
                [customMetadata:GuzzleHttp\Psr7\Stream:private] => Array
                    (
                    )

            )
    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Генерация печатных форм для заказа

Генерирует и возвращает pdf файл, который может содержать в зависимости от типа отправления:

  • форму ф7п (посылка, посылка-онлайн, бандероль, курьер-онлайн);
  • форму Е-1 (EMS, EMS-оптимальное, Бизнес курьер, Бизнес курьер экспресс)
  • конверт (письмо заказное).

Опционально прикрепляются формы: Ф112ЭК (отправление с наложенным платежом), Ф22 (посылка онлайн), уведомление (для заказного письма или бандероли).

ВАЖНО: Для генерации печатных форм до формирования партии в третьем параметре batch необходимо передавать false.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    // Генерация печатных форм до формирования партии
    $result = $otpravkaApi->generateDocOrderPrintForm(123645924, OtpravkaApi::PRINT_FILE, false, new DateTimeImmutable('now'));
    // Генерация печатных форм после формирования партии
    $result = $otpravkaApi->generateDocOrderPrintForm(123645924, OtpravkaApi::PRINT_FILE, true, new DateTimeImmutable('now'));

    /*
    GuzzleHttp\Psr7\UploadedFile Object
    (
        [clientFilename:GuzzleHttp\Psr7\UploadedFile:private] => form.pdf
        [clientMediaType:GuzzleHttp\Psr7\UploadedFile:private] => application/pdf; charset=UTF-8
        [error:GuzzleHttp\Psr7\UploadedFile:private] => 0
        [file:GuzzleHttp\Psr7\UploadedFile:private] =>
        [moved:GuzzleHttp\Psr7\UploadedFile:private] =>
        [size:GuzzleHttp\Psr7\UploadedFile:private] => 251338
        [stream:GuzzleHttp\Psr7\UploadedFile:private] => GuzzleHttp\Psr7\Stream Object
            (
                [stream:GuzzleHttp\Psr7\Stream:private] => Resource id #70
                [size:GuzzleHttp\Psr7\Stream:private] => 251338
                [seekable:GuzzleHttp\Psr7\Stream:private] => 1
                [readable:GuzzleHttp\Psr7\Stream:private] => 1
                [writable:GuzzleHttp\Psr7\Stream:private] => 1
                [uri:GuzzleHttp\Psr7\Stream:private] => php://temp
                [customMetadata:GuzzleHttp\Psr7\Stream:private] => Array
                    (
                    )

            )

    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Генерация печатной формы Ф103

Генерирует и возвращает pdf файл с формой Ф103 для указанной партии.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->generateDocF103(28, OtpravkaApi::PRINT_FILE);
    /*
    GuzzleHttp\Psr7\UploadedFile Object
    (
        [clientFilename:GuzzleHttp\Psr7\UploadedFile:private] => f103.pdf
        [clientMediaType:GuzzleHttp\Psr7\UploadedFile:private] => application/pdf; charset=UTF-8
        [error:GuzzleHttp\Psr7\UploadedFile:private] => 0
        [file:GuzzleHttp\Psr7\UploadedFile:private] =>
        [moved:GuzzleHttp\Psr7\UploadedFile:private] =>
        [size:GuzzleHttp\Psr7\UploadedFile:private] => 131856
        [stream:GuzzleHttp\Psr7\UploadedFile:private] => GuzzleHttp\Psr7\Stream Object
            (
                [stream:GuzzleHttp\Psr7\Stream:private] => Resource id #74
                [size:GuzzleHttp\Psr7\Stream:private] => 131856
                [seekable:GuzzleHttp\Psr7\Stream:private] => 1
                [readable:GuzzleHttp\Psr7\Stream:private] => 1
                [writable:GuzzleHttp\Psr7\Stream:private] => 1
                [uri:GuzzleHttp\Psr7\Stream:private] => php://temp
                [customMetadata:GuzzleHttp\Psr7\Stream:private] => Array
                    (
                    )

            )

    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Подготовка и отправка электронной формы Ф103

Присваивает уникальную версию партии для дальнейшего приема этой партии сотрудниками ОПС.
Отправляет по e-mail электронную форму Ф103 в ОПС для регистрации.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->sendingF103form(28); // return boolean
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Генерация печатной формы акта осмотра содержимого

Генерирует и возвращает pdf файл с формой акта осмотра содержимого для указанной партии.

Важно! Дананя функция работает только, если включена услуга проверки комплектности по отправлению.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->generateDocCheckingAct(28, OtpravkaApi::PRINT_FILE);
    // TODO если у Вас есть пример ответа, просьба приложить его через pull request :)
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Генерация возвратного ярлыка на одной печатной странице

Генерирует и возвращает pdf файл возвратного ярлыка на одной печатной странице.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->generateReturnLabel(123456, OtpravkaApi::PRINT_FILE, OtpravkaApi::PRINT_TYPE_PAPER);
    // TODO если у Вас есть пример ответа, просьба приложить его через pull request :)
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Архив

Реализует функции API Почты России для работы с архивом.
Для работы данных функций необходимы аутентификационные данные. Подробнее в разделе Конфигурация.

В случае возникновеня ошибок при обмене выбрасывает исключение \LapayGroup\RussianPost\Exceptions\RussianPostException
в котором будет текст и код ошибки от API Почты России и дамп сырого ответа с HTTP-кодом.

Перевод партии в архив

Перевод списка партий в архив.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->archivingBatch([25]);
    /*
    Array    (

        [0] => Array
            (
                [batch-name] => 25
            )

    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Возврат партии из архива

Возврат списка партий из архива.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->unarchivingBatch([25]);
    /*
    Array Успешный ответ
    (
        [0] => Array
            (
                [batch-name] => 25
            )

    )

    Array Ответ с ошибкой
    (
        [0] => Array
            (
                [batch-name] => 26
                [error-code] => NOT_FOUND
            )

    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Запрос данных о партиях в архиве

Возврат списка партий в архиве.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->getArchivedBatches();
    /*
    Array
    (
        [0] => Array
            (
                [batch-name] => 25
                [batch-status] => ARCHIVED
                [batch-status-date] => 2019-09-03T13:17:59.237Z
                [combined-batch-mail-types] => Array
                    (
                        [0] => POSTAL_PARCEL
                    )

                [courier-order-statuses] => Array
                    (
                        [0] => NOT_REQUIRED
                    )

                [international] =>
                [list-number-date] => 2019-09-08
                [mail-category] => COMBINED
                [mail-category-text] => Комбинированно
                [mail-rank] => WO_RANK
                [mail-type] => COMBINED
                [mail-type-text] => Комбинированно
                [payment-method] => CASHLESS
                [postmarks] => Array
                    (
                        [0] => NONSTANDARD
                    )

                [postoffice-address] => ул Никольская, д.7-9, стр.3, г Москва
                [postoffice-code] => 109012
                [postoffice-name] => ОПС 109012
                [shipment-avia-rate-sum] => 0
                [shipment-avia-rate-vat-sum] => 0
                [shipment-completeness-checking-rate-sum] => 0
                [shipment-completeness-checking-rate-vat-sum] => 0
                [shipment-contents-checking-rate-sum] => 0
                [shipment-contents-checking-rate-vat-sum] => 0
                [shipment-count] => 1
                [shipment-ground-rate-sum] => 16500
                [shipment-ground-rate-vat-sum] => 3300
                [shipment-insure-rate-sum] => 0
                [shipment-insure-rate-vat-sum] => 0
                [shipment-inventory-rate-sum] => 0
                [shipment-inventory-rate-vat-sum] => 0
                [shipment-mass] => 1000
                [shipment-mass-rate-sum] => 16500
                [shipment-mass-rate-vat-sum] => 3300
                [shipment-notice-rate-sum] => 0
                [shipment-notice-rate-vat-sum] => 0
                [shipment-sms-notice-rate-sum] => 0
                [shipment-sms-notice-rate-vat-sum] => 0
                [shipping-notice-type] => SIMPLE
                [transport-type] => SURFACE
                [use-online-balance] =>
                [wo-mass] =>
            )
    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Поиск ОПС

Реализует функции API Почты России для поиска ОПС.
Для работы данных функций необходимы аутентификационные данные. Подробнее в разделе Конфигурация.

В случае возникновеня ошибок при обмене выбрасывает исключение \LapayGroup\RussianPost\Exceptions\RussianPostException
в котором будет текст и код ошибки от API Почты России и дамп сырого ответа с HTTP-кодом.

Поиск почтового отделения по индексу

Возвращает информацию о ОПС.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->searchPostOfficeByIndex(115551, 0, 0);
    /*
    Array
    (
        [address-source] => Домодедовская ул, 20, к.3, стр.2
        [distance] => 7059103.1165241
        [holidays] => Array
            (
            )

        [is-closed] =>
        [is-private-category] =>
        [is-temporary-closed] =>
        [latitude] => 55.612772
        [longitude] => 37.704862
        [postal-code] => 115551
        [region] => Москва г
        [settlement] => Москва
        [type-code] => ГОПС
        [type-id] => 8
        [working-hours] => Array
            (
                [0] => Array
                    (
                        [begin-worktime] => 08:00:00.000
                        [end-worktime] => 20:00:00.000
                        [lunches] => Array
                            (
                            )

                        [weekday-id] => 1
                    )

                [1] => Array
                    (
                        [begin-worktime] => 08:00:00.000
                        [end-worktime] => 20:00:00.000
                        [lunches] => Array
                            (
                            )

                        [weekday-id] => 2
                    )

                [2] => Array
                    (
                        [begin-worktime] => 08:00:00.000
                        [end-worktime] => 20:00:00.000
                        [lunches] => Array
                            (
                            )

                        [weekday-id] => 3
                    )

                [3] => Array
                    (
                        [begin-worktime] => 08:00:00.000
                        [end-worktime] => 20:00:00.000
                        [lunches] => Array
                            (
                            )

                        [weekday-id] => 4
                    )

                [4] => Array
                    (
                        [begin-worktime] => 08:00:00.000
                        [end-worktime] => 20:00:00.000
                        [lunches] => Array
                            (
                            )

                        [weekday-id] => 5
                    )

                [5] => Array
                    (
                        [begin-worktime] => 09:00:00.000
                        [end-worktime] => 18:00:00.000
                        [lunches] => Array
                            (
                            )

                        [weekday-id] => 6
                    )

                [6] => Array
                    (
                        [begin-worktime] => 09:00:00.000
                        [end-worktime] => 14:00:00.000
                        [lunches] => Array
                            (
                            )

                        [weekday-id] => 7
                    )

            )

        [works-on-saturdays] => 1
        [works-on-sundays] => 1
        [phones] => Array
            (
                [0] => Array
                    (
                        [is-fax] =>
                        [phone-number] => 1000000
                        [phone-town-code] => 800
                        [phone-type-name] => Прочее
                    )

            )

        [service-groups] => Array
            (
                [0] => Array
                    (
                        [group-id] => 2101
                        [group-name] => Почтовые услуги
                    )

                [1] => Array
                    (
                        [group-id] => 2315
                        [group-name] => Коммерческие услуги
                    )

                [2] => Array
                    (
                        [group-id] => 2259
                        [group-name] => Финансовые услуги
                    )

            )

    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Поиск обслуживающего ОПС по адресу

Возвращает список почтовых индексов ОПС и признак является ли переданный адрес точным адресом ОПС.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->searchPostOfficeByAddress('Санкт-Петербург, улица Победы, 15к1');
    /*
    Array
    (
        [is-matched] =>
        [postoffices] => Array
            (
                [0] => 196070
            )

    )
    */
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Поиск почтовых сервисов ОПС

Может возвращать как все доступные сервисы, так и сервисы определенной группы (например: Киберпочт@).

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->getPostOfficeServices(196070);
    $result = $otpravkaApi->getPostOfficeServices(196070, 2101); // С фильтром по группе
    /*
    Array
    (
        [0] => Array
            (
                [code] => 1090900
                [group-id] => 2101
                [name] => Хранение и возврат почтовых отправлений, периодических изданий: Абонирование ячейки абонементного почтового шкафа, Возврат посылок, Возврат РПО (кроме посылок), Хранение РПО в ОПС
            )

        [1] => Array
            (
                [code] => 1090200
                [group-id] => 2101
                [name] => Информирование отправителей и получателей РПО, ЕМS -отправлений об их статусе: SMS-уведомление, Заказное уведомление о вручении внутреннего  РПО, Простое уведомление о вручении внутреннего РПО, Простое уведомление о получении международного почтового отправления, Электронное уведомление о вручении внутреннего РПО
            )

        [2] => Array
            (
                [code] => 1090100
                [group-id] => 2101
                [name] => Доставка и оказание услуг по адресу расположения (проживания) клиента: Доставка посылок и мелких пакетов по местонахождению клиента
            )
    */
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Поиск почтовых отделений по координатам

Возвращает список ОПС по переданному массиву параметров согласно документации.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->searchPostOfficeByCoordinates($params); // $params - массив параметров поиска
    /*
        Ответ аналогичен функции searchPostOfficeByIndex только список.
    */
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Поиск почтовых индексов в населённом пункте

Возвращает список индексов.

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->getPostalCodesInLocality('Екатеринбург');
    /*
    Array
    (
        [0] => 620000
        [1] => 620002
        [2] => 620004
        [3] => 620007
        [4] => 620010
        [5] => 620012
    */
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Выгрузка из паспорта ОПС

Выгружает данные ОПС, ПВЗ, Почтоматов из Паспорта ОПС.
Генерирует и возвращает zip архив с текстовым файлом TYPEdd_MMMM_yyyy.txt, где:

  • TYPE — тип объекта
  • dd_MMMM_yyyy — время создания архива

Входные параметры:

  • $type — Тип объекта ОПС.
<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
    $result = $otpravkaApi->getPostOfficeFromPassport(\LapayGroup\RussianPost\Enum\OpsObjectType::OPS);
    /*
    GuzzleHttp\Psr7\UploadedFile Object
    (
        [clientFilename:GuzzleHttp\Psr7\UploadedFile:private] => OPS02_May_2020.zip.octet-stream
        [clientMediaType:GuzzleHttp\Psr7\UploadedFile:private] => application/octet-stream; charset=UTF-8
        [error:GuzzleHttp\Psr7\UploadedFile:private] => 0
        [file:GuzzleHttp\Psr7\UploadedFile:private] =>
        [moved:GuzzleHttp\Psr7\UploadedFile:private] =>
        [size:GuzzleHttp\Psr7\UploadedFile:private] => 4203382
        [stream:GuzzleHttp\Psr7\UploadedFile:private] => GuzzleHttp\Psr7\Stream Object
            (
                [stream:GuzzleHttp\Psr7\Stream:private] => Resource id #56
                [size:GuzzleHttp\Psr7\Stream:private] => 4203382
                [seekable:GuzzleHttp\Psr7\Stream:private] => 1
                [readable:GuzzleHttp\Psr7\Stream:private] => 1
                [writable:GuzzleHttp\Psr7\Stream:private] => 1
                [uri:GuzzleHttp\Psr7\Stream:private] => php://temp
                [customMetadata:GuzzleHttp\Psr7\Stream:private] => Array
                    (
                    )

            )
    )*/
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Долгосрочное хранение

!!!Данный раздел не работает в API Почты России!!!

Реализует функции API Почты России для работы с долгосрочным хранением.
Для работы данных функций необходимы аутентификационные данные. Подробнее в разделе Конфигурация.

В случае возникновеня ошибок при обмене выбрасывает исключение \LapayGroup\RussianPost\Exceptions\RussianPostException
в котором будет текст и код ошибки от API Почты России и дамп сырого ответа с HTTP-кодом.

Возвраты

Реализует функции API Почты России для работы с услугой Легкий возврат.
Для работы данных функций необходимы аутентификационные данные. Подробнее в разделе Конфигурация.

В случае возникновеня ошибок при обмене выбрасывает исключение \LapayGroup\RussianPost\Exceptions\RussianPostException
в котором будет текст и код ошибки от API Почты России и дамп сырого ответа с HTTP-кодом.

Создание возвратного отправления для ранее созданного отправления

Создает возвратное отправление (ЛВ) для уже созданного в ЛК отправления.

Входные параметры:

  • $rpo — ШПИ прямого отправления;
  • $mail_type — Вид РПО. См. Вид РПО.

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

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

$otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
$result = $otpravkaApi->returnShipment(123456, \LapayGroup\RussianPost\Enum\MailType::UNDEFINED);

// Успешный ответ
/*Array
(
    [return-barcode] => 1234567890 // ШПИ возвратного отправления
)

// Ответ с ошибкой
/*Array
(
    [errors] => Array
        (
            [0] => Array
                (
                    [code] => DIRECT_SHIPMENT_NOT_FOUND
                    [description] => Прямое отправление не найдено
                )

        )

)*/

Создание отдельного возвратного отправления

Создает возвратное отправление (ЛВ) без прямого.
Метод asArr() проверяет заполнение необходимых для создания возвратного отправления полей и в случае незаполнения выбрасывает \InvalidArgumentException.

Пример создания заказа:

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));

    $addressFrom = new \LapayGroup\RussianPost\Entity\AddressReturn();
    $addressFrom->setAddressType(\LapayGroup\RussianPost\Enum\AddressType::DEFAULT);
    $addressFrom->setIndex(125009);
    $addressFrom->setPlace('Москва');
    $addressFrom->setRegion('Москва');

    $addressTo = new \LapayGroup\RussianPost\Entity\AddressReturn();
    $addressTo->setAddressType(\LapayGroup\RussianPost\Enum\AddressType::DEFAULT);
    $addressTo->setIndex(115551);
    $addressTo->setPlace('Москва');
    $addressTo->setRegion('Москва');

    $return_shipment = new \LapayGroup\RussianPost\Entity\ReturnShipment();
    $return_shipment->setMailType(\LapayGroup\RussianPost\Enum\MailType::UNDEFINED);
    $return_shipment->setSenderName('Иванов Иван');
    $return_shipment->setRecipientName('Петров Петр');
    $return_shipment->setOrderNum(1234);
    $return_shipment->setAddressFrom($addressFrom);
    $return_shipment->setAddressTo($addressTo);

    $result = $otpravkaApi->createReturnShipment([$return_shipment->asArr()]);

    // Успешный ответ
    // TODO добавьте в PR, если у кого есть реальный пример, пожалуйста :-)

    // Ответ с ошибкой
    /*Array
    (
        [0] => Array
        (
            [errors] => Array
            (
                [0] => Array
                (
                    [code] => FREE_ER_ADDRESS_NOT_ENABLED
                    [description] => Свободный ввод адреса не доступен
                        )

                )

            [position] => 0
        )
    )*/
}

catch (\InvalidArgumentException $e) {
  // Обработка ошибки заполнения параметров
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Удаление отдельного возвратного отправления

Удаляет отдельное возвратное отправление.

Входные параметры:

  • $rpo — ШПИ возвратного отправления.

Выходные параметры:

  • code — Код ошибки;
  • description — Описание ошибки.

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

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

$otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
$result = $otpravkaApi->deleteReturnShipment(123456);

/*Array
(
    [code] => RETURN_SHIPMENT_NOT_FOUND
    [description] => Возвратное отправление не найдено
)*/

Редактирование отдельного возвратного отправления

Редактирование отдельного возвратного отправления (ЛВ).
Метод asArr() проверяет заполнение необходимых для создания возвратного отправления полей и в случае незаполнения выбрасывает \InvalidArgumentException.

Пример создания заказа:

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

try {
    $otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));

    $addressFrom = new \LapayGroup\RussianPost\Entity\AddressReturn();
    $addressFrom->setAddressType(\LapayGroup\RussianPost\Enum\AddressType::DEFAULT);
    $addressFrom->setIndex(125009);
    $addressFrom->setPlace('Москва');
    $addressFrom->setRegion('Москва');

    $addressTo = new \LapayGroup\RussianPost\Entity\AddressReturn();
    $addressTo->setAddressType(\LapayGroup\RussianPost\Enum\AddressType::DEFAULT);
    $addressTo->setIndex(115551);
    $addressTo->setPlace('Москва');
    $addressTo->setRegion('Москва');

    $return_shipment = new \LapayGroup\RussianPost\Entity\ReturnShipment();
    $return_shipment->setMailType(\LapayGroup\RussianPost\Enum\MailType::UNDEFINED);
    $return_shipment->setSenderName('Иванов Иван');
    $return_shipment->setRecipientName('Петров Петр');
    $return_shipment->setOrderNum(1234);
    $return_shipment->setAddressFrom($addressFrom);
    $return_shipment->setAddressTo($addressTo);

    $result = $otpravkaApi->editReturnShipment($return_shipment, 123456);

    // Успешный ответ
    // TODO добавьте в PR, если у кого есть реальный пример, пожалуйста :-)

    // Ответ с ошибкой
    /* Array
    (
        [errors] => Array
            (
                [0] => Array
                    (
                        [code] => FREE_ER_ADDRESS_NOT_ENABLED
                        [description] => Свободный ввод адреса не доступен
                    )

            )

    )*/
}

catch (\InvalidArgumentException $e) {
  // Обработка ошибки заполнения параметров
}

catch (\LapayGroup\RussianPost\Exceptions\RussianPostException $e) {
  // Обработка ошибочного ответа от API ПРФ
}

catch (\Exception $e) {
  // Обработка нештатной ситуации
}

Настройки

Реализует функции API Почты России для работы с настройками.
Для работы данных функций необходимы аутентификационные данные. Подробнее в разделе Конфигурация.

В случае возникновеня ошибок при обмене выбрасывает исключение \LapayGroup\RussianPost\Exceptions\RussianPostException
в котором будет текст и код ошибки от API Почты России и дамп сырого ответа с HTTP-кодом.

Текущие точки сдачи

Возвращает список текущих точек сдачи.

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

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

$otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
$list = $otpravkaApi->shippingPoints();

Текущие настройки пользователя

Возвращает текущие настройки пользователя.

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

<?php
use Symfony\Component\Yaml\Yaml;
use LapayGroup\RussianPost\Providers\OtpravkaApi;

$otpravkaApi = new OtpravkaApi(Yaml::parse(file_get_contents('path_to_config.yaml')));
$info = $otpravkaApi->settings();

Оригинал статьи http://www.emspost.ru/ru/corp_clients/dogovor_docements/api/

API предназначено для автоматического расчета стоимости и сроков доставки EMS-отправлений.

Функционирование API предполагает выполнение HTTP запросов со стороны клиентов и выдачу сервером соответствующих им результатов в формате JSON.

В настоящее время API реализует выполнение следующих методов:

  • ems.test.echo – проверка доступности сервиса;
  • ems.get.locations – получение списков идентификаторов, используемых для кодирования пунктов отправки и получения в запросах расчета стоимости доставки;
  • ems.get.max.weight – получение значения максимально допустимого веса отправления;
  • ems.calculate – расчет стоимости и сроков доставки.

I. Общая структура запроса

Все запросы к API имеют следующий формат:

http://emspost.ru/api/rest/?<набор параметров>

где <набор параметров> — набор параметров запроса, представленный в соответствии со стандартами оформления http-запросов. Параметры запросов к API разделяются на 2 типа:

  • общие параметры для всех запросов.
  • специфические параметры метода API, применяются только в запросах определенных методов.

К общим параметрам запросов относятся следующие:

  • method – обязательный параметр для любого запроса содержащий имя метода API. Допустимыми значениями являются:
    • ems.test.echo
    • ems.get.locations
    • ems.get.max.weight
    • ems.calculate
  • plain – параметр, отключающий режим кодирования символов Unicode в ответе сервера в соответствии со спецификацией JSON. Параметр не является обязательным. Допустимые значения:
    • true – кодирование не осуществляется, символы Unicode выводятся в ответ «как есть» (см. примеры далее).
  • callback – параметр, использующийся для выполнения XSS (Сross Site Sсriрting) запросов, для вызова API из JavaScript. Значением является имя функции клиента, в качестве аргументов которой должен быть подставлен ответ сервера (см. примеры далее). Параметр не является обязательным.

Специфические параметры методов описаны ниже в соответствующих разделах.

II. Ответ сервера

Ответы сервера представляют собой данные в формате JSON, соответствующие поступившему запросу. Общий вид ответа:

{«rsp»:{<статус обработки запроса >,<данные ответа>}}

<статус обработки запроса > указывается в ответе в поле stat, например:

{«rsp»:{«stat»:»ok»,<данные ответа>}}

Допустимые значения:

  • ok – запрос обработан, ответ содержит запрашиваемые данные
  • fail – при обработке запроса произошла ошибка, ответ содержит информацию об ошибке

При возникновении ошибки выводится результат вида:

{«rsp»:{«stat»:»fail»,»err»:{<информация об ошибке>} }}

<информация об ошибке> содержит два поля:

  • поле code содержит код ошибки
  • поле msg содержит описание ошибки

и имеет вид:

{«rsp»:{«stat»:»fail»,»err»:{«code»:»101″,»msg»:»Wrong location type. Allowed: cities, regions, countries»}}}

III. Общие примеры запросов и ответов

1. Запрос тестирования доступности:

http://emspost.ru/api/rest/?method=ems.test.echo

Ответ сервера:

{«rsp»:{«stat»:»ok»,»msg»:»successeful»}}

2. Запрос тестирования доступности с установленным параметром callback:

http://emspost.ru/api/rest/?method=ems.test.echo&callback=jsonEMSApi

Ответ сервера:

jsonEMSApi({«rsp»:{«stat»:»ok»,»msg»:»successeful»}})

IV. Метод ems.get.locations

Возвращает список идентификаторов, используемых для кодирования пунктов отправки и получения в запросах расчета стоимости доставки.

Специфические параметры метода

  • type (обязательный) — тип запрашиваемых местоположений. Допустимые значения:
    • cities – получить список идентификаторов городов России, для которых может быть рассчитана доставка;
    • regions– получить список идентификаторов регионов России, для которых может быть рассчитана доставка;
    • russia – получить объединенный список идентификаторов городов и регионов России, для которых может быть рассчитана доставка;
    • countries – получить список идентификаторов стран, для которых может быть рассчитана доставка.

Ответ сервера

Блок <данные ответа> для запроса ems.get.locations содержит массив locations вида:

«locations»:[
<элемент местоположения> , <элемент местоположения>, … <элемент местоположения>
]

Где <элемент местоположения> — структура, содержащая 3 поля:

  • value — идентификатор местоположения.
  • name — название местоположения
  • type — тип местоположения. Допустимые значения соответствуют типу запроса: cities, regions или countries.

Например:

{«value»:»city—abakan»,»name»:»АБАКАН»,»type»:»cities»}

Примеры использования метода

1. Получить список идентификаторов городов России в формате с отключенным кодированием Unicode-символов:

http://emspost.ru/api/rest/?method=ems.get.locations&type=cities&plain=true

Ответ сервера (в сокращенном виде):

{«rsp»:{
«stat»:»ok»,
«locations»:[
{«value»:»city—abakan»,»name»:»АБАКАН»,»type»:»cities»},
{«value»:»city—anadyr»,»name»:»АНАДЫРЬ»,»type»:»cities»},

… ,

{«value»:»city—yaroslavl»,»name»:»ЯРОСЛАВЛЬ»,»type»:»cities»}
]}}

2. Получить список идентификаторов регионов. Символы Unicode по умолчанию кодируются в соответствии со стандартом JSON:

http://emspost.ru/api/rest/?method=ems.get.locations&type=regions

Ответ сервера (в сокращенном виде):

{«rsp»:{
«stat»:»ok»,»locations»:[
{«value»:»region—respublika-adygeja», «name»:»\u0410\u0414\u042b\u0413\u0415\u042f\u0420\u0415\u0421\u041f\u0423\u0411\u041b\u0418\u041a\u0410″,»type»:»regions»},

… ,

{«value»:»region—tajmyrskij-ao», «name»:»\u0422\u0410\u0419\u041c\u042b\u0420\u0421\u041a\u0418\u0419\u0414\u041e\u041b\u0413\u0410\u041d\u041e-\u041d\u0415\u041d\u0415\u0426\u041a\u0418\u0419\u0420\u0410\u0419\u041e\u041d»,»type»:»regions»}
]}

V. Метод ems.get.max.weight

Возвращает значение максимально допустимого веса отправления.

Специфические параметры метода

нет

Ответ сервера

<данные ответа > содержат значение max_weight, соответствующее максимально допустимому весу отправления.

Примеры использования метода

http://emspost.ru/api/rest/?method=ems.get.max.weight

Ответ сервера

«rsp»:{«stat»:»ok»,»max_weight»:»31.5″}}

VI. Метод ems.calculate

Возвращает значение стоимости и сроков доставки EMS-отправления.

Специфические параметры метода

  • from (обязательный, кроме международной доставки) — идентификатор пункта отправления. Для получения списка допустимых идентификаторов используется метод ems.get.locations.
  • to (обязательный) — идентификатор пункта назначения. Для получения списка допустимых идентификаторов используется метод ems.get.locations.
  • weight (обязательный) — вес отправления. Значение не должно превышать максимально допустимый вес отправления, значение которого возвращается методом ems.get.max.weight.
  • type (обязательный для международной доставки) — тип международного отправления. Допустимые значения:
    • doc — документы (до 2-х килограм),
    • att — товарные вложения.

Ответ сервера

<данные ответа > содержат значение следующих полей:

  • price – стоимость отправления;
  • term – структура, содержащая информацию о сроках доставки внутрироссийских отправлений, состоящая из двух полей:
    • min – минимальный срок доставки;
    • max – максимальный срок доставки.

и имеют следующий вид:

«price»:»630″,»term»:{«min»:»4″,»max»:»6″}

Примеры использования метода

1. Запрос расчета стоимости и сроков доставки из Москвы в Омскую область отправления весом 1,5 кг:

http://emspost.ru/api/rest?method=ems.calculate&from=city—moskva&to=region—omskaja-oblast&weight=1.5

Ответ сервера:

{«rsp»:{«stat»:»ok»,»price»:»870″,»term»:{«min»:»3″,»max»:»5″}}}

2. Запрос стоимости доставки в Литву товарных вложений общим весом 0,5 кг:

http://emspost.ru/api/rest?method=ems.calculate&to=LT&weight=0.5&type=att

Ответ сервера:

{«rsp»:{«stat»:»ok»,»price»:»1585″}}

Прочитав статью Клиент для SOAP API Почты России на Python и воодушевленный подвигом ребят, а также располагая свободным временем, решено было сделать тоже самое.
Но на .NET, так как Visual Studio более адаптивна к веб-сервисам с описанием в wsdl.

Как работает

Для получения информации по списку почтовых трекеров (trackid_list)

  • необходимо получить номер билета (ticket_number), с указанием логина и пароля сервиса
  • запросить информацию с предъявлением выданного билета, с указанием логина и пароля сервиса
Подключаем Web Reference

Создадим проект UnitTest:

Добавим с помощью встроенных средств обертку на сервис vfc.russianpost.ru

Стоит отметить, что добавлять нужно именно WebReference.
С ServiceReference возникает проблема в приведении типов, так что, вероятно, сам сервис не поддерживает более новый формат.

После добавления у вас появится появится доступ к классу UnitTestProject_ruPost.ruPost.ItemDataService, а также в файл app.config будет добавлены настройки доступа к веб сервису.

Класс обертка RussianPostAgent

Весь код написан к .NET 4.5

using System;
using System.Collections.Generic;
using System.Linq;
using System.Runtime.CompilerServices;
using System.Text;
using System.Threading.Tasks;
using UnitTestProject_ruPost.ruPost;


namespace UnitTestProject_ruPost
{
    /// <summary>
    /// Класс обертка для vfc.russianpost.ru
    /// </summary>
    public class RussianPostAgent
    {
        #region Внутренние объекты

        //Экземпляр клиента-сервиса        
        static readonly ItemDataService client = new ItemDataService();
        //Словари с описанием статусов
        static readonly Dictionary<int,string> _oper_types = new Dictionary<int,string>();
        static readonly Dictionary<int,string> _oper_categories = new Dictionary<int,string>();

        //Статический конструктор
        static RussianPostAgent()
        {
           _oper_types.Add(1,"Приём");
           _oper_types.Add(2,"Вручение");
           _oper_types.Add(3,"Возврат");
           _oper_types.Add(4,"Досылка почты");
           _oper_types.Add(5,"Невручение");
           _oper_types.Add(6,"Хранение");
           _oper_types.Add(7,"Временное хранение");
           _oper_types.Add(8,"Обработка");
           _oper_types.Add(9,"Импорт международной почты");
           _oper_types.Add(10,"Экспорт международной почты");
           _oper_types.Add(11,"Передано таможне");
           _oper_types.Add(12,"Неудачная попытка вручения");
           _oper_types.Add(13,"Регистрация отправки");
           _oper_types.Add(14,"Таможенное оформление завершено");
           _oper_types.Add(15,"Передача на временное хранение");
           _oper_types.Add(16,"Уничтожение");
            
           _oper_categories.Add(0,"Сортировка");
           _oper_categories.Add(1,"Вручение адресату");
           _oper_categories.Add(2,"Прибыло в место вручения");
           _oper_categories.Add(3,"Прибыло в сортировочный центр");
           _oper_categories.Add(4,"Покинуло сортировочный центр");
           _oper_categories.Add(5,"Прибыло в место международного обмена");
           _oper_categories.Add(6,"Покинуло место международного обмена");
           _oper_categories.Add(8,"Иное");
           _oper_categories.Add(9,"Адресат заберет отправление сам");
           _oper_categories.Add(10,"Нет адресата");
        }

        /// <summary>
        /// Получить соответствие ID из словаря если оно есть
        /// </summary>
        /// <param name="d">Словарь</param>
        /// <param name="id">ID</param>
        /// <returns></returns>
        static string _get_(IDictionary<int,string> d,string id)
        {
            int _id=-1;
            if (d!=null&&!string.IsNullOrEmpty(id)
                && int.TryParse(id, out _id)
                && d.ContainsKey(_id))
                return d[_id];
            return id;
        }

        /// <summary>
        /// Получить тип операции по ID
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        static string _get_oper_type(string id)
        {
            return _get_(_oper_types,id);
        }
        
        /// <summary>
        /// Получить категорию операции по ID
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        static string _get_oper_category(string id)
        {
            return _get_(_oper_categories, id);
        }

        #endregion

        /// <summary>
        /// Получить детальную информацию о состояние почтовых трэков
        /// </summary>
        /// <param name="login">Логин в системе vfc.russianpost.ru</param>
        /// <param name="password">Пароль</param>
        /// <param name="trackid_list">Список trackid</param>        
        public static Task<dynamic> getStates(string login, string password, string[] trackid_list)
        {            
            //Если параметры пустые, то выходим
            if (string.IsNullOrEmpty(login) || string.IsNullOrEmpty(password)
                || (trackid_list == null || trackid_list.Length == 0))
                return null;

            return Task.Factory.StartNew<dynamic>((Func<object,dynamic>)(
                (args) =>
                {
                    object result = null;

                    //Обработка ошибки
                    Func<object, bool> f_error =
                        e =>
                        {
                            if (e is error)
                            {
                                error _error = e as error;
                                //Установим результат с исключением
                                if (_error != null)
                                   result = new { Exception = string.Format("{0} (код ошибки:{1})",
                                                              _error.ErrorName,
                                                              _error.ErrorTypeID) };
                                return true;
                            }
                            return false;
                        };

                    //Запрос билета, на  доступ к детальной информации списка трэков
                    result = client.getTicket(
                          new file
                          {
                              DatePreparation = DateTime.Now.ToString("dd.MM.yyyy HH:mm:ss"),
                              FileTypeID = "1",
                              FileName = "0",
                              SenderID = "0",
                              RecipientID = "1",
                              FileNumber = "0",
                              Item = trackid_list.Aggregate(new List<item>(), (l, i) =>
                              {
                                  l.Add(new item { Barcode = i });
                                  return l;
                              }).ToArray()
                          }
                          , login, password, "RUS");

                    //Если нет ошибки в ответе
                    //То по номеру выданного билета получим детальную информацию по списку трэков
                    if (!f_error(result) && result is string)
                    {                        
                        result = client.getResponseByTicket(result as string,
                                                            (args as string[])[0],
                                                            (args as string[])[1]);
                        if (!f_error(result)&&result is item)
                        {
                            item item = result as item;
                            //Вернем результат
                            return 
                            new
                            {
                                Exception = string.Empty, //Ошибка не указана
                                //Список операции
                                Operations = item.Operation.Aggregate(new List<object>(),
                                                        (a, o) =>
                                                        {
                                                            a.Add(new 
                                                                       {
                                                                         TrackID = item.Barcode, 
                                                                         Date = o.DateOper, 
                                                                         ID = o.IndexOper,
                                                                         Name = o.OperName, 
                                                                         Category = _get_oper_category(o.OperCtgID) 
                                                                        }
                                                                     );
                                                            return a;
                                                        }
                                                     ).ToArray(),
                                //Список ошибок
                                Errors = item.Error.Aggregate(new List<object>(),
                                                       (a, e) =>
                                                       {
                                                        a.Add(
                                                         new {
                                                                  TrackID = item.Barcode,
                                                                  Date = DateTime.Now.ToString("dd.MM.yyyy HH:mm:ss"),
                                                                  ID = e.ErrorTypeID,
                                                                  Name = e.ErrorName
                                                                }
                                                                  );
                                                           return a;
                                                       }).ToArray()
                            };                         
                        }
                    }

                    return result;
                }), new string[] { login, password });
                

        
        }
    }
}


Тестируем класс-обертку

Напишем для этого тест:

using System;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using System.Threading.Tasks;


namespace UnitTestProject_ruPost
{
    [TestClass]    
    public class UnitTest1
    {
        [TestMethod]
        public void TestMethod1()
        {
            Task<dynamic> tStateTracks = RussianPostAgent.getStates(
                "[login]", "[password]",
                new string[] { //Список трэкеров
                               string.Empty.PadRight(13,"1"[0]), //"1111111111111"
                               string.Empty.PadRight(13,"2"[0]),
                               string.Empty.PadRight(13,"3"[0]),
                               string.Empty.PadRight(13,"4"[0]),
                             });
            //Ожидаем завершения задачи
            tStateTracks.Wait();
            
            //Получим результат выполнения 
            dynamic data = tStateTracks.Result;

            //Проверим его на ошибку
            string error = data.Exception as string;                   
            Assert.IsFalse(!string.IsNullOrEmpty(error), error);

            //Вывод результатов
            object[] operations = data.Operations;            
            object[] errors = data.Errors;
            foreach (dynamic oper in operations)
                       Assert.Inconclusive(
                           string.Format("TrackId:{0}\tDate:{1}\tID Oper:{2}\tOper Name:{3}\tCategory:{4}",
                           oper.TrackID,
                           oper.Date,
                           oper.ID,
                           oper.Name,
                           oper.Category
                           ));
                   foreach (dynamic err in errors)
                       Assert.Inconclusive(
                           string.Format("TrackId:{0}\tErrorID:{1}\tError:{2}",
                           err.TrackID,
                           err.ID,
                           err.Name
                           ));            
        }
    }
}

Стоит заметить, что у меня нет возможности протестировать его без ошибки.
Так как я не обладаю логином и паролем к сервису и нет возможности его получить, поэтому результатом данного теста будет ошибка сервиса о не прошедшей авторизации.

Заключение

В заключении хотелось бы отметить, что данная статья носит исключительно ознакомительный характер, про то как возможно реализовать доступ к сервису почты России с использованием .NET, так как ещё раз повторюсь, у меня нет официального доступа к сервису.

Всем, у кого есть замечания и предложения по доработке, прошу на git.

В следующей статье мы поговорим, о реализации аналогичного асинхронного решения, но без обращения к веб-сервису почты России и с использованием antigate.

Trackru API

Получить API ключ

Для интеграции с API необходимо располагать: API Keys.

The base URL

https://api.trackru.ru/v1


При работе с API,

: спользуется HTTPS соединение, а также http.

Заголовки

Для проверки и аутентификации вашего приложения (например, вашего сайта) все запросы к API должны включать ваш уникальный Trackru API ключ ( Api-Key),вы можете сгенерировать ключ авторизации Api-Key.

                        Content-Type: application/json
Api-Key: YOUR_API_KEY

Отчет «Статусы заказов»

Значение Описание
pending Заказ создан в информационной системе.
notfound Заказ не найден в данный момент.
transit Заказ отправлен.
pickup Выдан на доставку.
delivered Успешно доставлен и вручен адресату (конечный статус).
undelivered Курьер попытался доставить, но не удалось, обычно оставляет уведомление и попытается доставить снова.
exception Заказ может подвергаться необычным условиям доставки, это может быть вызвано несколькими причинами, скорее всего, товар был возвращен отправителю, таможня, утерян, поврежден и т. д.
expired Заказ долго находился в периоде транспортировки без обновления статуса.

Подстатусы «Не найдено» Описание
not found001 Информация получена. Заказ готов к перевозке.
not found002 Нет информации об отслеживании данного заказа.

Подстатус «Исключение» Описание
exception001 Заказ отправлен ** дней без информации отслеживания, помечен как «Исключение».
exception002 Заказ в пути ** дней без информации отслеживания, помечен как «Исключение».
exception003 Заказ отправлен ** но не доставлен, помечен как «Исключение».
exception004 Невостребованное отправление.
exception005 Посылка была отправлена обратно отправителю.
exception006 Посылка задержана на таможне, это запрещённый товар.
exception007 Посылка утеряна или повреждена.
exception008 Доставка отменена до доставки.

Список возврата параметров API

Значние Описание
code Meta.code
type Meta.type
message Meta status description
id Произвольные данные, генерируемые Trackru для идентификации трекинга
tracking_number Трек-номер или номер для отслеживания
carrier_code Код службы доставки
status Статус посылки
created_at Время добавления трек-номера
updated_at Время последнего обновления статуса посылки
order_create_time Время создания заказа
title Название продукта
order_id Номер заказа
comment Ваше замечание к заказу
customer_name Имя покупателя
customer_email email покупателя
original_country Название страны происхождения
singed_by Имя получателя
lastEvent Последнее обновление статуса
lastUpdateTime Время последней информации отслеживания
destination_country Название страны назначения
itemTimeLength Время перевозки заказа
stayTimeLength Общее количество дней без обновлений с момента появления последнего обновления
origin_info Информация об отправлении предоставляется службой доставки отправителя.
ItemReceived Время обновления первого статуса
ItemDispatched Время отпракви с сортировочного центра.
DepartfromAirport Время прибытия на аэропорт.
ArrivalfromAbroad Время прибытия в страну назначения.
CustomsClearance Время передачи посылки таможне.
DestinationArrived Время прибытия в пункт назначения.
weblink Ссылка на официальный сайт службы доставки.
phone Телефон службы доставки
trackinfo Подробная информация об отслеживании
Date Дата определенного статуса
StatusDescription Основное содержание определенного статуса
Details Информация о местоположении отправления
destination_info Информация об отправлении предоставляется службой доставки получателя.

Стандартный ответ сервера

Мы ответим Вам одним из следующих кодов состояния.

Meta.code Meta.type Описание
200 Success Запрос был успешно выполнен (некоторые вызовы API могут возвращать вместо этого код 201).
201 Created Запрос был успешно выполнен и ресурс был создан.
202 Bad Request Запрос был успешно выполнен, но был превышен лимит.
401 Unauthorized Ошибка аутентификации или пользователь не имеет достаточно прав для совершения запрашиваемой операции.
4001 Unauthorized Ошибочный API ключ. Проверьте его правильность. Check
4002 Unauthorized API ключ был удален. Проверьте его состояние. Check
4012 Bad Request Не ясен запрос или отсутствуют необходимые параметры.
4013 Bad Request Требуется трек-номер.
4014 Bad Request Недопустимое значение трек-номера.
4015 Bad Request Недопустимое значение «carrier_code». Проверьте его правильность здесь Check Код службы доставки
4016 Bad Request Данное отслеживание уже существует.
4017 Bad Request Данное отслеживание не существует.
4018 Bad Request Из-за рисков перегрузки данная функция требует активации службой поддержки. Свяжитесь по адресу [email protected] для уточнения дополнительной информации.
4019 Bad Request Баланс израсходован, пожалуйста, пополните счет для продолжения. Бесплатный аккаунт поддерживает до 500 номеров в месяц.
4020 Bad Request Максимум 200 за один раз.
4021 Bad Request Остатка на балансе не достаточно для совершения операции с API. Пополнить. Purchase here.
4031 No Content Запрос был успешно выполнен, но ответ пуст. Попробуйте POST /trackings/post
и затем GET /trackings/get
4032 No Content Не удается определить службу доставки. Требуется указать службу доставки вручную.
Получить код службы доставки.
4033 No Content Недопустимое значение «статуса».
402 Payment Required Требуется оплата.
403 Forbidden Доступ запрещен.
404 Not Found Ресурс не найден.
405 Method Not Allowed Запрашиваемый метод не поддерживается для указанного ресурса.
409 Conflict Запрос не может быть выполнен из-за конфликта.
429 Too Many Requests Превышены лимиты API. Подождите две минуты и повторите попытку.
500 Server error
503 Service Unavailable Услуга временно недоступна (возможно плановое обслуживание системы). Повторите попытку позже.

Лимит запроса

Мы применяем ограничений по количеству запросов. Имейте в виду, что если запросы превысит эти пределы, вы получите ошибку 429..

  • POST /trackings/realtime        Отслеживание в режиме реального времени: для каждого IP-адреса, максимум 3 запроса в секунду.
  • GET /trackings/get                    Список всех отслеживаний; каждый IP-адрес, максимум 1 запрос, до 2000 отслеживаний в секунду.

Понравилась статья? Поделить с друзьями:
  • Почта ошибка сервера 503
  • Почта ошибка 550 что это
  • Почта ошибка 500 что это
  • Почта выдает ошибку соединения
  • Почта ошибка 421