Setting up the exchange of mutual settlements between 1C and 1C-Bitrix

Configuring Mutual Settlements Exchange Between 1C and 1C-Bitrix

Mutual settlements in the customer's personal account is functionality in high demand for B2B online stores and wholesale portals. The buyer needs to see their current debt to the supplier, payment history, and outstanding balances on specific orders. All this data lives in 1C — and it needs to be transferred to 1C-Bitrix.

Mutual settlements data: what is stored in 1C

In 1C (UT, KA, ERP, BP), mutual settlements with counterparties are stored in the accumulation register MutualSettlementsWithCounterparties. Key data:

• Current accounts receivable — how much the counterparty owes the organization
• Accounts payable — if the organization owes the counterparty (overpayment, refund)
• Overdue debt — debt exceeding the credit limit or payment term
• Payment history — when and how much was paid
• Source documents — invoices, orders with outstanding balances

The standard CommerceML exchange does not transmit mutual settlements. This must be implemented separately.

Solution architecture

Two approaches are used to transfer mutual settlements to 1C-Bitrix:

Approach 1: 1C HTTP service. An HTTP service is created in 1C that returns mutual settlements for a specific counterparty on request. 1C-Bitrix calls this service when the "My Balance" page is opened in the personal account.

// Requesting mutual settlements from 1C-Bitrix
$response = file_get_contents(
    "https://1c.example.com/ut/hs/balance/get?counterparty_id={$guid}&key={$apiKey}"
);
$balance = json_decode($response, true);

Advantage: data is always up to date. Disadvantage: dependency on the 1C server availability.

Approach 2: Periodic synchronization. A scheduled task in 1C generates a file with mutual settlements data and transfers it to 1C-Bitrix (via FTP, API, or a direct script request). 1C-Bitrix saves the data in its own database and displays it to the client.

Advantage: independence from 1C availability at page load time. Disadvantage: data is delayed (by the synchronization interval, typically 30–60 minutes).

Implementation in 1C-Bitrix: data structure

For storing mutual settlements in 1C-Bitrix, it is recommended to create a HighloadBlock — for example, ContractorBalance:

For payment history — a separate HighloadBlock ContractorPayments with records for each payment.

Linking a counterparty to a 1C-Bitrix user

The primary technical challenge is knowing which 1C-Bitrix user corresponds to which counterparty in 1C. Options:

1. By user XML_ID. When registering on the site, a counterparty is created in 1C (via REST API), and their GUID is saved in the 1C-Bitrix user profile (field UF_1C_CONTRACTOR_ID).

2. By TIN (INN). The user enters their TIN during registration; the system searches for the counterparty in 1C by TIN.

3. Manual mapping. An administrator in 1C-Bitrix manually links the user to the counterparty. Suitable for B2B with a small number of clients.

Credit limit and order blocking

A common scenario: if a counterparty has overdue debt — block new orders on the site. Or: if debt exceeds the credit limit — show a warning.

Implementation via the 1C-Bitrix event OnSaleOrderBeforeSaved:

AddEventHandler('sale', 'OnSaleOrderBeforeSaved', 'checkDebtLimit');

function checkDebtLimit(\Bitrix\Main\Event $event) {
    $order = $event->getParameter('ENTITY');
    $userId = $order->getUserId();
    $debt = getContractorDebt($userId);
    $limit = getContractorCreditLimit($userId);

    if ($debt['overdue'] > 0) {
        $result = $event->getParameter('RESULT');
        $result->addError(new \Bitrix\Main\Error(
            'Order placement is unavailable: there is overdue debt'
        ));
    }
}

Case study: wholesale building materials portal

B2B portal: 300 active counterparties, each with a credit limit. Objective: display account balance in the personal account and block orders when the limit is exceeded.

Used the 1C HTTP service approach to retrieve current debt in real time. Response cached for 10 minutes (Redis). At checkout — always a fresh request, no cache.

Additionally: the personal account page displayed a detailed breakdown — a list of open invoices with amounts and payment dates. Data from a HighloadBlock updated once per hour.

Result: managers stopped manually notifying clients about debts. Clients see their balance themselves and pay before placing a new order. The number of calls asking "why can't I place an order" decreased significantly.