> ## Documentation Index
> Fetch the complete documentation index at: https://dev.fbox.uz/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

> Integration workflow for FiscalBox APIs

## 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

## Recommended Integration Order

<Steps>
  <Step title="Authenticate where required">
    Use billing auth first when integrating billing-protected APIs:

    * [Billing Login](/api-reference/endpoint/billing/auth/login/login)

    Store and rotate tokens according to your backend security policy.
  </Step>

  <Step title="Implement Order Create as core transaction">
    Start from:

    * [Order Create](/api-reference/endpoint/order/create/order-create)

    Validate required fields, numeric units, and response persistence (`receipt_count`, `fiscal_sign`, `qr_url`).
  </Step>

  <Step title="Add payment provider-specific routes">
    Integrate only providers you use in production:

    * [Click](/api-reference/endpoint/payment/click/index)
    * [Payme](/api-reference/endpoint/payment/payme/index)
    * [Uzum](/api-reference/endpoint/payment/uzum/index)
    * [Anor](/api-reference/endpoint/payment/anor/index)

    Keep provider-specific `extra_info` rules isolated in adapter logic.
  </Step>

  <Step title="Implement reporting and daily closing logic">
    Add report endpoints into end-of-day operations:

    * [Z-Report Open](/api-reference/endpoint/report/zreport-open)
    * [Z-Report Close](/api-reference/endpoint/report/zreport-close)
    * Related print/info/sverka endpoints
  </Step>

  <Step title="Handle operational endpoints">
    Add operational capabilities where needed:

    * [Open Cash Drawer](/api-reference/endpoint/tool/cash-drawer/open)
    * [Info](/api-reference/endpoint/info/info)
    * [Banner](/api-reference/endpoint/banner/banner)
  </Step>

  <Step title="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
  </Step>
</Steps>

## 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

<AccordionGroup>
  <Accordion title="Scaled amount mismatch">
    Values sent in wrong unit scale lead to invalid totals or fiscal rejection. Centralize conversion rules in one service/module.
  </Accordion>

  <Accordion title="Provider-specific field errors">
    Payment providers can require extra fields depending on flow. Validate provider payloads before request dispatch.
  </Accordion>

  <Accordion title="Duplicate fiscal operations on retries">
    Network retries without idempotency checks may create duplicated operations. Add retry guards and request tracing.
  </Accordion>
</AccordionGroup>