WT Otpravkapochtaru - библиотека сервиса Отправка Почты России для Joomla

Описание

WT Otpravkapochtaru — пакет для Joomla 5+, который помогает расширениям сайта работать с API «Отправка» Почты России и SOAP-сервисом отслеживания. В пакет входят библиотека и системный плагин с настройками подключения.

Документация ниже подготовлена для публикации в карточке проекта SW JProjects. Она не заменяет полную справку разработчика в репозитории, а объясняет рабочие сценарии: как подключиться, подготовить данные, рассчитать доставку, создать отправление, собрать партию, получить документы, оформить возврат и запросить сведения по трекингу.

Официальная спецификация Почты России доступна по адресу: https://otpravka.pochta.ru/specification#/main.

Системные требования

• Joomla 5+
• PHP 8.3+
• Расширения PHP:
  • ext-mbstring
  • ext-simplexml
  • ext-soap (опционально, для трекинга)
  • ext-zip

Что умеет библиотека?

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

Поддерживаются:

• получение настроек аккаунта, точек сдачи и текущего остатка запросов к API;
• нормализация адресов, ФИО и телефонов перед созданием отправления;
• расчёт тарифа и срока доставки через актуальный REST-метод Почты России;
• создание, поиск, изменение, удаление и возврат заказов в состояние «Новые»;
• проверка надёжности получателя;
• создание партий, просмотр партий и заказов внутри партии;
• генерация пакета печатных документов и формы Ф103;
• создание, изменение и удаление возвратных отправлений;
• поиск отделений по индексу, адресу и координатам, получение сервисов отделения;
• локальный список стран;
• SOAP-отслеживание операций по РПО и работа с билетами пакетного трекинга.

Не реализованы как отдельные публичные методы:

• архив партий и долгосрочное хранение;
• временные интервалы и бронирование таймслотов;
• заявления на дополнительные услуги;
• пользовательские сессии API;
• все дополнительные печатные формы из официальной спецификации, кроме пакета документов и Ф103.

Такое ограничение сделано осознанно: библиотека закрывает основной поток отправки и отслеживания, не превращая Joomla-пакет в полную копию официальной спецификации.

Установка и настройка

Установите ZIP-пакет через стандартный менеджер расширений Joomla. После установки откройте плагин System - WT Otpravkapochtaru и заполните параметры подключения:

• токен доступа приложения;
• режим авторизации;
• пользовательский ключ или пару «логин и пароль»;
• отдельные учётные данные SOAP-трекинга, если нужен трекинг;
• таймаут HTTP-запросов.

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

Типичный сценарий отправки

В рабочем сценарии не стоит сразу создавать заказ из пользовательской формы. Сначала приведите входные данные к виду, который ожидает Почта России.

1. Нормализация адреса отправителя и получателя.
2. Нормализация ФИО и телефона получателя.
3. Используйте нормализованный индекс и адрес в расчёте тарифа.
4. Соберите заказ из нормализованных данных.
5. Создайте заказ в "Новых".
6. После проверки нескольких заказов сформируйте партию.
7. Получите печатные документы.

Такой порядок снижает количество ошибок API и делает поведение интеграции предсказуемым.

Пример: нормализация и расчёт через API «Отправка»

<?php

declare(strict_types=1);

use LapayGroup\RussianPost\AddressList;
use LapayGroup\RussianPost\Enum\MailCategory;
use LapayGroup\RussianPost\Enum\MailType;
use LapayGroup\RussianPost\Enum\PaymentMethods;
use LapayGroup\RussianPost\FioList;
use LapayGroup\RussianPost\ParcelInfo;
use LapayGroup\RussianPost\PhoneList;
use Webtolk\Otpravkapochtaru\Otpravkapochtaru;

defined('_JEXEC') or die;

// Библиотека читает параметры из включенного системного плагина Joomla; массив параметров можно передать явно, но здесь показан Joomla-способ.
$client = new Otpravkapochtaru();

$api = $client->otpravkaApi();

$addresses = new AddressList();
$addresses->add('410000, Saratov, Moskovskaya St., 1');
$normalizedAddress = $api->clearAddress($addresses);

$names = new FioList();
$names->add('Ivanov Ivan Ivanovich');
$normalizedName = $api->clearFio($names);

$phones = new PhoneList();
$phones->add('+7 900 000-00-00');
$normalizedPhone = $api->clearPhone($phones);

$parcel = new ParcelInfo();
$parcel->setIndexFrom(410000);
$parcel->setIndexTo(685000);
$parcel->setMailType(MailType::PARCEL_POSTAL);
$parcel->setMailCategory(MailCategory::ORDINARY);
$parcel->setWeight(1000);
$parcel->setPaymentMethod(PaymentMethods::CASHLESS);

$tariff = $api->getDeliveryTariff($parcel);

// Joomla использует реализацию VarDumper из Symfony для dd().
dd($normalizedAddress, $normalizedName, $normalizedPhone, $tariff);

В ответах API денежные значения обычно приходят в копейках. Поэтому перед показом пользователю сумму нужно делить на 100 и форматировать в соответствии с интерфейсом сайта.

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

<?php

declare(strict_types=1);

use LapayGroup\RussianPost\Entity\Order;
use Webtolk\Otpravkapochtaru\Otpravkapochtaru;

defined('_JEXEC') or die;

// Библиотека читает параметры из включенного системного плагина Joomla; массив параметров можно передать явно, но здесь показан Joomla-способ.
$client = new Otpravkapochtaru();

// Создаём объект заказа
$order = new Order();
$order->setOrderNum('JSHOP-10001');
$order->setIndexTo('685000');
$order->setRegionTo('Магаданская область');
$order->setPlaceTo('Магадан');
$order->setStreetTo('ул. Ленина');
$order->setHouseTo('1');
$order->setRecipientName('Иванов Иван Иванович');
$order->setTelAddress('79000000000');
$order->setMailType('POSTAL_PARCEL');
$order->setMailCategory('ORDINARY');
$order->setMass(500);

$created = $client->otpravkaApi()->createOrders([$order->asArr()]);

// Joomla использует реализацию VarDumper из Symfony для dd().
dd($created);

Для изменения уже созданного заказа используйте editOrder(), для удаления заказов из «Новых» — deleteOrders(). Если заказ нужно вернуть в «Новые», используйте returnOrdersToNew().

Партии и документы

Когда заказы проверены и готовы к передаче в отделение, сформируйте партию:

<?php

declare(strict_types=1);

use LapayGroup\RussianPost\Providers\OtpravkaApi;
use Webtolk\Otpravkapochtaru\Otpravkapochtaru;

defined('_JEXEC') or die;

// Библиотека читает параметры из включенного системного плагина Joomla; массив параметров можно передать явно, но здесь показан Joomla-способ.
$client = new Otpravkapochtaru();

$api = $client->otpravkaApi();
$batch = $api->createBatch([123456789, 123456790]);
$batchName = (string) ($batch['batch-name'] ?? '');

if ($batchName !== '') {
    $document = $api->generateDocPackage($batchName, OtpravkaApi::PRINT_FILE);
    file_put_contents(JPATH_ROOT . '/tmp/' . $batchName . '.zip', $document->getStream()->getContents());
}

Методы документов возвращают двоичные данные. Сохраняйте их в защищённое место и не выводите в браузер без корректных заголовков Content-Type и Content-Disposition.

Возвраты

Возвратное отправление можно создать по ШПИ прямого отправления или как отдельное возвратное отправление. Для отдельного возврата используйте сущность ReturnShipment, если хотите явно собрать payload и переиспользовать его в тестах.

Основные методы:

• createReturnShipment() создаёт возврат для ранее созданного отправления;
• createReturnShipments() создаёт отдельные возвратные отправления;
• editReturnShipment() меняет отдельное возвратное отправление;
• deleteReturnShipment() удаляет отдельное возвратное отправление.

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

Методы поиска отделений полезны до создания заказа: с их помощью можно проверить индекс, найти ближайшее отделение и узнать доступные сервисы.

<?php

declare(strict_types=1);

use Webtolk\Otpravkapochtaru\Otpravkapochtaru;

defined('_JEXEC') or die;

// Библиотека читает параметры из включенного системного плагина Joomla; массив параметров можно передать явно, но здесь показан Joomla-способ.
$client = new Otpravkapochtaru();

$api = $client->otpravkaApi();
$office = $api->searchPostOfficeByIndex('685000');
$services = $api->getPostOfficeServices('685000');

// Joomla использует реализацию VarDumper из Symfony для dd().
dd($office, $services);

Список стран хранится локально и не расходует лимит REST API.

Отслеживание почтовых отправлений

REST API сервиса «Отправка» отвечает за создание отправлений. Для отслеживания отправлений у Почты России сделан отдельный сервис трекинга, поэтому для него нужны отдельные учётные данные. Их можно запросить через тех.поддержку или получить при оформлении и договора

<?php

declare(strict_types=1);

use Webtolk\Otpravkapochtaru\Otpravkapochtaru;

defined('_JEXEC') or die;

// Библиотека читает параметры из включенного системного плагина Joomla; массив параметров можно передать явно, но здесь показан Joomla-способ.
$client = new Otpravkapochtaru();

$operations = $client->trackingApi()->getOperationsByRpo('12345678901234', 'RUS');

// Joomla использует реализацию VarDumper из Symfony для dd().
dd($operations);

Если у аккаунта нет доступа к SOAP-трекингу, REST-сценарии отправки всё равно могут работать.

JSON-схемы ответов API Отправки Почты России

Для удобства отладки и разработки в репозитории есть папка с JSON, полученными на реальных запросах к API. Снимки актуальны на момент публикации релиза. С течением времени в реальных ответах API могут быть изменения.