RETAILOS

Developer documentation

BUILD ON THE SAME CONTROL PLANE.

Use tenant-aware APIs, scoped tokens and signed events without bypassing the permissions used by first-party applications.

01 · AUTHENTICATION

Start with a scoped session.

Authenticate with a phone number in E.164 format. Send the returned access token as a Bearer token. Refresh tokens rotate and should never be exposed to third-party scripts.

curl -X POST https://api.ocro.uz/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"phone":"+998…","password":"…"}'
02 · REQUESTS

Make every mutation traceable.

Use a unique idempotency key for sales and payment commands. Tenant identity comes from the verified token, never from a request body.

Production rule

Use HTTPS, short-lived access tokens and a server-side secret store.

03 · PERMISSIONS

Authorization is enforced twice.

The interface hides unavailable actions for clarity. The API independently validates role permissions and store or warehouse scope for security.

04 · CORE RESOURCES

Resource map.

Endpoints below are tenant-scoped unless marked public or platform. Every protected route also applies its declared permission.

Authentication & access

POST/auth/loginCreate an access and rotating refresh session
POST/auth/refreshRotate the refresh token family
GET/auth/sessionsList active account sessions
DELETE/auth/sessions/:idRevoke one device session
GET/permissionsRead the permission catalog
GET/rolesList tenant roles
POST/rolesCreate a custom permission role
POST/usersCreate a worker with roles and location scope

Catalog & files

GET/productsPaginate and filter products
POST/productsCreate a product and sellable variants
PATCH/products/:idUpdate product, variants and images
POST/products/:id/duplicateDuplicate a catalog item
POST/products/variants/:id/barcodesAssign a barcode
POST/products/labelsGenerate barcode and QR label jobs
POST/filesUpload a tenant-scoped file
GET/files/:id/contentDownload protected file content

Inventory & purchasing

GET/inventoryRead balances by location and variant
GET/inventory/movementsRead the stock movement ledger
POST/inventory/adjustmentsCreate an audited adjustment
POST/inventory/reservationsReserve available stock
POST/transfersCreate a warehouse transfer
POST/stock-countsStart a physical stock count
GET/purchasesList purchase orders
POST/purchases/:id/receiveReceive items into stock

Sales, shifts & finance

POST/salesComplete an idempotent sale
GET/sales/historyRead sales history
POST/sales/:id/returnsCreate a controlled return
GET/cash-shifts/currentRead the active cashier shift
POST/cash-shifts/openOpen a cashier shift
POST/cash-shifts/:id/closeClose and reconcile a shift
GET/financeRead accounts, entries and debts
POST/finance/debts/:id/payRecord a debt payment

Work, sites & channels

GET/work/projectsList projects with assigned tasks
POST/work/tasksCreate and assign a task
PATCH/work/tasks/:idMove or update a task
GET/bookingsRead scheduled bookings
POST/sitesCreate a website, taplink or bot project
POST/sites/:id/publishPublish a validated channel
POST/telegramVerify and connect a Telegram bot token
POST/instagram/messagesSend through a verified Meta connection

Automation, AI & physical operations

GET/reportsList report definitions
POST/reports/:id/runExecute a report export
POST/ai/assistantAsk the operational assistant
POST/ai/product-imageGenerate a product image through OpenRouter
POST/biometrics/enrollEnroll a face in connected CompreFace
POST/biometrics/recognizeRecognize against enrolled profiles
POST/hikvision/people-countRead the configured Hikvision counter
PATCH/warehouses/:id/layoutPersist the interactive warehouse model
05 · SIGNED WEBHOOKS

Verify before processing.

Compare the signature against the raw request body, reject stale timestamps and store provider event IDs to prevent replay.

06 · ERRORS

Keep the request ID.

Error responses include a request identifier. Record it with the failed command so operations teams can correlate the API response with structured logs.

Open protected OpenAPI JSON

The live OpenAPI document is intentionally protected and requires the operations documentation token. Customer integrations should use a dedicated server-side account and only the permissions they need.