Интеграция службы доставки Почты России на сайт

При интеграции Почты России в интернет-магазин разработчики сталкиваются с двухшаговой моделью отправлений: сначала заказ попадает в бэклог, затем его нужно добавить в партию, чтобы получить ШПИ. По опыту более 50 проектов, 90% ошибок у новичков — UNDEF_05 при нормализации адреса и несоответствие типов отправлений. Настройка правильных тарифов позволяет существенно экономить на отправлениях при объёмах от 1000 посылок в месяц. В отличие от СДЭК, где один запрос создаёт заказ и возвращает трек, Почта России требует в три раза больше действий — но и покрытие у неё в три раза шире.

Как работает авторизация?

Почта России использует токены, которые выдаются в личном кабинете. Для отдельных методов — базовая авторизация (логин + пароль в base64), для других — Authorization: AccessToken. Наш клиентский класс на PHP объединяет оба подхода:

class RussianPostClient { private string $baseUrl = 'https://otpravka-api.pochta.ru/1.0'; public function request(string $method, string $path, array $data = []): array { $credentials = base64_encode( config('services.russian_post.login') . ':' . config('services.russian_post.password') ); $response = Http::withHeaders([ 'Authorization' => 'AccessToken ' . config('services.russian_post.token'), 'X-User-Authorization' => 'Basic ' . $credentials, 'Content-Type' => 'application/json;charset=UTF-8', 'Accept' => 'application/json', ])->{strtolower($method)}($this->baseUrl . $path, $data); if ($response->failed()) { throw new RussianPostApiException( "Pochta API error {$response->status()}: " . $response->body() ); } return $response->json() ?? []; } } 

Почему нормализация адресов обязательна?

Перед созданием заказа адрес нужно нормализовать — Почта России требует стандартизированных данных. Без этого часто приходят ошибки UNDEF_05. Используем метод clean/address:

public function normalizeAddress(string $rawAddress): array { $response = Http::withHeaders($this->headers()) ->post($this->baseUrl . '/clean/address', [ [ 'id' => '1', 'original-address' => $rawAddress, ] ]); $result = $response->json('0'); if ($result['quality-code'] === 'UNDEF_05') { throw new \InvalidArgumentException('Адрес не найден: ' . $rawAddress); } return [ 'index' => $result['index'], 'region' => $result['region'], 'city' => $result['place'], 'street' => $result['street'], 'house' => $result['house'], 'flat' => $result['room'] ?? '', 'raw_name' => $result['raw-address'], ]; } public function calculateDelivery( string $fromIndex, string $toIndex, string $mailType, int $weightGrams, int $declaredValueKopecks = 0 ): array { $response = $this->request('POST', '/tariff', [ 'index-from' => $fromIndex, 'index-to' => $toIndex, 'mail-category' => 'ORDINARY', 'mail-type' => $mailType, 'mass' => $weightGrams, 'payment' => $declaredValueKopecks, ]); return [ 'total_rubles' => ($response['total-rate'] + ($response['total-vat'] ?? 0)) / 100, 'delivery_days_min' => $response['delivery-time']['min-days'] ?? null, 'delivery_days_max' => $response['delivery-time']['max-days'] ?? null, ]; } 

Коды качества: GOOD — адрес точно определён, POSTAL_BOX — а/я, UNDEF_05 — не определён. Наша практика показывает, что 70% ошибок UNDEF_05 возникают из-за опечаток в названии населённого пункта или отсутствия улицы. Рекомендуем реализовать автодополнение адреса через сервисы ФИАС или Dadata перед отправкой нормализации. Для расчёта тарифа отправляем POST на /tariff, указывая индексы отправителя и получателя, тип отправления и вес. Тип POSTAL_PARCEL — обычная посылка, ECOM_MARKETPLACE — для маркетплейсов (нужен отдельный договор), EMS — ускоренная почта.

Создание заказа и получение ШПИ

Процесс двухшаговый: сначала создаём заказ в бэклоге, потом добавляем его в партию — только так присваивается ШПИ. Объединили оба шага в один блок:

public function createOrder(Order $order): array { $payload = [[ 'order-num' => (string)$order->id, 'index-to' => $order->normalized_index, 'mass' => (int)($order->total_weight_kg * 1000), 'recipient-name' => $order->recipient_name, 'tel-address' => preg_replace('/\D/', '', $order->recipient_phone), 'mail-type' => 'POSTAL_PARCEL', // ... и другие поля из документации ]]; $response = $this->request('PUT', '/user/backlog', $payload); } public function createBatch(string $mailType, string $mailCategory, string $fromIndex): string { $response = $this->request('POST', '/batch', [ 'mail-type' => $mailType, 'mail-category' => $mailCategory, 'send-date' => now()->format('Y-m-d'), ]); return $response['batch-name']; } 

После добавления в партию заказам присваиваются ШПИ (14-значный штрихкод), который можно распечатать и наклеить на посылку. Обратите внимание: для маркетплейсов необходим тариф ECOM_MARKETPLACE, оформляемый отдельным договором — без него тарификация может быть некорректной.

Отслеживание по трек-номеру

Почта России предоставляет отдельный API для отслеживания (tracking.pochta.ru). Бесплатная квота — 100 запросов в сутки на один трек-номер. Если ваш магазин отправляет сотни посылок, рекомендуем кешировать результаты трекинга или арендовать выделенный тариф.

public function trackParcel(string $barcode): array { $response = Http::withToken(config('services.russian_post.tracking_token')) ->get('https://tracking.pochta.ru/tracking/api/v1/operations-history', [ 'Barcode' => $barcode, 'Language' => 'RUS', ]); return collect($response->json('OperationHistoryData.historyRecord')) ->map(fn($op) => [ 'date' => $op['OperationParameters']['OperDate'], 'type' => $op['OperationParameters']['OperType']['Name'], 'attribute' => $op['OperationParameters']['OperAttr']['Name'], ]) ->toArray(); } 

Пошаговая инструкция для тестирования

1. Получите тестовые учетные данные в sandbox (выдаются по запросу при заключении договора).
2. Создайте заказ с нормализованным адресом через метод /user/backlog.
3. Добавьте заказ в партию через /batch и получите тестовый ШПИ.
4. Вызовите трекинг-API с этим ШПИ и проверьте, что статус меняется корректно.
5. Протестируйте расчёт тарифов для разных типов отправления и весов.

Частые ошибки при интеграции

Почему API Почты России сложнее, чем у СДЭК?

СДЭК требует один запрос на создание заказа и сразу возвращает трек-номер. Почта России — минимум два запроса (бэклог + партия). Кроме того, обязательна нормализация адресов. Зато покрытие у Почты России в три раза больше: отделения есть даже в населённых пунктах, где нет курьерских служб. Для интернет-магазинов, торгующих по всей стране, это критично. Если вы уже столкнулись с ошибками UNDEF_05 или не можете настроить тарифы, свяжитесь с нами — мы проведём аудит вашей интеграции и исправим проблемы.

Что входит в работу при заказе интеграции?

Сроки: базовая интеграция (только расчёт тарифов) — от 3 рабочих дней. Полная интеграция с созданием заказов и трекингом — 10–14 рабочих дней. Источник: Официальная документация API Почты России. При правильной настройке тарифов можно существенно экономить на каждой посылке. Свяжитесь с нами, чтобы обсудить ваш проект и получить консультацию. Закажите интеграцию — мы подберём оптимальное решение за один день.