Integration of 1C-Bitrix with the DostavkaBy delivery service (Belarus)

1C-Bitrix Integration with DostavkaBy Delivery Service (Belarus)

DostavkaBy is a Belarusian courier delivery service oriented to e-commerce on RB market. Delivery to Minsk and regions, cash on delivery support, returns. For shops operating on Belarusian market, DostavkaBy is one of local alternatives to major operators.

DostavkaBy API

DostavkaBy provides REST API for partners. Documentation and credentials provided upon contract conclusion. Authorization via Basic Auth or token depending on API version. Format — JSON.

Basic operations:

• Creating delivery request
• Getting request status
• Cost calculation
• Getting tracking
• Canceling/changing request

Delivery Module in Bitrix

Class inherits \Bitrix\Sale\Delivery\Services\Base. Parameters in b_sale_delivery_service_params:

• DOSTAVKA_API_KEY — API key
• SENDER_NAME — sender name
• SENDER_PHONE — sender phone
• SENDER_ADDRESS — warehouse or pickup point address

Features of Belarusian Logistics

Working with Belarusian delivery services has specifics common to most RB operators:

Phone format. All numbers — +375XXXXXXXXX. Normalize incoming number before sending: remove spaces, brackets, dashes, add 375 if entered in local format 80XXXXXXXX.

Currency BYN. All sums in Belarusian rubles. Multi-currency shop — convert via CCurrencyRates Bitrix.

Addressing. Belarus doesn't use FIAS/KLADR system. Addresses — free string or via service's own classifiers. Sometimes enough to pass city + address string.

Cash on delivery. Standard operation for RB market. With cash on delivery, DostavkaBy collects money from customer and transfers to shop minus commission per schedule (usually once per week).

Cost Calculation

In calculateConcrete() request delivery cost for recipient address. Minimum calculation parameters: delivery city, package weight, delivery type (courier). Additionally — declared value, dimensions (affect cost for oversized packages).

If received HTTP 200 with price — return in CalculationResult object. If address outside coverage or API unavailable — return error without blocking order (customer sees "delivery unavailable for your address").

Creating and Managing Requests

Requests created automatically on order confirmation (hook to OnSaleStatusOrder event) or manually by manager. In order card in admin part add "DostavkaBy Delivery" block with buttons:

• "Create request" (if not created yet)
• "Show status"
• "Print label"
• "Cancel request"

DostavkaBy request ID saved to b_sale_order_props as custom property DOSTAVKA_BY_ID.

Status Synchronization

With small order volume (up to 50–100 per day), polling sufficient: Bitrix agent every 30 minutes checks statuses of active requests. With higher volume — setup webhooks: DostavkaBy sends notifications on status change.

Typical status mapping:

Payment Integration

For shops with cash on delivery, reconciliation is important: how much DostavkaBy collected and when transferred. Implement report in admin part: export orders with cash on delivery for period with sums and transfer dates. Get data via DostavkaBy API (if payout report export method exists) or maintain manually.

Timeline