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

Інтеграція 1С-Bitrix зі службою доставки Dostavista

Dostavista — служба краудсорсингової кур'єрської доставки «останньої милі». Кур'єри працюють у режимі реального часу: заявка приймається протягом кількох хвилин, доставка виконується протягом кількох годин. API відкритий, документація російською мовою. Використовується для магазинів із швидкою доставкою: їжа, квіти, фармацевтика, електроніка.

Принцип роботи API Dostavista

Dostavista надає REST API. Авторизація — за токеном у заголовку X-Authorizationtoken. Основні методи:

• POST /api/business/v1/orders — створити заявку на доставку
• GET /api/business/v1/orders/{id} — отримати статус заявки
• DELETE /api/business/v1/orders/{id} — відмінити заявку
• GET /api/business/v1/couriers/{id}/location — координати кур'єра

Заявка містить точки маршруту (масив points): точка 0 — звідки забрати (склад/магазин), точки 1..N — адреси доставки покупців. Одне замовлення Dostavista може містити кілька точок доставки — це зручно для пакетних відправлень.

Модуль доставки в Bitrix

Служба доставки підключається через клас, що успадковує \Bitrix\Sale\Delivery\Services\Base. Ключові методи:

• calculateConcrete() — розраховує стоимість доставки. Викликає POST /api/business/v1/orders/calculate-price з адресою звідки/куди та вагою.
• createDelivery() — створює реальну заявку при підтвердженні замовлення менеджером або автоматично при зміні статусу.
• Обробник OnSaleStatusOrder — хук на зміну статусу замовлення в b_sale_order.

Параметри модуля зберігаються в b_sale_delivery_service_params: API_TOKEN, SHOP_POINT_ADDRESS (адреса складу), AUTO_CREATE (створювати заявку автоматично).

Розрахунок стоимості доставки

$response = $httpClient->post(
    'https://robot.dostavista.ru/api/business/v1/orders/calculate-price',
    [
        'matter'    => 'Товар з магазину',
        'weight_kg' => $weightKg,
        'points'    => [
            ['address' => $shopAddress],
            [
                'address'  => $deliveryAddress,
                'contact_person' => ['phone' => $phone],
            ],
        ],
    ],
    ['X-Authorizationtoken' => $apiToken]
);
$price = $response['order']['payment_amount'];

Відповідь містить payment_amount — сума до сплати в рублях (або місцевій валюті). Якщо адреса не визначена або виходить за межі зони покриття, API повертає помилку — обробляємо як «доставка недоступна».

Створення заявки при оформленні замовлення

Заявка створюється або автоматично при виборі покупцем способу доставки та підтвердженні замовлення, або вручну менеджером з адміністративної частини. Другий варіант переважніший для магазинів, де потрібна перевірка наявності перед відправленням.

В b_sale_order_props зберігаємо DOSTAVISTA_ORDER_ID — ідентифікатор заявки в системі Dostavista. Він потрібен для:

• відстеження статусу заявки (polling або webhook)
• скасування заявки при скасуванні замовлення в Bitrix
• передачі покупцю посилання для відстеження кур'єра

Статуси та синхронізація

Dostavista підтримує вебхуки: при зміні статусу заявки система робить POST-запит на зазначений URL. Налаштовується в особистому кабінеті. На стороні Bitrix створюємо обробник, який відображає статуси Dostavista на статуси замовлення:

Якщо вебхуки недоступні (немає білого IP), реалізуємо polling: агент Bitrix раз на 5–10 хвилин опитує статус активних заявок через GET /api/business/v1/orders/{id}.

Відстеження кур'єра

Dostavista повертає в заявці поле courier.latitude/courier.longitude при активній доставці. Для магазинів, яким потрібно показувати покупцю положення кур'єра на карті, реалізуємо AJAX-ендпоінт на стороні Bitrix — він проксує запит до API Dostavista та повертає координати.

Строки