Інтеграція Європошти з 1С-Бітрікс: повне підключення

Інтеграція Європошти з 1С-Бітрікс: повне підключення

При інтеграції служби доставки Європошта з 1С-Бітрікс часто виникають проблеми: нестандартний розрахунок ваги посилок (мінімальний поріг 0.05 кг), плутанина з післяплатою, відсутність автоматичного відстеження. Ми вирішуємо ці завдання вже довгі роки та реалізували понад 30 інтеграцій для білоруських інтернет-магазинів. Наше рішення під ключ включає все: від налаштування API до карти ПВЗ на сайті. Європошта — приватний поштовий оператор із широкою мережею пунктів видачі. API надається партнерам після реєстрації.

З якими проблемами стикаються магазини?

Основні технічні складнощі: нестандартний розрахунок ваги (потрібен мінімальний поріг 0.05 кг), неправильна передача коду післяплати, відсутність синхронізації статусів. Додатково — низька продуктивність через часті запити до API при розрахунку доставки. Стандартні компоненти доставки в Бітрікс не оптимізовані для Європошти — часті запити сповільнюють сторінку. Наш компонент використовує теговане кешування та зменшує навантаження на сервер у 2-3 рази. Середня економія часу на обробку одного замовлення — до 60%.

Чому варто інтегрувати Європошту через наш компонент?

Ми використовуємо теговане кешування результатів розрахунку, що скорочує навантаження на сервер у 2-3 рази. На відміну від стандартних рішень, наш компонент підтримує автоматичне визначення cod за способом оплати, виключаючи ручні помилки. Ми передаємо cod як числове значення з двома знаками після коми, як це передбачено в офіційній документації API Європошти.

Як налаштувати розрахунок вартості без помилок?

class EuropachtaHandler extends \Bitrix\Sale\Delivery\Services\Base { protected function calculateConcrete( \Bitrix\Sale\Shipment $shipment ): \Bitrix\Sale\Delivery\CalculationResult { $result = new \Bitrix\Sale\Delivery\CalculationResult(); $order = $shipment->getOrder(); $response = $this->apiPost('/rate/calculate', [ 'from_city' => $this->getOption('SENDER_CITY'), 'to_city' => $this->getOrderCity($shipment), 'weight' => max($shipment->getWeight() / 1000, 0.05), 'declared' => round($order->getPrice()), 'delivery_type' => $this->getOption('DELIVERY_TYPE', 'pvz'), ]); if (!empty($response['price'])) { $result->setDeliveryPrice((float)$response['price']); $days = $response['days'] ?? '2–5'; $result->setPeriodDescription("{$days} днів"); } return $result; } } 

Створення замовлення з післяплатою

public function createOrder(\Bitrix\Sale\Shipment $shipment): string { $order = $shipment->getOrder(); $props = $order->getPropertyCollection(); $payload = [ 'external_id' => 'bitrix_' . $order->getId(), 'delivery_type' => $this->getOption('DELIVERY_TYPE', 'pvz'), 'weight' => max($shipment->getWeight() / 1000, 0.05), 'declared' => round($order->getPrice()), 'cod' => $this->getCodAmount($order), 'sender' => [ 'name' => $this->getOption('SENDER_NAME'), 'phone' => $this->getOption('SENDER_PHONE'), 'address' => $this->getOption('SENDER_ADDRESS'), ], 'recipient' => [ 'name' => $props->getItemByOrderPropertyCode('FIO')?->getValue(), 'phone' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(), 'city' => $this->getOrderCity($shipment), 'pvz_id' => $props->getItemByOrderPropertyCode('EUROPOCHTA_PVZ')?->getValue(), ], 'items' => $this->buildItems($shipment), ]; $response = $this->apiPost('/order/create', $payload); return (string)($response['order_id'] ?? ''); } 

Поле cod — сума післяплати. Якщо замовлення передплачене, передаємо 0. Якщо післяплата — передаємо повну суму замовлення. Ми автоматично визначаємо cod за способом оплати, виключаючи ручні помилки.

Обробка помилок API та валідація даних

При інтеграції критично важлива надійна обробка помилок. API Європошти може повернути коди помилок: 401 (невірні облікові дані), 400 (невірний формат запиту), 404 (місто не знайдено в довіднику), 500 (помилка на стороні сервера). У кожному випадку потрібна різна стратегія: для 401 потрібна перевірка API-ключів у конфігурації, для 400 — валідація даних адреси та ваги, для 404 — запропонувати користувачу вибрати альтернативне місто або район доставки, для 500 — відкласти повтор запиту на 10-30 секунд з експоненційною затримкою. Всі помилки мають логуватися з повною інформацією про параметри запиту для налагодження. Ми використовуємо вбудовану систему логування Бітрікс та відправляємо критичні помилки сповіщеннями менеджерам.

Чому важливо правильно реалізувати післяплату?

Неправильна передача cod призводить до спорів з покупцями та втрати грошей. Автоматизація за способом оплати гарантує, що сума стягується коректно.

Як ми прискорюємо роботу служби доставки?

Для кешування списку ПВЗ використовуємо Bitrix\Main\Data\Cache з часом життя 12 годин. Агент перевіряє статуси замовлень раз на 3-4 години, оскільки вебхуків у Європошти немає. Наш компонент оптимізований так, що сторінка оформлення замовлення не гальмує навіть при високих навантаженнях.

Тестування інтеграції та пошук несправностей

Перед запуском у production необхідно протестувати всі сценарії: розрахунок доставки для різних ваг (включаючи граничний випадок 0.05 кг), створення замовлень з різними способами оплати, синхронізацію статусів для доставлених і повернутих посилок. Рекомендується спочатку працювати з sandbox-оточенням Європошти (якщо доступно), потім перейти на production з невеликим трафіком. Регулярно перевіряйте логи агента в панелі адміністратора Бітрікс, щоб виявити збої API або некоректні дані адрес. Часті помилки: невірний формат телефону (використовуйте міжнародний формат +375...), відсутність міста в довіднику Європошти, перевищення API rate limit (зазвичай 100 запитів на хвилину — додайте throttling на рівні компонента).

Безпека та найкращі практики

API-ключі та облікові дані Європошти ніколи не повинні зберігатися в коді — використовуйте змінні середовища або захищене сховище параметрів у Бітрікс (опція .env файлу або local.php). Всі запити до API Європошти мають йти по захищеному каналу HTTPS з верифікацією SSL-сертифікатів. При логуванні ніколи не зберігайте повний API-ключ або чутливі дані користувачів (паспортні дані, повні адреси) в логах — логуйте лише ID замовлень та стани. Обмежте доступ до адмін-панелі компонента тільки для довірених менеджерів через права користувачів Бітрікс. Рекомендується регулярно ротувати API-ключі (раз на 90 днів) та перевіряти логи доступу на предмет незвичної активності.

Що входить в роботу

• Налаштування служби доставки в Бітрікс з розрахунком вартості через API
• Створення замовлень автоматично при оформленні
• Відображення списку ПВЗ з кешуванням (випадний список або карта)
• Автоматичне відстеження та оновлення статусів (агент з налаштовуваним інтервалом)
• Підтримка післяплати з автоматичним визначенням cod
• Вихідний код компонента та документація з експлуатації
• Навчання менеджерів роботі з новими статусами

Терміни

Зв'яжіться з нами для консультації з налаштування. Замовте інтеграцію під ключ — отримайте готове рішення за 3-7 днів. Розрахуємо вартість вашого проекту безкоштовно.