Інтеграція 1С-Бітрікс зі службою доставки Пошта Росії

Інтеграція 1С-Бітрікс зі службою доставки Пошта Росії

Пошта Росії — єдина служба з покриттям усіх населених пунктів країни, що робить інтеграцію з нею практично обов'язковою для магазинів, які продають у малі міста та села. API Пошти Росії (Отправка 2.0) значно краще за старий, але все одно вимагає розуміння специфіки: нормалізація адрес, види відправлень, пакетний режим, накладений платіж.

API Пошти Росії: принципи роботи

Базовий URL: https://otpravka-api.pochta.ru. Авторизація: два токени одночасно — Authorization: AccessToken TOKEN та X-User-Authorization: Basic BASE64(login:password).

Ключові групи методів:

• /1.0/user/shipping-points — адреси відправки (звідки)
• /1.0/clean/address — нормалізація адреси
• /1.0/tariff — розрахунок тарифу
• /1.0/user/backlog — пакетне завантаження відправлень
• /1.0/batch/{batchName}/shipment — створення відправлень у партії
• /1.0/shipment/search — трекінг за штрихкодом

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

Головна проблема Пошти Росії — якість адрес, які вводять покупці. API вимагає коректних адрес у форматі ФІАС. Нормалізація — перший крок перед будь-якою операцією:

private function normalizeAddress(string $rawAddress): array
{
    $response = $this->apiPost('/1.0/clean/address', [
        [
            'id'            => 'addr1',
            'original-address' => $rawAddress,
        ]
    ]);

    $normalized = $response[0] ?? [];

    if (($normalized['quality-code'] ?? '') === 'GOOD') {
        return $normalized;
    }

    // Якщо якість погана — повертаємо помилку, не створюємо відправлення
    throw new \RuntimeException(
        'Адресу не нормалізовано: ' . ($normalized['quality-code'] ?? 'unknown')
    );
}

Коди якості: GOOD — повністю нормалізовано, POSTAL_BOX — абонентська скринька, ON_DEMAND — до запитання, UNDEF_* — різні проблеми з нормалізацією. Лише GOOD гарантує правильну доставку.

Розрахунок тарифу

private function calcTariff(
    array $normalizedAddress,
    int $weightGram,
    string $mailType = 'POSTAL_PARCEL'
): float {
    $response = $this->apiPost('/1.0/tariff', [
        'object-type'        => $mailType,
        'mail-category'      => 'ORDINARY',
        'from-index'         => $this->getOption('FROM_INDEX'), // індекс відправки
        'to-index'           => $normalizedAddress['index'],
        'mass'               => $weightGram,
        'dimension'          => [
            'height' => 200,
            'length' => 300,
            'width'  => 200,
        ],
    ]);

    return ($response['total-rate'] ?? 0) / 100; // копійки → рублі
}

Пошта Росії повертає вартість у копійках — не забуваємо ділити на 100. Типи відправлень: POSTAL_PARCEL (посилка), EMS (експрес), EMS_OPTIMAL (оптимальний ЕМС), FIRST_CLASS (перший клас).

Пакетний режим: створення відправлень

Пошта Росії працює через партії (batch). Не можна створити одиночне відправлення — потрібно створити партію, додати до неї відправлення, надіслати на друк.

public function createShipment(\Bitrix\Sale\Shipment $shipment): string
{
    $order = $shipment->getOrder();
    $props = $order->getPropertyCollection();

    // 1. Отримуємо або створюємо партію
    $batchName = $this->getOrCreateBatch($shipment);

    // 2. Створюємо відправлення в партії
    $payload = [[
        'address-type-to'     => 'DEFAULT',
        'mail-type'           => 'POSTAL_PARCEL',
        'mail-category'       => 'ORDINARY',
        'mass'                => $this->getWeight($shipment),
        'index-to'            => $this->getNormalizedIndex($props),
        'recipient-name'      => $props->getItemByOrderPropertyCode('FIO')?->getValue(),
        'tel-address'         => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
        'str-index-to'        => $this->getNormalizedIndex($props),
        'order-num'           => (string)$order->getId(),
        'payment'             => $this->getCashOnDelivery($order), // накладений платіж
    ]];

    $response = $this->apiPost("/1.0/batch/{$batchName}/shipment", $payload);
    $barcode = $response['result-ids'][0] ?? null;

    if ($barcode) {
        $props->getItemByOrderPropertyCode('POCHTA_BARCODE')?->setValue($barcode);
        $order->save();
    }

    return $barcode ?? '';
}

Накладений платіж

Накладений платіж (COD — cash on delivery) — ключова функція Пошти Росії для e-commerce. Поле payment у запиті містить суму до отримання від покупця в копійках. Якщо накладений платіж не потрібен — передаємо 0.

При накладеному платежі Пошта утримує комісію (~2–3%) і перераховує залишок на розрахунковий рахунок магазину. Терміни перерахування — до 10 робочих днів.

Трекінг через API Пошти Росії

public function trackShipment(string $barcode): array
{
    $response = $this->apiGet('/1.0/shipment/search', ['query' => $barcode]);
    $events = $response['trackingData']['trackingItem']['trackingHistoryItem'] ?? [];

    $lastEvent = end($events);
    return [
        'status'    => $lastEvent['humanStatus'] ?? '',
        'date'      => $lastEvent['eventDateTime'] ?? '',
        'city'      => $lastEvent['cityName'] ?? '',
        'barcode'   => $barcode,
    ];
}

Трекінг через основний API обмежений за частотою запитів. Для магазинів з великим навантаженням використовується окремий Tracking API з іншою квотою.

Друк марок і форм

Після додавання відправлень до партії доступний друк ф7 (адресний ярлик) і ф107/ф112 (супровідні документи):

GET /1.0/forms/{barcode}/f7pdf — адресний ярлик
GET /1.0/batch/{batchName}/checkin — здача партії на пошту

Терміни