Setting up integration with 1C-Bitrix laboratory information systems

Setting Up Integration with Laboratory Information Systems in 1C-Bitrix

A laboratory accepts test orders online and through collection points. Results are processed in a Laboratory Information System (LIS) — specialized software for managing samples, analytical equipment, and results. Patients want to receive results in their personal account on the website rather than waiting for a paper form or calling a hotline. The goal is to publish test results from the LIS in the 1C-Bitrix personal account.

Common LIS Systems in Russia

• QLAB (Qualab) — one of the most widely used, REST API
• CaLab — oriented toward private laboratories, REST/SOAP
• LIMS (custom-built) — large laboratories often have custom systems
• MedWork / Eralis — REST API
• Helix Lab — closed system, integration available for partners only

The APIs all differ. What they share is a common data structure: referral (order) → samples → tests → results.

Laboratory Order Data Model

-- Test orders
CREATE TABLE local_lab_orders (
    ID              BIGINT AUTO_INCREMENT PRIMARY KEY,
    USER_ID         INT NOT NULL,
    EXTERNAL_ORDER_ID VARCHAR(100) NOT NULL UNIQUE,  -- ID in the LIS
    ORDER_DATE      DATE,
    STATUS          ENUM('received','processing','completed','cancelled') DEFAULT 'received',
    SYNCED_AT       DATETIME,
    INDEX idx_user (USER_ID),
    INDEX idx_external (EXTERNAL_ORDER_ID)
);

-- Test results
CREATE TABLE local_lab_results (
    ID              BIGINT AUTO_INCREMENT PRIMARY KEY,
    ORDER_ID        BIGINT NOT NULL,
    TEST_CODE       VARCHAR(50),   -- test code (ICD / LOINC / proprietary)
    TEST_NAME       VARCHAR(500),
    RESULT_VALUE    VARCHAR(500),  -- text value (number, +/-, text)
    RESULT_UNIT     VARCHAR(100),  -- unit of measurement
    REFERENCE_MIN   VARCHAR(100),  -- reference minimum
    REFERENCE_MAX   VARCHAR(100),  -- reference maximum
    IS_ABNORMAL     CHAR(1) DEFAULT 'N', -- outside reference range
    RESULT_DATE     DATETIME,
    PDF_PATH        VARCHAR(500),  -- path to PDF form
    INDEX idx_order (ORDER_ID)
);

LIS API Client (QLAB Example)

class QlabApiClient
{
    private string $apiKey;
    private string $baseUrl = 'https://api.qlab.ru/v2';

    public function getOrdersByPatient(string $patientPhone, string $dateFrom): array
    {
        return $this->request('GET', '/orders', [
            'patient_phone' => $patientPhone,
            'date_from'     => $dateFrom,
            'status'        => 'completed',
        ]);
    }

    public function getOrderResults(string $orderId): array
    {
        return $this->request('GET', "/orders/{$orderId}/results");
    }

    public function getResultPdf(string $orderId): string
    {
        // Returns binary PDF
        $response = $this->rawRequest('GET', "/orders/{$orderId}/pdf");
        return $response;
    }

    public function createOrder(array $patientData, array $tests): array
    {
        return $this->request('POST', '/orders', [
            'patient'   => $patientData,
            'tests'     => $tests,
            'source'    => 'website',
        ]);
    }

    private function request(string $method, string $path, array $data = []): array
    {
        $url = $this->baseUrl . $path;
        if ($method === 'GET' && $data) {
            $url .= '?' . http_build_query($data);
        }

        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST  => $method,
            CURLOPT_HTTPHEADER     => [
                "X-Api-Key: {$this->apiKey}",
                'Accept: application/json',
                'Content-Type: application/json',
            ],
            CURLOPT_POSTFIELDS => $method === 'POST' ? json_encode($data) : null,
        ]);

        $json     = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode >= 400) {
            throw new \RuntimeException("QLAB API error {$httpCode}: {$json}");
        }

        return json_decode($json, true) ?? [];
    }
}

Results Synchronization

An agent checks incomplete orders every 15 minutes:

function SyncLabResults(): string
{
    $qlabClient = new QlabApiClient(QLAB_API_KEY);

    // Active orders without a final status
    $pendingOrders = LocalLabOrdersTable::getList([
        'filter' => ['STATUS' => ['received', 'processing']],
        'select' => ['ID', 'EXTERNAL_ORDER_ID', 'USER_ID'],
    ]);

    while ($order = $pendingOrders->fetch()) {
        try {
            $lisData = $qlabClient->getOrderResults($order['EXTERNAL_ORDER_ID']);

            if (($lisData['status'] ?? '') === 'completed') {
                // Save results
                foreach ($lisData['results'] ?? [] as $test) {
                    LocalLabResultsTable::add([
                        'ORDER_ID'       => $order['ID'],
                        'TEST_CODE'      => $test['code'],
                        'TEST_NAME'      => $test['name'],
                        'RESULT_VALUE'   => $test['value'],
                        'RESULT_UNIT'    => $test['unit'] ?? '',
                        'REFERENCE_MIN'  => $test['ref_min'] ?? '',
                        'REFERENCE_MAX'  => $test['ref_max'] ?? '',
                        'IS_ABNORMAL'    => ($test['abnormal'] ?? false) ? 'Y' : 'N',
                        'RESULT_DATE'    => $test['result_date'],
                    ]);
                }

                // Download and save PDF
                $pdf     = $qlabClient->getResultPdf($order['EXTERNAL_ORDER_ID']);
                $pdfPath = "/upload/lab-results/{$order['USER_ID']}/{$order['EXTERNAL_ORDER_ID']}.pdf";
                file_put_contents($_SERVER['DOCUMENT_ROOT'] . $pdfPath, $pdf);

                // Update status
                LocalLabOrdersTable::update($order['ID'], [
                    'STATUS'    => 'completed',
                    'SYNCED_AT' => new \Bitrix\Main\Type\DateTime(),
                ]);

                // Notify patient
                $user = \Bitrix\Main\UserTable::getById($order['USER_ID'])->fetch();
                \CEvent::Send('LAB_RESULTS_READY', SITE_ID, [
                    'EMAIL'      => $user['EMAIL'],
                    'NAME'       => $user['NAME'],
                    'ORDER_ID'   => $order['EXTERNAL_ORDER_ID'],
                    'RESULT_URL' => '/personal/lab-results/' . $order['ID'] . '/',
                ]);
            }
        } catch (\Exception $e) {
            \CEventLog::Add([
                'SEVERITY'    => 'WARNING',
                'AUDIT_TYPE_ID' => 'LAB_SYNC',
                'DESCRIPTION' => "Order {$order['EXTERNAL_ORDER_ID']}: {$e->getMessage()}",
            ]);
        }
    }

    return __FUNCTION__ . '();';
}

"My Tests" Component in Personal Account

class LabResultsComponent extends CBitrixComponent
{
    public function executeComponent(): void
    {
        $userId = (int)\Bitrix\Main\Engine\CurrentUser::get()->getId();

        $orders = LocalLabOrdersTable::getList([
            'filter' => ['USER_ID' => $userId],
            'order'  => ['ID' => 'DESC'],
            'select' => ['ID', 'EXTERNAL_ORDER_ID', 'ORDER_DATE', 'STATUS'],
        ])->fetchAll();

        // For each completed order — fetch results
        foreach ($orders as &$order) {
            if ($order['STATUS'] === 'completed') {
                $order['RESULTS'] = LocalLabResultsTable::getList([
                    'filter' => ['ORDER_ID' => $order['ID']],
                    'order'  => ['TEST_NAME' => 'ASC'],
                ])->fetchAll();
            }
        }

        $this->arResult = ['ORDERS' => $orders, 'USER_ID' => $userId];
        $this->includeComponentTemplate();
    }
}

Security: Access Restricted to Own Results

Critical: verify USER_ID on every request for results. PDF files are stored outside the webroot or access-controlled via PHP:

// /local/ajax/download-lab-result.php
$userId  = \Bitrix\Main\Engine\CurrentUser::get()->getId();
$orderId = (int)$_GET['order_id'];

$order = LocalLabOrdersTable::getList([
    'filter' => ['ID' => $orderId, 'USER_ID' => $userId],
])->fetch();

if (!$order) {
    http_response_code(403);
    exit;
}

$pdfPath = $_SERVER['DOCUMENT_ROOT'] . '/upload/lab-results/' . $userId . '/' . $order['EXTERNAL_ORDER_ID'] . '.pdf';
header('Content-Type: application/pdf');
header('Content-Disposition: attachment; filename="result-' . $order['EXTERNAL_ORDER_ID'] . '.pdf"');
readfile($pdfPath);

Scope of Work

• Analysis of the specific LIS API, data format agreement
• PHP LIS API client
• Orders and results tables
• Results synchronization agent, PDF download
• "My Tests" component in personal account
• Email notification when results are ready
• Access control for PDFs and result data

Timeline: 3–5 weeks with a documented REST LIS API. 6–10 weeks with SOAP or a non-standard protocol.