Интеграция OrangeData с 1С-Битрикс: настройка, возвраты, опыт 5+ лет

Интеграция с OrangeData для 1С-Битрикс

При попытке интеграции OrangeData с 1С-Битрикс разработчики сталкиваются с неочевидными сложностями: асинхронная фискализация, двойной обмен с 1С, необходимость строго соблюдать 54-ФЗ. Без готового модуля приходится писать кастомный обработчик платёжной системы — и это лишь половина дела. OrangeData — облачный фискальный регистратор, работающий по схеме «касса как сервис». Физической кассы у магазина нет: OrangeData сам хранит и обслуживает оборудование, а вы получаете API для отправки чеков. Это удобно, пока не начинаете разбираться в деталях: авторизация через сертификаты X509, асинхронная фискализация, специфическая схема атрибутов чека под 54-ФЗ. Наша компания занимается такими интеграциями более 5 лет, реализовала свыше 30 проектов для интернет-магазинов на 1С-Битрикс, и знает все подводные камни.

Архитектура OrangeData REST API

OrangeData использует REST API с взаимной TLS-аутентификацией. Это не просто токен в заголовке — нужен клиентский X509-сертификат, который выдаётся при регистрации. Каждый запрос к API подписывается приватным ключом из этого сертификата. Основные эндпоинты:

• POST /api/v2/documents/ — отправить документ (чек прихода, возврата, коррекции)
• GET /api/v2/documents/{id} — получить результат фискализации по идентификатору

Важный момент: фискализация асинхронная. После POST получаете 202 Accepted, а не готовый чек. Реальный фискальный признак появляется через несколько секунд или минут — нужно опрашивать GET-эндпоинт или ждать callback.

Структура запроса на отправку чека

$document = [
    'id' => uniqid('', true), // уникальный идентификатор документа
    'inn' => $inn,
    'group' => 'Main',
    'key' => $signatureKeyName, // имя ключа из личного кабинета OrangeData
    'content' => [
        'type' => 1, // 1 - приход, 2 - возврат прихода
        'positions' => $this->buildPositions($payment),
        'checkClose' => [
            'payments' => [
                [
                    'type' => $this->getPaymentType($payment), // 1-наличные, 2-безнал
                    'amount' => $payment->getSum(),
                ],
            ],
            'taxationSystem' => 0, // 0-ОСН, 1-УСН доход, 2-УСН доход-расход
        ],
        'customerContact' => $this->getCustomerContact($order),
    ],
];

Поле positions — массив позиций чека. Каждая позиция содержит quantity, price, tax (код ставки НДС), text (наименование), paymentMethodType и paymentSubjectType. Последние два поля — требование 54-ФЗ с момента его вступления в силу: нужно явно указать, что продаётся (товар, услуга, работа) и каким способом (предоплата, полный расчёт).

private function buildPositions(\Bitrix\Sale\Payment $payment): array
{
    $order = $payment->getOrder();
    $basket = $order->getBasket();
    $positions = [];

    foreach ($basket as $item) {
        $positions[] = [
            'quantity'           => $item->getQuantity(),
            'price'              => $item->getPrice(),
            'tax'                => $this->mapVatRate($item->getField('VAT_RATE')),
            'text'               => $item->getField('NAME'),
            'paymentMethodType'  => 4, // 4 - полный расчёт
            'paymentSubjectType' => 1, // 1 - товар
        ];
    }

    // Доставка как отдельная позиция
    if ($order->getDeliveryPrice() > 0) {
        $positions[] = [
            'quantity'           => 1,
            'price'              => $order->getDeliveryPrice(),
            'tax'                => 6, // без НДС
            'text'               => 'Доставка',
            'paymentMethodType'  => 4,
            'paymentSubjectType' => 4, // 4 - услуга
        ];
    }

    return $positions;
}

TLS-аутентификация: настройка в PHP

Отправка запросов с клиентским сертификатом через cURL:

private function apiRequest(string $method, string $path, array $data = []): array
{
    $ch = curl_init('https://api.orangedata.ru:12003' . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_POSTFIELDS     => json_encode($data),
        CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
        CURLOPT_SSLCERT        => $this->certPath,       // путь к .crt
        CURLOPT_SSLKEY         => $this->keyPath,        // путь к .key
        CURLOPT_CAINFO         => $this->caPath,         // корневой сертификат OrangeData
        CURLOPT_SSL_VERIFYPEER => true,
    ]);

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

    if ($httpCode === 202) {
        return ['status' => 'queued'];
    }

    return json_decode($response, true);
}

Сертификаты и ключи хранятся вне webroot — например, в /local/certs/orangedata/. Пути передаются через настройки обработчика платёжной системы. Никогда не кладите .key-файл в public_html.

Асинхронная фискализация: механизм работы

После отправки документа нужно дождаться фискального признака. Реализация через агента:

1. После успешного POST сохраняем в b_sale_order_props поля ORANGEDATA_DOC_ID и ORANGEDATA_STATUS = pending.
2. Агент OrangeDataCheckAgent запускается каждую минуту, выбирает заказы с ORANGEDATA_STATUS = pending, опрашивает GET /api/v2/documents/{id}.
3. При получении статуса done — сохраняем фискальные данные (fn, fd, fpd, ссылка на чек) и меняем ORANGEDATA_STATUS = done.
4. Фискальные данные отправляются покупателю по email через событие SALE_NEW_ORDER или отдельным письмом.

public static function run(): string
{
    $pendingOrders = self::getPendingOrders();
    foreach ($pendingOrders as $orderId => $docId) {
        $result = self::checkDocumentStatus($docId);
        if (($result['status'] ?? '') === 'done') {
            self::saveFiscalData($orderId, $result);
        }
    }
    return __CLASS__ . '::run();';
}

Типичные ошибки при интеграции

Самая частая — неправильный путь к сертификату. Если CURLOPT_SSLCERT указывает на несуществующий файл, cURL возвращает ошибку SSL certificate problem. Вторая по частоте — игнорирование кода 202 Accepted: разработчики ждут мгновенного ответа и не реализуют поллинг. Третья — неверный маппинг ставок НДС. OrangeData использует числовые коды: 1 (НДС 20%), 2 (НДС 10%), 3 (НДС 0%), 4 (НДС 20/120), 5 (НДС 10/110), 6 (без НДС). Если передать код 0, API вернёт ошибку 400 Bad Request.

Сравнение OrangeData и традиционной кассы

OrangeData — облачный сервис, не требующий покупки и обслуживания физического оборудования. Экономия на содержании кассы достигает 50% по сравнению с классическими фискальными регистраторами.

Оценка сроков интеграции

Содержание работ

В состав работ по интеграции OrangeData с 1С-Битрикс входит:

• Разработка кастомного обработчика платёжной системы с отправкой чеков через OrangeData API.
• Настройка TLS-аутентификации и хранение сертификатов вне webroot.
• Реализация асинхронного поллинга статусов через агенты Битрикс.
• Обработка возвратов (полных и частичных).
• Маппинг ставок НДС и атрибутов paymentMethodType/paymentSubjectType.
• Подключение тестового контура и отладка.
• Email-отправка фискальных чеков покупателям.
• Документация по поддержке и список доступов.

Свяжитесь с нашими инженерами для предварительной оценки интеграции OrangeData. Для точного расчёта стоимости и сроков оставьте заявку — мы подготовим коммерческое предложение в течение суток.