commit 8e1e16d1dae3543d72c748b80c636232aecda05d
parent 956d9f4114952cdc5708737fcf50046ea2c02e77
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 1 Jan 2026 17:32:54 +0100
add 501 explicitly, fix typos
Diffstat:
2 files changed, 122 insertions(+), 2 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -6117,6 +6117,10 @@ and freeze or unfreeze accounts suspected of money laundering.
The designated AML account is not known.
:http:statuscode:`409 Conflict`:
The designated AML account is not enabled.
+ :http:statuscode:`501 Not implemented`:
+ The requested functionality is not implemented.
+ Usually returned if the PDF generator is not available
+ at this backend and the requested format was application/pdf.
.. ts:def:: KycAttributes
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -47,6 +47,10 @@ Android PoS app is currently targeting **v20**.
* ``vREPORTS``: adds features for periodic report generation
* ``vTAXES``: adds features to manage taxes
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
-----------------------
Base URLs and Instances
-----------------------
@@ -2038,7 +2042,7 @@ Getting statistics
This request will return be used to statistics where the
values are amounts. All available values for the given
SLUG will be returned.
- Since protocol **vSTATISTICS**.
+ Since protocol **v28**.
**Required permission:** ``statistics-read``
@@ -2116,7 +2120,7 @@ Getting statistics
This request will return be used to statistics where the
values are counters. All available values for the given
SLUG will be returned.
- Since protocol **vSTATISTICS**.
+ Since protocol **v28**.
**Required permission:** ``statistics-read``
@@ -2189,6 +2193,118 @@ Getting statistics
}
+
+.. http:get:: /management/instances/$INSTANCE/statistics-report/$NAME
+.. http:get:: [/instances/$INSTANCE]/private/statistics-report/$NAME
+
+ This request will return be used to generate a specific
+ report based on $NAME. The backend **MAY** support generating
+ the report in various formats. Supported values for ``$NAME`` include:
+
+ * "transactions" (total revenue, total refunds, fees
+ as well as number of transactions), since **vREPORTS**
+ * "money-pots" (changes to totals in money pots), since **vPOTS**
+ * "taxes" (amount of taxes withheld by tax class), since **vTAXES**,
+ * "sales-funnel" (number and volume of orders
+ created, claimed, paid, refunded and settled), since **vXXX**,
+
+ The overall endpoint family exists since protocol **vREPORTS**.
+
+ **Required permission:** ``statistics-read``
+
+ **Request:**
+
+ *Accept*:
+ The client may specify the desired MIME-type for the result.
+ Supported are the usual "application/json", but also
+ "application/pdf".
+
+ :query granularity: *Optional*. Determines the bucket granularity
+ to return. Accepted are "hour", "day", "week",
+ "month", "quarter" and "year". Defaults to "month".
+ :query count: *Optional*. Number of buckets to return. Defaults depends
+ on the granularity.
+
+ **Response:**
+
+ :http:statuscode:`200 Ok`:
+ If JSON is requested, the body will be
+ a `MerchantStatisticsReportResponse`, otherwise a PDF.
+ :http:statuscode:`401 Unauthorized`:
+ The request is unauthorized.
+ :http:statuscode:`404 Not found`:
+ The instance is unknown to the backend.
+ :http:statuscode:`410 Gone`:
+ The requested statistical data is unavailable because
+ it is not kept at the requested granularity for this long.
+ :http:statuscode:`501 Not implemented`:
+ The requested functionality is not implemented.
+ Usually returned if the PDF generator is not available
+ at this backend and the requested format was application/pdf.
+
+ **Details:**
+
+ .. ts:def:: MerchantStatisticsReportResponse
+
+ interface MerchantStatisticsReportResponse {
+
+ // Name of the business for which the report is generated.
+ business_name: String;
+
+ // Starting date for the report.
+ start_date: Timestamp;
+
+ // End date for the report.
+ end_date: Timestamp;
+
+ // Period of time covered by each bucket (aka granularity).
+ bucket_period: RelativeTime;
+
+ // Charts to include in the report.
+ charts: MerchantReportChart[];
+
+ }
+
+ .. ts:def:: MerchantReportChart
+
+ interface MerchantReportChart {
+
+ // Name of the chart.
+ chart_name: String;
+
+ // Label to use for the y-axis of the chart.
+ // (x-axis is always time).
+ y_label: String;
+
+ // Statistical values for the respective time windows,
+ // one entry per ``bucket_period`` in between ``start_date``
+ // and ``end_date``.
+ data_groups: BucketDataGroup[];
+
+ // Human-readable labels for the ``values`` in each of the
+ // ``data_groups``. Length of the array must match the
+ // length of the ``values`` arrays.
+ labels: string[];
+
+ // Should the ``values`` in each of the ``data_groups``
+ // be rendered cumulatively or using a grouped representation?
+ cumulative: boolean;
+
+ }
+
+ .. ts:def:: BucketDataGroup
+
+ interface BucketDataGroup {
+
+ // Starting data for this group
+ start_date: Timestamp;
+
+ // Values in the data group.
+ values: Float[];
+
+ }
+
+
Deleting instances
^^^^^^^^^^^^^^^^^^
