Integration of 1C-Bitrix with UkrPoshta delivery service (Ukraine)

Integration of 1C-Bitrix with UkrPoshta delivery service (Ukraine)

We often encounter stores that need to deliver goods to settlements where Nova Poshta branches are not available. UkrPoshta is the only state operator covering all of Ukraine, including villages and small towns. After restructuring, the API became modern: REST with JWT authorization. However, developers often stumble on the mandatory sequential creation of objects (address → client → shipment) and on address string parsing. Let's walk through the implementation on Bitrix. Each stage requires careful handling, otherwise integration can drag on for weeks. We have accumulated experience with over 10 projects where UkrPoshta was the primary carrier, and we are ready to share the details.

How to authorize in the UkrPoshta API?

Authorization is done via a Bearer token in the header Authorization: Bearer <token>. To get the token, send a POST request to /api/2.0/client-token, passing the key from your personal account. The base API URL: https://www.ukrposhta.ua/ecom/0.0.1. The token has a limited validity period, so it needs to be refreshed periodically. In Bitrix, it is convenient to store it in the module settings and update via an agent. The token timeout is 30 minutes, so the agent should run at least every 25 minutes. Check that there are no restrictions on agent execution in your hosting settings.

Creating a shipment

UkrPoshta requires sequential creation of objects: address → client → shipment. Below is an example handler in PHP for the bitrix:sale.order.ajax component:

class UkrPoshtaHandler
{
    public function createShipment(\Bitrix\Sale\Shipment $shipment): string
    {
        $order = $shipment->getOrder();
        $props = $order->getPropertyCollection();

        // Step 1: create recipient address
        $addr = $this->apiPost('/addresses', [
            'postcode'    => $props->getItemByOrderPropertyCode('ZIP')?->getValue(),
            'city'        => $props->getItemByOrderPropertyCode('CITY')?->getValue(),
            'street'      => $props->getItemByOrderPropertyCode('ADDRESS')?->getValue(),
            'houseNumber' => '1',
        ]);
        $addressUuid = $addr['uuid'];

        // Step 2: create recipient
        $client = $this->apiPost('/clients', [
            'firstName'   => $this->parseFirstName($props),
            'lastName'    => $this->parseLastName($props),
            'phoneNumber' => $props->getItemByOrderPropertyCode('PHONE')?->getValue(),
            'type'        => 'INDIVIDUAL',
            'addressId'   => $addressUuid,
        ]);
        $clientUuid = $client['uuid'];

        // Step 3: create shipment
        $response = $this->apiPost('/shipments', [
            'sender'          => ['uuid' => $this->getOption('SENDER_UUID')],
            'recipient'       => ['uuid' => $clientUuid],
            'deliveryType'    => 'W2D',
            'weight'          => max((int)$shipment->getWeight(), 20),
            'length'          => (int)$this->getOption('DEFAULT_LENGTH', 20),
            'width'           => (int)$this->getOption('DEFAULT_WIDTH', 20),
            'height'          => (int)$this->getOption('DEFAULT_HEIGHT', 5),
            'declaredPrice'   => (int)round($order->getPrice()),
            'description'     => 'Goods',
            'paidByRecipient' => false,
        ]);

        return $response['uuid'] ?? '';
    }
}

paidByRecipient: false — the store pays for delivery. If true, the recipient pays upon receipt. Note: UkrPoshta API returns an error if the houseNumber field is missing. In a real project, you should take it from an order property, otherwise parsing may fail.

Delivery types

The choice of type affects cost and delivery times. Based on experience, W2D is most often used for online stores — customers prefer home delivery.

How to implement shipment tracking?

After creating a shipment, save its UUID. Then set up an agent in Bitrix that calls GET /shipments/{uuid}/statuses every 3-4 hours. The received statuses can be logged or displayed in the order admin panel. Here is a simple implementation:

// Agent called every 3 hours
public function trackShipments(): string
{
    $shipments = \Bitrix\Sale\Shipment::getList([
        'filter' => ['!UKRPOSHTA_UUID' => null, '!=STATUS' => 'DELIVERED']
    ]);
    foreach ($shipments as $shipment) {
        $statuses = $this->apiGet("/shipments/{$shipment['UKRPOSHTA_UUID']}/statuses");
        // Update order status
        if (!empty($statuses)) {
            \Bitrix\Sale\Order::update($shipment['ORDER_ID'], [
                'UKRPOSHTA_STATUS' => end($statuses)['code']
            ]);
        }
    }
    return 'trackShipments();';
}

This approach allows seeing the current location of the parcel without manual updates.

Getting a label

// Print label — button in Bitrix order admin
public function getLabel(string $shipmentUuid): string
{
    $response = $this->apiGet("/shipments/{$shipmentUuid}/label");
    return base64_decode($response['pdf_base64'] ?? '');
}

The method returns a PDF file that can be saved or displayed to the user. In the admin area, it's convenient to add a "Print label" button directly in the shipment card.

What to know about international shipments?

For routes UA→BY, UA→PL and others: customs declaration CN22/CN23, weight limit up to 30 kg, mandatory HS code for goods. We recommend adding a user property UF_HS_CODE to products in the information block and automatically passing it to the declaration. Without this, UkrPoshta will reject the request. Also note: for international shipments, the country code must be specified in the recipient's address and the sender's country.

Address field specifics

UkrPoshta expects separate fields: street, house number, apartment. In Bitrix, the address is usually stored as a single string. You either need to add separate fields to the order form or implement address string parsing. The second approach gives about 85% accuracy, while the first is more reliable. In our projects, we use custom order properties "Street", "House", "Apartment" — this eliminates recognition errors. For example, when parsing, the house number is often confused with the apartment, especially in addresses like "Gagarin St., 10, apt. 5".

What is included in turnkey integration

• Setting up the delivery module and obtaining tokens
• Creating custom order properties for separate address fields
• Implementing the shipment handler with UkrPoshta API calls
• Generating and printing a waybill in PDF format
• Setting up background tracking (agent with 3-4 hour interval)
• Integrating customs declaration for international parcels
• Preparing documentation and handing over access

This list covers all typical complexities. We guarantee stable data exchange and full support after implementation. If you need integration with UkrPoshta, contact us to assess your project. Get a consultation on stages and timelines to start without unnecessary delays.

Timelines

Timelines are given assuming all client accesses are ready. On average, the project takes one week. We work with Bitrix and have implemented over 10 integrations with Ukrainian postal services. Reach out — we'll help set up delivery via UkrPoshta in your store.

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.

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

What stages does connecting delivery services consist of?

1. Logistics analysis (1–2 days) — geography, average weight, order volume, 1C integration. We recommend a combination of carriers.
2. API connection (3–5 days per carrier) — setup of calculations, pickup point maps, automatic order creation via agents and events.
3. Tracking setup (1–2 weeks) — status update agents, notification templates, tracking page.
4. Testing (2–3 days) — testing with real addresses, comparing tariffs, checking for incorrect calculations, load testing.
5. Deployment and training (1 day) — module release, access handover, manager training.
6. Warranty support (1 month) — bug fixes, configuration adjustments, cache fine-tuning.

Estimated implementation timelines

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.