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
- Obtain API keys from DostavkaBy and configure sender parameters.
- Develop a custom handler class inheriting
\Bitrix\Sale\Delivery\Services\Base.
- Connect events for automatic order creation upon order confirmation.
- Implement cost calculation and status synchronization.
- 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.
Common configuration errors
- Incorrect API key format (check case).
- Missing phone normalization: in Belarus, numbers must be in format +375XXXXXXXXX.
- Incorrect currency: all amounts in BYN, conversion needed for multi-currency stores.
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:
| DostavkaBy Status |
Bitrix Order Status |
| New |
Sent to delivery |
| Picked up by courier |
In transit |
| Delivered |
Delivered |
| Cancelled |
Cancelled |
| Return |
Return |
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
| Scope |
Components |
Time |
| Basic integration |
Calculation + order creation + statuses |
3–4 days |
| + Admin interface |
Order management block in order card |
+1–2 days |
| + Cash-on-delivery reconciliation |
Report + reconciliation with payouts |
+2 days |
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.
Delivery integration: from disparate APIs to a unified calculator in 5 days
A buyer abandons the cart at the shipping stage — they don't see a quote or see an obviously incorrect price. Each such case loses conversion. Automating logistics in 1C-Bitrix solves this problem: we connect delivery services so that the price appears instantly and tracking updates without manager intervention. Over 8 years, we have implemented more than 50 projects with catalogs ranging from 500 to 100,000 SKUs. Average time to connect one carrier is 4 days.
How to accelerate the connection of delivery services to 1C-Bitrix?
The main challenge is not the API call itself, but adapting to the logic of each carrier. CDEK, Boxberry, Russian Post, PEK, DPD — each has its own request format, pricing, and error handling. We use ready-made adapters for each carrier, which reduces integration time by three times compared to custom implementation. Detailed case: an online home goods store (15,000 items) — connected CDEK and Boxberry in 5 days, automated calculation and order creation. Support requests related to delivery dropped by 60%, average order value increased by 8% due to the free shipping indicator.
Why is each carrier's API a separate challenge?
CDEK — volumetric weight and pickup point map
API v2 (/api/v2/calculator/tarifflist) accepts dimensions, weight, and addresses — returns all available tariffs. Pitfalls: volumetric weight is calculated using the formula (L × W × H) / 5000. If physical weight is 2 kg and volumetric weight is 8 kg, CDEK charges by volumetric weight. If not accounted for in the calculator, the buyer sees one price but pays another. The pickup point map is loaded via /deliverypoints. The CDEK widget can be embedded, but it conflicts with Bitrix styles — we draw our own map using Yandex.Maps. Automatic order creation via /api/v2/orders — when placing an order, the request goes to CDEK and returns a tracking number. Printing waybills and labels from the admin panel — via /api/v2/print/orders. Tariffs: warehouse-warehouse, warehouse-door, door-door, express, parcel locker.
Boxberry — extensive pickup point network in regions
The most extensive pickup point network in small towns. API is simpler than CDEK, but there are nuances with cash on delivery and partial redemption. Pickup point map with filters: fitting, card payment, weekend operation. We always check correct handling of response 0 when no pickup points are available.
Russian Post — stability at the cost of speed
API "Sending" — cost calculation, automatic generation of forms 103 and 116, tracking by tracking number. Tariffs: parcel, printed matter, EMS. International shipments. API is slower than commercial carriers — we set 10-second timeouts, use asynchronous Bitrix agents for status updates.
PEK — heavy loads and groupage
When you need to ship a sofa or equipment. Calculation of groupage cargo, insurance, crate. Delivery to terminal and door-to-door. PEK terminal indices are loaded into an infoblock for auto-completion.
DPD — express delivery with time slots
DPD across Russia and abroad. Delivery within a selected time interval, return of signed documents. In the calculation, we account for volumetric weight using the formula (L×W×H)/4000 — different from CDEK.
Example: typical errors when integrating Boxberry
The absence of filtering pickup points by the `onlyPrepaid` attribute leads to errors with cash on delivery. Ignoring the `partialReturn` parameter breaks partial redemption. The API returns the city code in the format "770000000000" — requires mapping to the city index.How to combine different carriers in a single calculator?
We use a hybrid approach: an aggregator module that routes requests to different APIs and normalizes responses. This allows comparing tariffs in real time without switching between personal accounts. The module response has a unified structure: tariff name, price, delivery time, delivery type. Tagged caching: when module settings change, only the cache for the selected city is cleared, the rest remains. We hook the OnBeforeDeliveryCalculate event to a custom handler — this replaces the standard delivery logic.
Cost calculation: what pitfalls are encountered?
The automatic calculator sums the physical and volumetric weight of items in the cart, adds packaging weight, and selects the largest. Sounds simple, but:
- Dimensions must be filled for each item. No dimensions — no calculation. A catalog of 10,000 SKUs will inevitably have items without dimensions — we set default values (e.g., 0.1×0.1×0.1 m) and warn the manager via a mail event.
- Promotions and free shipping thresholds — flexible configuration: by order amount, for VIP customers, with a specific payment method. Implemented via custom cart properties.
- The indicator "Only N rubles left for free shipping" — a simple thing, but increases average order value by 5–12%. Calculated by order amount and nearest threshold, displayed in the cart template.
How to automate tracking, pickup, and courier delivery?
Tracking. Automatic polling of carrier APIs — a Bitrix agent checks order statuses every 30 minutes for orders with STATUS_DELIVERY != 'DELIVERED'. Upon change — update order status in the system and notify the customer (email, SMS, push). Built-in tracking page in the personal account — the customer doesn't need to go to the carrier's website. Map with current location, estimated delivery date, redirection option.
Pickup. Own pickup points on the map: addresses, schedule, contacts. Search for the nearest by customer address. Real-time availability check, reservation until a specific time. QR code for quick pickup and SMS about readiness.
Courier delivery. Delivery zones with different costs. 2-hour slots, courier schedule management, order limit per slot. Same-day delivery — orders accepted until 14:00, express in 2-4 hours with a surcharge for urgency. Integration with navigation for route optimization.
Multi-warehouse. Multiple warehouses with addresses and service zones. Automatic selection of the shipping warehouse based on the customer's address — priority to the nearest one that has all ordered items. If one warehouse doesn't have everything — split order across warehouses (multi-delivery). Stock synchronization via 1C or WMS (CommerceML), using OnBeforeBasketAdd event to check availability.
Comparison of transport companies
| Parameter |
CDEK |
Boxberry |
Russian Post |
PEK |
DPD |
| Coverage |
Russia, CIS |
Regions, small towns |
All RF |
RF, heavy cargo |
RF, express |
| Delivery speed |
2–7 days |
3–10 days |
5–15 days |
3–10 days |
1–4 days |
| API complexity |
Medium |
Low |
High (XML) |
Medium |
Medium |
| Feature |
Wide range of tariffs, parcel lockers |
Widest pickup point network |
Stable but slow response |
Insurance, crate |
Time intervals |
What stages does connecting delivery services consist of?
-
Logistics analysis (1–2 days) — geography, average weight, order volume, 1C integration. We recommend a combination of carriers.
-
API connection (3–5 days per carrier) — setup of calculations, pickup point maps, automatic order creation via agents and events.
-
Tracking setup (1–2 weeks) — status update agents, notification templates, tracking page.
-
Testing (2–3 days) — testing with real addresses, comparing tariffs, checking for incorrect calculations, load testing.
-
Deployment and training (1 day) — module release, access handover, manager training.
-
Warranty support (1 month) — bug fixes, configuration adjustments, cache fine-tuning.
Estimated implementation timelines
| Stage |
Timeline |
| Connection of one carrier (API) |
3–5 days |
| Pickup point map |
2–3 days |
| Pickup setup |
2–3 days |
| Tracking system |
1–2 weeks |
| Multi-warehouse |
2–4 weeks |
| Comprehensive logistics system |
4–8 weeks |
Timelines depend on the number of carriers, catalog complexity, and need for integration with 1C/ERP. Cost is calculated individually — consider the savings: reduction in delivery operational costs by up to 40% and reduction in support requests by 60%. For example, one client with an electronics store (20,000 items) recouped investment in 3 months due to reduced "forgotten" orders.
Ready to accelerate your online store's logistics? Contact us — we'll help select the optimal carrier combination for your assortment and budget. Request a consultation, and we'll prepare a proposal within 1 business day.
