Контур интеграции
Интеграция FiscalBox обычно включает следующие блоки:- Жизненный цикл заказа (
create,print,refuse) - Поток платежных провайдеров (Click, Payme, Uzum, Anor)
- Поток отчетов (Z-report open/close/print/info/sverka)
- Операции устройства/инструментов (cash drawer, info, banners)
Предварительные условия
- Доступ к фискальному устройству/терминалу
- Base URL API для вашей среды
- Billing credentials (для billing endpointов)
- Понятное маппирование полей POS в поля запроса FiscalBox
Рекомендуемый порядок интеграции
Настройте аутентификацию где требуется
Начните с billing auth при интеграции billing-защищенных API:Храните и обновляйте токены согласно политике безопасности backend.
Реализуйте Order Create как основную транзакцию
Начните с:Проверьте обязательные поля, масштабы числовых значений и сохранение ответа (
receipt_count, fiscal_sign, qr_url).Добавьте отчетность и ежедневное закрытие
Встройте эндпоинты отчетов в операции конца дня:
- Z-Report Open
- Z-Report Close
- Связанные endpointы печати/info/sverka
Реализуйте операционные endpointы
Добавьте операции при необходимости:
Checklist маппирования данных
- Проверьте, что денежные/масштабируемые значения соответствуют ожидаемым единицам (
*100,*1000). - Убедитесь, что обязательные метаданные товара всегда передаются (
barcode,class_code,package_codeи т.д.). - Валидируйте optional-поля, которые могут стать обязательными для конкретных методов оплаты.
- Сохраняйте фискальные поля ответа для сверки и support-операций.
Стратегия тестирования
- Используйте sandbox/тестовые устройства для интеграционных тестов.
- Покройте успешные и ошибочные payloadы для каждого критичного endpointа.
- Проведите end-to-end тест полного дневного цикла: open -> sales -> close.
- Проверьте печать чека и QR-ссылки в реальных условиях устройства.
Готовность к production
- Используйте безопасное хранение токенов на стороне сервера.
- Избегайте дубликатов фискальных операций без idempotency keys/проверок.
- Ведите структурированные логи с request ID и фискальными идентификаторами ответа.
- Определите fallback UX для временных сбоев API или устройства.
Частые риски интеграции
Несоответствие масштаба суммы
Несоответствие масштаба суммы
Значения в неверном масштабе приводят к ошибкам суммы или фискальному отказу. Вынесите правила конвертации в один сервис/модуль.
Ошибки полей конкретного провайдера
Ошибки полей конкретного провайдера
Платежные провайдеры могут требовать дополнительные поля в зависимости от сценария. Валидируйте payload провайдера до отправки.
Дубликаты фискальных операций при retry
Дубликаты фискальных операций при retry
Retry без idempotency-проверок может создать дубликаты операций. Добавьте retry guard и request tracing.