{ "openapi": "3.0.0", "info": { "title": "Storekeeper API", "description": "Interim Storekeeper API \u2014 proxies to Storekeeper REST and UPX/fulljson APIs.\n\n**Auth flow**:\n1. POST `/api/auth/login` with your `account`, `email`, `password`\n2. Use the returned `token` as `Authorization: Bearer ` for all other endpoints\n3. Token expires after 30 minutes \u2014 call `/api/auth/refresh` (or `/login`) again\n", "version": "1.0.0" }, "paths": { "/api/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Authenticate against Storekeeper and receive a bearer token", "operationId": "post_app_auth_login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "account", "email", "password" ], "properties": { "account": { "type": "string", "example": "demo" }, "email": { "type": "string", "example": "user@example.com" }, "password": { "type": "string", "example": "\u2022\u2022\u2022\u2022\u2022\u2022" } }, "type": "object" } } } }, "responses": { "200": { "description": "Bearer token issued (30 min TTL)", "content": { "application/json": { "schema": { "properties": { "token": { "type": "string" }, "expires_at": { "description": "Unix timestamp", "type": "integer" }, "expires_in": { "description": "Seconds", "type": "integer" } }, "type": "object" } } } }, "400": { "description": "Missing fields" }, "401": { "description": "Authentication failed" } }, "security": [] } }, "/api/auth/refresh": { "post": { "tags": [ "Auth" ], "summary": "Refresh: re-authenticate with the same credentials to get a fresh token", "operationId": "post_app_auth_refresh", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "account", "email", "password" ], "properties": { "account": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "New token issued" } }, "security": [] } }, "/api/discount-orders": { "get": { "tags": [ "Discount Orders" ], "summary": "List orders with a non-zero discount for a date range", "description": "Returns every order where `discount_value_wt > 0` (or `!= 0` if `include_negative` is set)\nwithin the given date range. Paginates the upstream `ShopModule.listOrders` call in batches\nof 100 and flattens the result into a tidy list. Each row carries a ready-to-click\n`backoffice_url` pointing at the order in the user's Storekeeper Backoffice.\n\nFilters:\n- `shop_id` narrows to a single sales channel. Omit for all shops.\n- `only_full` = 100%-discount orders only (adds `value_wt__= 0` to the upstream filter).\n- `include_negative` flips the base filter from `__> 0` to `__!= 0`, which also catches\n negative discounts (refund-like corrections).", "operationId": "get_app_discountorder_list", "parameters": [ { "name": "from", "in": "query", "description": "Start date (YYYY-MM-DD), inclusive", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End date (YYYY-MM-DD), inclusive. Defaults to `from`.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "shop_id", "in": "query", "description": "Filter to a single sales channel (shop). Omit for all.", "required": false, "schema": { "type": "integer" } }, { "name": "only_full", "in": "query", "description": "Only return orders where the full amount is discounted (value_wt = 0).", "required": false, "schema": { "type": "boolean" } }, { "name": "include_negative", "in": "query", "description": "Also include negative-discount rows (refunds/corrections). Default: only positive discounts.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Array of discounted orders", "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer" }, "total": { "type": "integer" }, "from": { "type": "string" }, "to": { "type": "string" }, "shop_id": { "type": "integer", "nullable": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "order_number": { "type": "string" }, "date_purchased": { "type": "string" }, "status": { "type": "string" }, "shop_id": { "type": "integer" }, "currency": { "type": "string" }, "value_wt": { "type": "number" }, "value_ex_wt": { "type": "number" }, "discount_value_wt": { "type": "number" }, "discount_value_ex_wt": { "type": "number" }, "customer_name": { "type": "string" }, "customer_email": { "type": "string" }, "backoffice_url": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "502": { "description": "Upstream Storekeeper error" } } } }, "/api/financial-report": { "get": { "tags": [ "Financial Report" ], "summary": "Structured financial report for a date range", "description": "Returns a structured report for the given date range. Response sections:\n\n- **revenue** \u2014 `total_sales`, `total_returns`, `total_differences`, `total_turnover` (sales minus returns and differences), `total_cost_of_goods_sold`, `margin` (value and percentage), and `non_revenue` (gift cards, tips, payments on invoice, prepayments).\n- **direct_paid** \u2014 per-rate breakdown and grand total for what was paid directly, a list of payment methods used with friendly names and amounts, plus a `balance_check` that verifies the payments sum matches the total.\n- **not_paid_now** \u2014 per-rate breakdown and total for invoiced amounts that are still unpaid.\n- **turnover_by_group** \u2014 rows per product group with a per-shop split, per-shop totals, and an overall total. When `location_id` is passed, the result is filtered to the shop(s) that belong to that location.", "operationId": "get_app_financialreport_report", "parameters": [ { "name": "from", "in": "query", "description": "Start date (YYYY-MM-DD), inclusive", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End date (YYYY-MM-DD), inclusive. Defaults to `from`.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "location_id", "in": "query", "description": "Limit to a single location. Omit for all.", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Structured financial report" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "502": { "description": "Upstream Storekeeper error" } } } }, "/api/locations": { "get": { "tags": [ "Locations" ], "summary": "List all locations", "operationId": "get_app_location_list", "responses": { "200": { "description": "Locations array or object" }, "401": { "description": "Unauthorized" } } } }, "/api/locations/{id}": { "get": { "tags": [ "Locations" ], "summary": "Get a single location by id", "operationId": "get_app_location_get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Single location" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/api/payment-methods": { "get": { "tags": [ "Payment Methods" ], "summary": "List configured payment methods (providers)", "description": "Returns the published, customer-facing payment providers configured on the Storekeeper account. Internal Storekeeper providers (returns, payment balance, imported, dummy) are excluded.", "operationId": "get_app_paymentmethod_list", "responses": { "200": { "description": "Array of payment providers, default first, then alphabetical", "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "alias": { "type": "string" }, "type_alias": { "type": "string" }, "is_default": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Upstream Storekeeper error" } } } } }, "components": { "securitySchemes": { "Bearer": { "type": "http", "bearerFormat": "opaque", "scheme": "bearer" } } }, "security": [ { "Bearer": [] } ], "tags": [ { "name": "Auth" }, { "name": "Discount Orders" }, { "name": "Financial Report" }, { "name": "Locations" }, { "name": "Payment Methods" } ] }