Интеграция с API Почты России. Регистрация отправлений и обновление статусов отправлений.

К написанию данной статьи сподвигло небольшое количество актуальной информации (2022-2023 годы) о взаимодействии с сервером Почты России по api. Найденная мной информация в основном касается отслеживания отправлений, причем не в пакетном режиме, а для каждого в отдельности, мне же по работе пришла задача на регистрацию отправлений на сервере Почты России и получение статусов по трек-номерам в пакетном режиме.

Что требуется — создавать отправления на сервере Почты России, получать печатные формы (с трек-номером). Для каждого успешного отправления создавать элемент справочника в котором будут храниться печатные формы (ярлыки), трек-номер, лог создания отправления и его статус. Так же требуется проверять статус по трек-номеру отправления.

Что нам понадобится: прежде всего это договор с Почтой России, т. к. для регистрации отправлений какой либо тестовой среды не существует. Для отправки существует отдельный сервис https://otpravka.pochta.ru. После прохождения всего процесса регистрации (описывать его не стану) вам станет доступен личный кабинет (далее ЛК) и возможность изучить спецификацию https://otpravka.pochta.ru/specification#/main, вам выдадут логин, пароль и токен. В отличии от спецификации для отслеживания отправлений, примеры для 1с отсутствуют, в основном все примеры на питоне.

Итак:

API Онлайн-сервиса «Отправка» является самым прямым способом взаимодействия сторонних приложений с Онлайн-сервисом «Отправка» посредством REST запросов.
Запросы и ответы сервиса используют JSON текстовый формат.

Подключение ваших приложений к API Онлайн-сервису «Отправка» позволит интегрировать в ваши бизнес-процессы:

• подготовку печатных ярлыков для отправлений;

• подготовку печатных документов с расчетом стоимости;

• подготовку электронных документов с автоматической отсылкой в почтовое отделение;

• подключение дополнительных сервисов для нормализации адресов, телефонов, наименований (фамилия, имя, отчество) получателей.

Необходимые условия

Для интеграции с API Онлайн-сервиса «Отправка» необходимо располагать:

• токеном авторизации приложения;

• ключом авторизации пользователя.

Для отслеживания отправлений требования аналогичны.

Предлагаю вашему вниманию расширение для работы с api Почты России, которое решает следующие задачи:

1. Регистрация отправлений на сервере Почты России https://otpravka.pochta.ru, 2. Получение статуса отправления с сервера Почты России https://tracking.pochta.ru, 3. Хранение зарегистрированных отправлений в справочнике. 4. Обновление статусов отправлений по регламентному заданию.

Расширение протестировано на конфигурации Бухгалтерия предприятия, редакция 3 (3.0.142.67), на платформе 1С:Предприятие 8.3 (8.3.23.1865), с выключенным «Безопасным режимом» и с выключенным режимом «Защита от опасных действий». Расширение работает на платформах 8.3.20 и 8.3.21, думаю должна работать и на других конфигурациях в которых есть БСП т. к. заимствованный объект только один (Общий модуль «ДополнительныеОтчетыИОбработки»), необходим он для реализации работы регламентного задания. Процесс работы регламентного задания сохраняется в файл, во временной папке 1с.

Основной код находится в общем модуле ПР_Сервер, в расширении присутствуют две обработки для настройки доступа к API и созданию тестовых отправлений. Для работы расширения нужно использовать 2 функции, ПР_Сервер.ОтправитьПР() и ПР_Сервер.ОбновитьСтатусОтправленияПР(),

1. ОтправитьПР() - Регистрирует отправления на сервере Почты России, при успешной регистрации создает элементы в справочнике «ОтправленияПочтойРоссии». Принцип работы следующий:
   1. Проверка входящих параметров.
   2. Объединение адресов в один массив (для пакетного запроса) из входящего в функцию массива отправлений, элемент коллекции — это соответствие (адрес отправителя, номер телефона и т. п.).
   3. Нормализация адресов.
   4. Валидация адресов.
   5. Объединение телефонных номером и ФИО в массивы, только для валидированных адресов (для пакетных запросов) из входящего в функцию массива отправлений, элемент коллекции — это соответствие (адрес отправителя, номер телефона и т. п.).
   6. Нормализация телефонных номеров и ФИО.
   7. Проверка результатов нормализации ФИО с отбором отправлений, только успешно прошедших нормализацию.
   8. Создание заказов и регистрация отправлений на сервере Почты России.
   9. Объединение заказов в партии.
   10. Получение ярлыков отправлений, сохранение ярлыков у соответствующих элементов справочника в базе, сохранение лога для каждого отправления, обновление статуса отправления и сохранение результата.
   11. Возврат лога всего процесса.
2. ОбновитьСтатусОтправленияПР() - Получает статусы отправлений по переданным трек-номерам, создает элементы в справочнике «ОтправленияПочтойРоссии». Принцип работы следующий:
   1. Проверка входящих параметров, предварительная обработка данных.
   2. Подготовка данных к отправке в пакетном режиме с использованием WS-ссылки (для пакетного режима работы в таком варианте взаимодействия в спецификации к api для 1С описания нету).
   3. Обработка ответа по «тикету», в случае «неготовности» ответа создается задача, которая будет обработана регламентным заданием позже.
   4. При успешном получении информации с сервера Почты России, обновляется статус отправлений у соответствующих элементов справочника в базе, если в функцию передан параметр «ТрекНомера», в коллекции элементов которого есть свойство «ДокРТУ», тогда к данному документу будет добавлен трек-номер как дополнительное сведение.

В разработке мне помогли следующие статьи: 

Конфигурирование новых регламентных заданий с помощью расширения

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