Интеграция 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. Для точного расчёта стоимости и сроков оставьте заявку — мы подготовим коммерческое предложение в течение суток.