Интеграция 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 — сдача партии на почту

Сроки