При інтеграції Пошти Росії в інтернет-магазин розробники стикаються з двошаровою моделлю відправлень: спочатку замовлення потрапляє в беклог, потім його потрібно додати в партію, щоб отримати ШПІ. За досвідом понад 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 виникають через помилки в назві населеного пункту або відсутність вулиці. Рекомендуємо реалізувати автодоповнення адреси через сервіси ФІАС перед відправкою нормалізації. Для розрахунку тарифу надсилаємо 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();
}
Покрокова інструкція для тестування
- Отримайте тестові облікові дані в sandbox (видаються за запитом при укладанні договору).
- Створіть замовлення з нормалізованою адресою через метод
/user/backlog. - Додайте замовлення в партію через
/batchі отримайте тестовий ШПІ. - Викличте трекінг-API з цим ШПІ та перевірте, що статус змінюється коректно.
- Протестуйте розрахунок тарифів для різних типів відправлення та ваг.
Часті помилки при інтеграції
| Помилка | Причина | Рішення |
|---|---|---|
| UNDEF_05 | Адресу не знайдено | Перевірте нормалізацію адреси; використовуйте автодоповнення |
| Невірний тип відправлення | Зазначено непідтримуваний mail-type | Використовуйте POSTAL_PARCEL або ECOM_MARKETPLACE |
| Перевищення квоти трекінгу | Більше 100 запитів на один трек на добу | Реалізуйте кешування або збільште квоту |
Чому API Пошти Росії складніше, ніж у СДЕК?
СДЕК вимагає один запит на створення замовлення й одразу повертає трек-номер. Пошта Росії — мінімум два запити (беклог + партія). Крім того, обов'язкова нормалізація адрес. Зате покриття в Пошти Росії втричі більше: відділення є навіть у населених пунктах, де немає кур'єрських служб. Для інтернет-магазинів, які торгують по всій країні, це критично. Якщо ви вже зіткнулися з помилками UNDEF_05 або не можете налаштувати тарифи, зв'яжіться з нами — ми проведемо аудит вашої інтеграції та виправимо проблеми.
Що входить у роботу при замовленні інтеграції?
| Етап | Зміст | Орієнтовний термін |
|---|---|---|
| Аналітика | Розбір бізнес-процесів, вибір методів API, підготовка документації | 1–2 дні |
| Розробка | Реалізація розрахунку тарифів, нормалізації адрес, створення замовлень | 6–8 днів |
| Тестування | Перевірка на sandbox, інтеграційне тестування | 2–3 дні |
| Деплой | Налаштування прав доступу, кешування, моніторингу | 1 день |
| Підтримка | Навчання команди, документація, гарантійний супровід 2 тижні | включено |
Терміни: базова інтеграція (тільки розрахунок тарифів) — від 3 робочих днів. Повна інтеграція зі створенням замовлень і трекінгом — 10–14 робочих днів. Джерело: Офіційна документація API Пошти Росії. При правильному налаштуванні тарифів можна суттєво економити на кожній посилці. Зв'яжіться з нами, щоб обговорити ваш проєкт і отримати консультацію. Замовте інтеграцію — ми підберемо оптимальне рішення за один день.