Skip to main content

​
Integration Scope

FiscalBox integration usually includes these blocks:
  • Order lifecycle (create, print, refuse)
  • Payment provider flow (Click, Payme, Uzum, Anor)
  • Reporting flow (Z-report open/close/print/info/sverka)
  • Device/tool operations (cash drawer, info, banners)

​
Prerequisites

  • Fiscal device/terminal access
  • API base URL for your environment
  • Billing credentials (for billing endpoints)
  • Clear mapping between POS fields and FiscalBox request fields
1

Authenticate where required

Use billing auth first when integrating billing-protected APIs:Store and rotate tokens according to your backend security policy.
2

Implement Order Create as core transaction

Start from:Validate required fields, numeric units, and response persistence (receipt_count, fiscal_sign, qr_url).
3

Add payment provider-specific routes

Integrate only providers you use in production:Keep provider-specific extra_info rules isolated in adapter logic.
4

Implement reporting and daily closing logic

Add report endpoints into end-of-day operations:
5

Handle operational endpoints

Add operational capabilities where needed:
6

Harden for production

Add:
  • Request/response audit logging
  • Idempotency strategy for retry safety
  • Timeout and retry policy per endpoint type
  • Monitoring for fiscal errors and printer/device failures

​
Data Mapping Checklist

  • Confirm all monetary/scaled values match expected units (for example *100, *1000 fields).
  • Ensure mandatory product metadata is always present (barcode, class_code, package_code, etc.).
  • Validate optional fields that become required for specific payment methods.
  • Preserve fiscal response fields for reconciliation and support operations.

​
Testing Strategy

  1. Use sandbox/test devices for integration tests.
  2. Cover both success and error payloads for each critical endpoint.
  3. Run end-to-end test for a full day cycle: open -> sales -> close.
  4. Verify receipt printing and QR links with real device conditions.

​
Production Readiness

  • Use server-side secure token storage.
  • Avoid sending duplicate fiscal operations without idempotency keys/checks.
  • Maintain structured logs for request IDs and fiscal response identifiers.
  • Define fallback UX for temporary API or device failures.

​
Common Integration Risks

Values sent in wrong unit scale lead to invalid totals or fiscal rejection. Centralize conversion rules in one service/module.
Payment providers can require extra fields depending on flow. Validate provider payloads before request dispatch.
Network retries without idempotency checks may create duplicated operations. Add retry guards and request tracing.