Integrating 1C-Bitrix with the ApiShip delivery aggregator

Integration of 1C-Bitrix with ApiShip delivery aggregator

ApiShip is a delivery aggregator that provides a unified API for working with dozens of carriers: CDEK, Boxberry, PEC, Business Lines, Yandex.Delivery, Russian Post and others. Instead of separate integrations with each carrier, you connect one module and gain access to all carriers in the ApiShip catalog.

Advantages of aggregators over direct integrations

Direct integration with each carrier is a separate module, separate credentials, different data schema. When a carrier's API changes, each integration must be updated separately. ApiShip unifies this:

• Single authentication, uniform request format
• Cost calculation across all connected carriers in one request
• Creation of shipments through one endpoint
• Unified tracking of all orders
• Aggregated list of pickup points

The downside: the aggregator adds a layer, sometimes there are delays when updating the carrier's API. For stores with non-standard requirements for a specific carrier, direct integration may be more accurate.

ApiShip API

Base URL: https://api.apiship.ru/v2. Authorization: Bearer token. Test environment: https://api.test.apiship.ru/v2.

Key endpoints:

• POST /calculator — cost calculation across all active carriers
• POST /orders — create a request
• GET /orders/{id} — request status
• GET /points — list of pickup points
• GET /deliveries — list of connected carriers
• DELETE /orders/{id} — cancel

Delivery module in Bitrix

One module covers all services. Architectural choice: either one \Bitrix\Sale\Delivery\Services\Base class with a "carrier" parameter, or multiple instances of one class for different carriers (courier, pickup point, etc.). The second approach is more convenient for customers: they see separate delivery methods.

Parameters in b_sale_delivery_service_params:

• APISHIP_API_KEY — key from ApiShip personal account
• PROVIDER_KEY — carrier code (cdek, boxberry, russian_post, etc.)
• FROM_POINT_ID — ID of shipment point (warehouse in ApiShip system)
• DELIVERY_TYPE — door (courier) or point (pickup point)

Cost calculation

$calcRequest = [
    'fromPoint' => ['id' => $fromPointId],
    'toPoint'   => [
        'address' => $deliveryAddress,
        'cityId'  => $apishipCityId,
    ],
    'parameters' => [
        'weight' => $weightGram,
        'length' => $lengthCm,
        'width'  => $widthCm,
        'height' => $heightCm,
        'declaredValue' => $declaredValue,
    ],
    'deliveryType' => $deliveryType,
    'providers'    => [$providerKey], // empty array = all carriers
];

$results = $httpClient->post('/v2/calculator', $calcRequest);
// $results — array of options with price and delivery time for each carrier

If providers is an empty array, ApiShip will return calculations for all active carriers. This allows you to implement a delivery method comparison block on the site with prices.

Getting and storing pickup points

Pickup points in ApiShip are requested by filters:

GET /points?cityId={id}&providerKey={key}&type=pickup_point

We load once a day via agent for active carriers. We save in HL-block "Pickup Points" with fields: providerKey, pointId, name, address, lat, lng, workingHours, maxWeight. Display everything on the map in aggregate — the customer chooses any pickup point from any carrier.

When a pickup point is selected, we save in b_sale_order_props: APISHIP_PROVIDER_KEY and APISHIP_POINT_ID.

Creating a request

$orderPayload = [
    'providerKey'     => $providerKey,
    'senderPointId'   => $fromPointId,
    'deliveryType'    => $deliveryType,
    'toPoint'         => [
        'id'      => $pvzId,   // if pickup point
        'address' => $address, // if courier
    ],
    'recipient'       => ['name' => $name, 'phone' => $phone],
    'parameters'      => $parameters,
    'orderNumber'     => 'SHOP-' . $bitrixOrderId,
    'declaredValue'   => $declaredValue,
    'cashOnDelivery'  => $codAmount,
    'places'          => $places,
];

Response: orderId in the ApiShip system and trackingNumber of the carrier. We save both in b_sale_order_props.

Tracking and statuses

Webhooks: ApiShip sends POST when status changes. We register the URL in the personal account. Statuses are unified for all carriers — one mapping works for all.

Timeline