1C-Bitrix – DostavkaBy Integration (Belarus): Delivery Automation

1C-Bitrix Integration with DostavkaBy (Belarus)

You open an online store for Belarus and face a challenge: how to connect reliable and automated delivery? Bitrix out of the box does not know local operators, and manually entering orders into the delivery service's personal dashboard takes up to 2 hours per day per manager. For 50 orders per month, that's 100 hours of lost time on routine tasks. Errors in manual entry occur in 15% of cases. Delays, lost shipments, conflicts, and unhappy customers.

DostavkaBy is one of the most popular courier services in Belarus with the widest coverage. We have been integrating Bitrix with dozens of delivery services across CIS countries for 6 years, including all major courier services. For DostavkaBy, we have encountered challenges: non-standard authentication, specifics of Belarusian addresses, and a complex cash-on-delivery scheme. We share our accumulated experience and are ready to implement a full turnkey integration.

How We Integrate? 5 Steps

1. Obtain API keys from DostavkaBy and configure sender parameters.
2. Develop a custom handler class inheriting \Bitrix\Sale\Delivery\Services\Base.
3. Connect events for automatic order creation upon order confirmation.
4. Implement cost calculation and status synchronization.
5. Test all scenarios: creation, cancellation, modification, cash-on-delivery.

DostavkaBy API

DostavkaBy provides a REST API for partners. Documentation and credentials are provided upon signing a contract. Authentication is Basic Auth or token, depending on the API version. Format is JSON.

Basic operations:

• Create delivery order
• Get order status
• Calculate cost
• Get tracking
• Cancel/change order

How Does the Delivery Module Work in Bitrix?

The 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

According to Bitrix documentation, developing a custom handler is a standard practice.

Specifics of Belarusian Logistics

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

Currency BYN. All amounts in Belarusian rubles. For multi-currency stores, convert via CCurrencyRates Bitrix.

Addressing. Belarus does not use FIAS/KLADR. Addresses are entered as free text or through the delivery service's own classifiers. In some cases, it's sufficient to pass city + address as strings.

Cash-on-delivery. This operation is standard for the Belarusian market. For cash-on-delivery, DostavkaBy collects money from the buyer and transfers it to the store minus commission on a schedule (usually once a week).

Why Does Cash-on-Delivery Require Separate Integration?

For stores with cash-on-delivery, reconciliation is critical: how much DostavkaBy collected and when transferred. Without automation, managers manually match data from the delivery service's dashboard and Bitrix orders. We implement a report in the admin area: export of cash-on-delivery orders by period with amounts and transfer dates. Data is fetched via DostavkaBy API (if the payout registry method is available) or maintained semi-automatically.

How to Synchronize Order Statuses?

For low order volumes (up to 100 per day), polling suffices: a Bitrix agent checks active order statuses every 30 minutes. For higher volumes, we set up webhooks: DostavkaBy sends notifications on status changes.

Typical status mapping:

What Is Included in the Integration Work?

We provide a full scope of work:

• Development of a custom delivery handler class inheriting Base
• Configuration of API keys and sender parameters
• Creation of events for automatic order creation upon order confirmation
• Integration with the payment system for cash-on-delivery tracking
• Testing all scenarios: calculation, creation, cancellation, status changes
• Documentation and training for managers on using the order management block
• 30-day warranty on integration functionality after completion

Cost Calculation

In calculateConcrete(), we request the delivery cost for the recipient's address. Minimum calculation parameters: delivery city, parcel weight, delivery type (courier). Optional: declared value, dimensions (affects cost for oversized parcels).

If HTTP 200 with a price is received, we return it in the CalculationResult object. If the address is outside the coverage area or the API is unavailable, we return an error without blocking the order checkout (the buyer sees "delivery unavailable for your address").

Order Creation and Management

Orders are created automatically upon order confirmation (hook on OnSaleStatusOrder event) or manually by the manager. In the order card in the admin area, we add a "DostavkaBy Delivery" block with buttons:

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

The DostavkaBy order ID is stored in b_sale_order_props as a custom property DOSTAVKA_BY_ID.

Timeline

Over 6 years, we have implemented more than 50 integrations with various delivery services, including DostavkaBy. Automation reduces order processing time by 3 times and eliminates errors. Contact us for a free project evaluation. Or order a consultation – we'll provide details.

More about Bitrix delivery services documentation.