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, plusDigeston 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 gets403 PRODUCT_NOT_ENABLED; without the scope403 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.
| Method | Path | Scope |
|---|---|---|
GET | /api/v1/physical-pos/reports/sales-summary | physical_pos:view or physical_pos:payments |
GET | /api/v1/physical-pos/reports/tax-summary | physical_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 parameter | Type | Description |
|---|---|---|
dateFrom | string | First business day, YYYY-MM-DD (inclusive). Default: 6 days before dateTo. |
dateTo | string | Last business day, YYYY-MM-DD (inclusive). Default: today. |
deviceId | string (UUID) | Only this device's operations. |
storeId | string (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) gets400 physical_pos.input.filter_invalid(details.field); a reversed or too long range gets the same code withdetails.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:
| Bucket | Operations |
|---|---|
| Sale | SALE and PREAUTH_CLOSE |
| Refund | REFUND and REFUND_UNMATCHED |
| Void | VOID |
- Only approved (
APPROVED,PARTIALLY_APPROVED) operations enter the buckets, with the approved amount.PREAUTH_OPENandPREAUTH_CANCELare not in the report. - Operations with an uncertain outcome (
UNKNOWN,MANUAL_REVIEW) do not enter the amounts; they are only counted inambiguousCount. - 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 andrateBpremain 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.
| Field | Type | Description |
|---|---|---|
environment | string | The report's environment. |
dateFrom, dateTo | string | The business day range applied. |
groupBy | string | The grouping applied. |
rows[].groupKey | string | null | DAY: 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[].currency | string | Currency. |
rows[].saleCount, refundCount, voidCount | integer | Operation counts in the sale, refund and void buckets. |
rows[].saleMinor, refundMinor, voidMinor | string | Approved amounts in those buckets, as canonical nonnegative minor-unit strings. |
rows[].netMinor | string | Sale − refund − void. |
rows[].ambiguousCount | integer | Count 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.
| Field | Type | Description |
|---|---|---|
environment, dateFrom, dateTo | As in the sales summary. | |
rows[] | array | Breakdown per tax type, rate and currency. |
rows[].taxType | string | KDV, KDV_TEVKIFAT, OTV_I, OTV_II, OTV_III, OTV_IV, OIV, BSMV or KONAKLAMA. |
rows[].rateBp | integer | null | Rate in basis points; null for a fixed per-unit tax. |
rows[].currency | string | Currency. |
rows[].saleBaseMinor, saleTaxMinor | string | Base and tax of the sale bucket. |
rows[].refundBaseMinor, refundTaxMinor | string | Refund bucket. |
rows[].voidBaseMinor, voidTaxMinor | string | Void bucket. |
rows[].netBaseMinor, netTaxMinor | string | Sale − refund − void. |
amountTotals[] | array | Amount counters per currency and scope. |
amountTotals[].scope | string | ITEMIZED: 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, netMinor | Same 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
ITEMLESScounters ofamountTotals. - For the same range and filters,
ITEMIZED.netMinor + ITEMLESS.netMinorequals the totalnetMinorof the sales summary.
Errors
| HTTP | code | When |
|---|---|---|
400 | physical_pos.input.filter_invalid | Invalid date, range, groupBy or ID; details.field, and details.reason where relevant. |
400 | physical_pos.input.environment_invalid | environment in the request. |
400 | physical_pos.payment.card_data_rejected | A query parameter name looks like card data. |
400 | VALIDATION_ERROR | Undefined query parameter (e.g. limit). |
500 | physical_pos.internal.integrity · physical_pos.gateway.response_invalid | The report could not be built; retry with backoff. |