Physical POS
API Reference
Reports

Reports

Who calls these endpoints?External API (s2s)
Base path
/api/v1/physical-pos
Identity
Ed25519 request signature on every request — X-Key-Id, X-Date, X-Nonce, X-Signature, plus Digest on requests with a body. ±5 min clock window, single-use nonce. A Bearer token or a panel session is not accepted here.
Authorization
The key must carry the Physical POS product (PHYSICAL_POS) and the scope for the endpoints on this page: physical_pos:view · physical_pos:payments. Without the product the call gets 403 PRODUCT_NOT_ENABLED; without the scope 403 API_INSUFFICIENT_SCOPE. See Authentication and Scopes.
Cross-surface
These endpoints are the s2s surface — call them from your own server with a signed request. The same records have screens in the panel, but panel endpoints cannot be called with an API key, and these endpoints cannot be called with a panel session.
MethodPathScope
GET/api/v1/physical-pos/reports/sales-summaryphysical_pos:view or physical_pos:payments
GET/api/v1/physical-pos/reports/tax-summaryphysical_pos:view or physical_pos:payments

Reports are built from the payments in your key's environment; test and live records are never combined in one report. The environment field of the response shows the report's environment (TEST or LIVE).

Common rules

Query parameterTypeDescription
dateFromstringFirst business day, YYYY-MM-DD (inclusive). Default: 6 days before dateTo.
dateTostringLast business day, YYYY-MM-DD (inclusive). Default: today.
deviceIdstring (UUID)Only this device's operations.
storeIdstring (UUID)Only this store's operations (the device's assignment at operation time).
  • The business day follows Europe/Istanbul time. The range is at most 93 days. A date that does not exist (2026-02-30) gets 400 physical_pos.input.filter_invalid (details.field); a reversed or too long range gets the same code with details.reason: range_invalid.
  • Operation time: for a sale made directly on the device (origin: "DEVICE_DIRECT"), the sale time the device reported; for other operations, the time the operation was recorded. Each operation counts on its own day: a void made the next day reduces the next day's net.
  • Buckets:
BucketOperations
SaleSALE and PREAUTH_CLOSE
RefundREFUND and REFUND_UNMATCHED
VoidVOID
  • Only approved (APPROVED, PARTIALLY_APPROVED) operations enter the buckets, with the approved amount. PREAUTH_OPEN and PREAUTH_CANCEL are not in the report.
  • Operations with an uncertain outcome (UNKNOWN, MANUAL_REVIEW) do not enter the amounts; they are only counted in ambiguousCount.
  • Net = sale − refund − void, per currency. Different currencies are on separate rows.
  • All monetary totals, tax bases and taxes are canonical minor-unit strings. Net fields may be negative (for example "-4500"); counts and rateBp remain JSON integers. → Amounts

Sales summary

GET /api/v1/physical-pos/reports/sales-summary

Additional query parameter: groupBy: DAY (default), STORE, DEVICE or INSTRUMENT. Any other value gets 400 physical_pos.input.filter_invalid.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/reports/sales-summary?dateFrom=2026-01-01&dateTo=2026-01-07&groupBy=STORE"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"
{
  "environment": "LIVE",
  "dateFrom": "2026-01-01",
  "dateTo": "2026-01-07",
  "groupBy": "STORE",
  "rows": [
    {
      "groupKey": "00000000-0000-0000-0000-000000000101",
      "currency": "TRY",
      "saleCount": 120,
      "saleMinor": "540000",
      "refundCount": 3,
      "refundMinor": "12000",
      "voidCount": 1,
      "voidMinor": "4500",
      "netMinor": "523500",
      "ambiguousCount": 0
    }
  ]
}

The example shows the data field.

FieldTypeDescription
environmentstringThe report's environment.
dateFrom, dateTostringThe business day range applied.
groupBystringThe grouping applied.
rows[].groupKeystring | nullDAY: business day (YYYY-MM-DD); STORE: store ID, null for operations of devices not assigned to a store; DEVICE: device ID; INSTRUMENT: payment instrument: CARD, MEAL_CARD, QR, WALLET, CASH, BANK_TRANSFER, OTHER (payments started from the API are CARD; the others come from sales made directly on the device). The value set can grow.
rows[].currencystringCurrency.
rows[].saleCount, refundCount, voidCountintegerOperation counts in the sale, refund and void buckets.
rows[].saleMinor, refundMinor, voidMinorstringApproved amounts in those buckets, as canonical nonnegative minor-unit strings.
rows[].netMinorstringSale − refund − void.
rows[].ambiguousCountintegerCount of operations with an uncertain outcome.

Tax summary

GET /api/v1/physical-pos/reports/tax-summary

The tax breakdown is computed from the sale's items (tax groups). There is no additional query parameter.

FieldTypeDescription
environment, dateFrom, dateToAs in the sales summary.
rows[]arrayBreakdown per tax type, rate and currency.
rows[].taxTypestringKDV, KDV_TEVKIFAT, OTV_I, OTV_II, OTV_III, OTV_IV, OIV, BSMV or KONAKLAMA.
rows[].rateBpinteger | nullRate in basis points; null for a fixed per-unit tax.
rows[].currencystringCurrency.
rows[].saleBaseMinor, saleTaxMinorstringBase and tax of the sale bucket.
rows[].refundBaseMinor, refundTaxMinorstringRefund bucket.
rows[].voidBaseMinor, voidTaxMinorstringVoid bucket.
rows[].netBaseMinor, netTaxMinorstringSale − refund − void.
amountTotals[]arrayAmount counters per currency and scope.
amountTotals[].scopestringITEMIZED: sales with items and their refunds and voids. ITEMLESS: sales without items, pre-authorisation closes, refunds and voids of sales without items, and unmatched refunds.
amountTotals[].currency, saleCount, saleMinor, refundCount, refundMinor, voidCount, voidMinor, netMinorSame meaning as in the sales summary.
  • An item refund is deducted with its own tax breakdown.
  • An amount refund is deducted from the sale's collected tax in the ratio of the refund amount to the sale's approved amount.
  • The tax of a partially approved sale is the breakdown scaled by the approved / requested amount ratio.
  • A void deducts exactly the sale's collected tax.
  • Minor-unit rounding uses the largest remainder method: the rows add up to the rounded total tax.
  • The tax of sales without items cannot be computed; these sales appear only in the ITEMLESS counters of amountTotals.
  • For the same range and filters, ITEMIZED.netMinor + ITEMLESS.netMinor equals the total netMinor of the sales summary.

Errors

HTTPcodeWhen
400physical_pos.input.filter_invalidInvalid date, range, groupBy or ID; details.field, and details.reason where relevant.
400physical_pos.input.environment_invalidenvironment in the request.
400physical_pos.payment.card_data_rejectedA query parameter name looks like card data.
400VALIDATION_ERRORUndefined query parameter (e.g. limit).
500physical_pos.internal.integrity · physical_pos.gateway.response_invalidThe report could not be built; retry with backoff.