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% порівняно з класичними фіскальними реєстраторами. Інтеграція займає в 2 рази менше часу, ніж звичайна ККТ.

Оцінка термінів інтеграції

Що входить у роботу

До складу робіт з інтеграції OrangeData з 1С-Бітрікс входить:

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

Ми пропонуємо інтеграцію під ключ за 4-5 днів. Пишіть нам для оцінки вашого проєкту. Наша компанія — 5+ років досвіду, 30+ проєктів з інтеграції фіскалізації. Обирайте нас: гарантія 54-ФЗ, зниження витрат на 50%.