commit 6f76d961cb15f206153f415edf6cb0eb808e3f1d
parent 56b11e2ee4a5cad960701b854e86de70e6291600
Author: Christian Grothoff <christian@grothoff.org>
Date: Sun, 28 Dec 2025 14:29:52 +0100
update spec for vPRODUCTS/vPOTS
Diffstat:
| M | core/api-merchant.rst | | | 132 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------- |
1 file changed, 115 insertions(+), 17 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -2981,8 +2981,19 @@ Adding products to the inventory
:http:statuscode:`204 No content`:
The backend has successfully expanded the inventory.
+ :http:statuscode:`404 Not found`:
+ The instance, category, product group or money pot specified are
+ unknown. Possible error ``code`` values are thus:
+ ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN`` (instance unknown),
+ ``TALER_EC_MERCHANT_GENERIC_PRODUCT_GROUP_UNKNOWN`` (product group unknown)
+ ``TALER_EC_MERCHANT_GENERIC_MONEY_POT_UNKNOWN`` (money pot unknown),
+ ``TALER_EC_MERCHANT_GENERIC_CATEGORY_UNKNOWN``
+ (category unknown, specific category is given in the details).
+
:http:statuscode:`409 Conflict`:
- The backend already knows a product with this product ID, but with different details.
+ The backend already knows a product with this product ID,
+ but with different details. Returned with a ``code`` of
+ ``TALER_EC_MERCHANT_PRIVATE_POST_PRODUCTS_CONFLICT_PRODUCT_EXISTS``.
**Details:**
@@ -3064,6 +3075,17 @@ Adding products to the inventory
// Minimum age buyer must have (in years). Default is 0.
minimum_age?: Integer;
+ // Product group the product belongs to. 0 and missing both
+ // means default.
+ // Since **vGROUPS**.
+ product_group_id?: Integer;
+
+ // Money pot revenue on the product should be accounted in.
+ // 0 and missing both mean no money pot (revenue accounted
+ // in money pot of the overall order or not at all).
+ // Since **vPOTS**.
+ money_pot_id?: Integer;
+
}
Clients SHOULD migrate to the new ``unit_*`` fields and treat ``total_stock`` and ``price``
@@ -3119,9 +3141,17 @@ Adding products to the inventory
:http:statuscode:`204 No content`:
The backend has successfully expanded the inventory.
:http:statuscode:`404 Not found`:
- The product (ID) is unknown to the backend.
+ The instance, product, category, product group or money pot specified are
+ unknown. Possible error ``code`` values are thus:
+ ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN`` (instance unknown),
+ ``TALER_EC_MERCHANT_GENERIC_PRODUCT_UNKNOWN`` (product unknown),
+ ``TALER_EC_MERCHANT_GENERIC_PRODUCT_GROUP_UNKNOWN`` (product group unknown)
+ ``TALER_EC_MERCHANT_GENERIC_MONEY_POT_UNKNOWN`` (money pot unknown),
+ ``TALER_EC_MERCHANT_GENERIC_CATEGORY_UNKNOWN``
+ (category unknown, specific category is given in the details).
:http:statuscode:`409 Conflict`:
- The provided information is inconsistent with the current state of the inventory.
+ The provided information is inconsistent with the current state of
+ the inventory.
.. ts:def:: ProductPatchDetail
@@ -3170,6 +3200,11 @@ Adding products to the inventory
// Legacy price field. Deprecated; when present it must match the first element of ``unit_price``.
price?: Amount;
+ // True if the price(s) given are a net prices, false if they are
+ // gross prices.
+ // Since protocol **vTAXES**.
+ price_is_net?: boolean;
+
// An optional base64-encoded product image.
image?: ImageDataUrl;
@@ -3195,6 +3230,17 @@ Adding products to the inventory
// Minimum age buyer must have (in years). Default is 0.
minimum_age?: Integer;
+ // Product group the product belongs to. 0 and missing both
+ // means default.
+ // Since **vGROUPS**.
+ product_group_id?: Integer;
+
+ // Money pot revenue on the product should be accounted in.
+ // 0 and missing both mean no money pot (revenue accounted
+ // in money pot of the overall order or not at all).
+ // Since **vPOTS**.
+ money_pot_id?: Integer;
+
}
The same compatibility rules for the ``unit_*`` fields and their deprecated counterparts apply
@@ -3312,6 +3358,11 @@ Inspecting inventory
// Optional since **v15**.
taxes?: Tax[];
+ // True if the price(s) given are a net prices, false if they are
+ // gross prices.
+ // Since protocol **vTAXES**.
+ price_is_net: boolean;
+
// Legacy integer stock counter kept for compatibility. ``-1`` indicates unlimited stock.
total_stock: Integer;
@@ -3335,6 +3386,16 @@ Inspecting inventory
// Minimum age buyer must have (in years).
minimum_age?: Integer;
+ // Product group the product belongs to. Missing means default.
+ // Since **vGROUPS**.
+ product_group_id?: Integer;
+
+ // Money pot revenue on the product should be accounted in.
+ // Missing means no money pot (revenue accounted
+ // in money pot of the overall order or not at all).
+ // Since **vPOTS**.
+ money_pot_id?: Integer;
+
}
.. http:get:: [/instances/$INSTANCE]/private/pos
@@ -5620,7 +5681,7 @@ Inspecting webhook
.. http:get:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID
- This is used to obtain detailed information about apecific webhook.
+ This is used to obtain detailed information about a specific webhook.
**Required permission:** ``webhooks-read``
@@ -5684,12 +5745,48 @@ helper programs which must be configured for each merchant backend.
Since protocol **vREPORTS**.
-Adding reports
-^^^^^^^^^^^^^^
+Generating reports
+^^^^^^^^^^^^^^^^^^
+
+.. http:post:: /reports/$REPORT_ID
+
+ This is used to request the generation of a periodic report.
+ It is used internally by the ``taler-merchant-report-generator``.
+ The endpoint itself is unauthenticated, but the ``report-token``
+ serves to authorize the request.
+
+ **Request:**
+
+ The request must be a `ReportGenerationRequest`.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The backend has successfully added a new report.
+ Details returned (including the content type) depend
+ fully on the type of report that was requested.
+
+ :http:statuscode:`404 Not found`:
+ The report ID *or* the report token are unknown.
+
+ **Details:**
+
+ .. ts:def:: ReportGenerationRequest
+
+ interface ReportGenerationRequest {
+
+ // Report token authorizing the report generation.
+ report_token: ShortHashCode;
+
+ }
+
+
+Scheduling periodic reports
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. http:post:: [/instances/$INSTANCES]/private/reports
- This is used to create a report.
+ This is used to schedule the generation of periodic reports.
**Required permission:** ``reports-write``
@@ -5747,12 +5844,12 @@ Adding reports
}
-Editing reports
-^^^^^^^^^^^^^^^
+Editing scheduled reports
+^^^^^^^^^^^^^^^^^^^^^^^^^
.. http:patch:: [/instances/$INSTANCES]/private/reports/$REPORT_ID
- This is used to update a report.
+ This is used to update a scheduled report.
**Required permission:** ``reports-write``
@@ -5768,12 +5865,12 @@ Editing reports
The report or instance is unknown to the backend.
-Inspecting reports
-^^^^^^^^^^^^^^^^^^
+Inspecting reporting schedules
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. http:get:: [/instances/$INSTANCES]/private/reports
- This is used to return all the reports
+ This is used to return all the scheduled reports
that are present in our backend.
**Required permission:** ``reports-read``
@@ -5826,7 +5923,8 @@ Inspecting reports
.. http:get:: [/instances/$INSTANCES]/private/reports/$REPORT_SERIAL
- This is used to obtain detailed information about apecific report.
+ This is used to obtain detailed information about a specific
+ scheduled report.
**Required permission:** ``reports-read``
@@ -5882,12 +5980,12 @@ Inspecting reports
}
-Removing reports
-^^^^^^^^^^^^^^^^
+Removing scheduled reports
+^^^^^^^^^^^^^^^^^^^^^^^^^^
.. http:delete:: [/instances/$INSTANCES]/private/reports/$REPORT_SERIAL
- This is used to delete information about a report.
+ This is used to delete report generation from the schedule.
**Required permission:** ``reports-write``
