commit 1935794c1df3858f9312c2d14b81d26a5de7b188
parent 91083aa92e79a57993696778d453335d056499ed
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 25 May 2024 20:26:26 +0200
spec merchant API v16 with inventory categories
Diffstat:
2 files changed, 181 insertions(+), 17 deletions(-)
diff --git a/core/api-donau.rst b/core/api-donau.rst
@@ -18,6 +18,8 @@
@author Lukas Matyja
@author Johannes Casaburi
+.. _donau-api:
+
=====================
The Donau RESTful API
=====================
@@ -42,7 +44,7 @@ The chapters group the families of requests frequently encountered when using th
* :ref:`Status information<donau_status>`: get the public signing keys of the Donau, the donation unit key, the Donaus config or some entropy
* :ref:`Issue receipts<donau_issue>`: For use by charities: Issue receipts with blinded unique donor ids from a donor.
-* :ref:`Donation statement<donation_statement>`: Summarizes the donation receipts to the donation statement signature which is made over the total yearly donation amount,
+* :ref:`Donation statement<donation_statement>`: Summarizes the donation receipts to the donation statement signature which is made over the total yearly donation amount,
the year and the hash of taxid+salt. Provides an API to get the donation statement signature.
* :ref:`Charity administration and status information<donau_charity>`:
@@ -273,8 +275,8 @@ CSR Issue
:http:statuscode:`404 Not found`:
The donation unit key is not known to the donau.
:http:statuscode:`410 Gone`:
- The requested donation unit key is not yet or no longer valid. It either before the validity year, past the
- year or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code provided to
+ The requested donation unit key is not yet or no longer valid. It either before the validity year, past the
+ year or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code provided to
understand which of the cases this is and handle it accordingly.
**Details:**
@@ -327,16 +329,16 @@ CSR Issue
Batch Issue
~~~~~~~~~~~
This is the effectiv issue receipts request. Depending on the amount of the donation a
-certain amount of blinded unique donation identifiers, or for short `BUDI`s, are required.
-Every `BUDI` will be signed by the corresponding requested donation unit, which is associated with a value.
+certain amount of blinded unique donation identifiers, or for short BUDIs, are required.
+Every BUDI will be signed by the corresponding requested donation unit, which is associated with a value.
This API is used by the charity but the `BUDIKeyPairs` are coming from the donor.
-To make the request idempotent, the hash of the hole request is recorded under the
+To make the request idempotent, the hash of the hole request is recorded under the
corresponding charity_id by the Donau.
.. http:POST:: /batch-issue/$CHARITY_ID
- Send in a `IssueReceiptsRequest` and ask the Donau to sign all it's contained `BUDI`s.
+ Send in a `IssueReceiptsRequest` and ask the Donau to sign all it's contained BUDIs.
**Request:** `IssueReceiptsRequest`
@@ -347,14 +349,14 @@ corresponding charity_id by the Donau.
:http:statuscode:`403 Forbidden`:
The charity signature is invalid. This response comes with a standard `ErrorDetail` response.
:http:statuscode:`404 Not found`:
- At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`.
+ At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`.
This suggests a bug in the donor as it should have used current donation unit keys from :ref:`/keys<donau_status>`.
:http:statuscode:`409 Conflict`:
- The donation volume of the charity is not sufficient to issue donation receipts for all sent in blinded udis.
+ The donation volume of the charity is not sufficient to issue donation receipts for all sent in blinded udis.
The response is a `IssueError` object.
:http:statuscode:`410 Gone`:
- The requested donation unit key is not yet or no longer valid. It either before the validity year, past the
- year or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code
+ The requested donation unit key is not yet or no longer valid. It either before the validity year, past the
+ year or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code
provided to understand which of the cases this is and handle it accordingly.
**Details:**
@@ -476,7 +478,7 @@ Donation statement operations are requested by a donor.
.. http:POST:: /submit
Send in donation receipts for the current or one of the past fiscal years.
- The donor will reveive the signed total back, which is called the
+ The donor will reveive the signed total back, which is called the
donation statement.
**Request:** `SubmitDonationReceiptsRequest`
@@ -549,9 +551,9 @@ Donation statement operations are requested by a donor.
:http:statuscode:`403 Forbidden`:
One of the signatures is invalid. This response comes with a standard `ErrorDetail` response.
:http:statuscode:`404 Not found`:
- Either the donor or the year or the corresponding donation statement was not found.
+ Either the donor or the year or the corresponding donation statement was not found.
This response comes with a standard `ErrorDetail` response.
-
+
**Details:**
.. ts:def:: DonationStatement
@@ -561,7 +563,7 @@ Donation statement operations are requested by a donor.
// signature over h_donor_tax_id, total, donation_year
signature: EddsaSignature;
}
-
+
.. _donau_charity:
---------------------------------------------
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -123,7 +123,7 @@ such as the implemented version of the protocol and the currency used.
.. http:get:: /config
Return the protocol version and currency supported by this merchant backend.
- This specification corresponds to ``current`` protocol being version **v15**.
+ This specification corresponds to ``current`` protocol being version **v16**.
**Response:**
@@ -1705,6 +1705,150 @@ management.
Adding products to the inventory
--------------------------------
+.. http:get:: [/instances/$INSTANCE]/private/categories
+
+ This request returns the known product categories
+ and the number of products in each category.
+ Since API version **v16**.
+
+ **Response:**
+
+ :http:statuscode:`200 Ok`:
+ The body is a `CategoryList`.
+ :http:statuscode:`204 No content`:
+ There are no known categories.
+
+ **Details:**
+
+ .. ts:def:: CategoryList
+
+ interface CategoryList {
+
+ // Unique number for the category.
+ category_id: Integer;
+
+ // Name of the category.
+ name: string;
+
+ // Translations of the name into various
+ // languages.
+ name_i18n?: { [lang_tag: string]: string };
+
+ // Number of products in this category.
+ // A product can be in more than one category.
+ product_count: Integer;
+
+ }
+
+.. http:get:: [/instances/$INSTANCE]/private/categories/$CATEGORY_ID
+
+ This request returns the known products in the given
+ category.
+ Since API version **v16**.
+
+ **Response:**
+
+ :http:statuscode:`200 Ok`:
+ The body is a `CategoryProductList`.
+
+ **Details:**
+
+ .. ts:def:: CategoryProductList
+
+ interface CategoryProductList {
+
+ // Name of the category.
+ name: string;
+
+ // Translations of the name into various
+ // languages.
+ name_i18n?: { [lang_tag: string]: string };
+
+ // IDs of the products in this category.
+ product_ids: ProductSummary[];
+
+ }
+
+ .. ts:def:: ProductSummary
+
+ interface ProductSummary {
+
+ // Product ID to use.
+ product_id: string;
+
+ // Human-readable product description.
+ description: string;
+
+ // Map from IETF BCP 47 language tags to localized descriptions.
+ description_i18n?: { [lang_tag: string]: string };
+
+ }
+
+
+.. http:post:: [/instances/$INSTANCE]/private/categories
+
+ This is used to create a new category for the inventory.
+ Since API version **v16**.
+
+ **Request:**
+
+ The request is a `CategoryCreateRequest`.
+
+ **Response:**
+
+ :http:statuscode:`200 Ok`:
+ The response is a `CategoryCreatedResponse`.
+
+ **Details:**
+
+ .. ts:def:: CategoryCreateRequest
+
+ interface CategoryCreateRequest {
+
+ // Name of the category.
+ name: string;
+
+ // Translations of the name into various
+ // languages.
+ name_i18n?: { [lang_tag: string]: string };
+
+ }
+
+ .. ts:def:: CategoryCreatedResponse
+
+ interface CategoryCreatedResponse {
+
+ // Number of the newly created category.
+ category_id: Integer;
+ }
+
+
+.. http:patch:: [/instances/$INSTANCE]/private/categories/$CATEGORY_ID
+
+ This is used to edit a category.
+ Since API version **v16**.
+
+ **Request:**
+
+ The request is a `CategoryCreateRequest`.
+
+ **Response:**
+
+ :http:statuscode:`204 No Content`:
+ The category was modified successfully.
+
+.. http:delete:: [/instances/$INSTANCE]/private/categories/$CATEGORY_ID
+
+ This is used to delete a category.
+ Since API version **v16**.
+
+ **Response:**
+
+ :http:statuscode:`204 No Content`:
+ The category was deleted.
+ :http:statuscode:`404 Not Found`:
+ The category was possibly already deleted or is unknown.
+
.. http:post:: [/instances/$INSTANCE]/private/products
This is used to add a product to the inventory.
@@ -1720,6 +1864,7 @@ Adding products to the inventory
:http:statuscode:`409 Conflict`:
The backend already knows a product with this product ID, but with different details.
+ **Details:**
.. ts:def:: ProductAddDetail
@@ -1734,6 +1879,11 @@ Adding products to the inventory
// Map from IETF BCP 47 language tags to localized descriptions.
description_i18n?: { [lang_tag: string]: string };
+ // Categories into which the product belongs.
+ // Used in the POS-endpoint.
+ // Since API version **v16**.
+ categories?: Integer[];
+
// Unit in which the product is measured (liters, kilograms, packages, etc.).
unit: string;
@@ -1809,6 +1959,11 @@ Adding products to the inventory
// Unit in which the product is measured (liters, kilograms, packages, etc.).
unit: string;
+ // Categories into which the product belongs.
+ // Used in the POS-endpoint.
+ // Since API version **v16**.
+ categories?: Integer[];
+
// The price for one ``unit`` of the product. Zero is used
// to imply that this product is not sold separately, or
// that the price is not fixed, and must be supplied by the
@@ -1879,6 +2034,9 @@ Inspecting inventory
// ``product_serial_id`` of the product in the database.
product_serial: Integer;
+
+ // TODO: also return description/description_i18n here?
+ // TODO: what's the point in returning product_serial?
}
@@ -1907,6 +2065,10 @@ Inspecting inventory
// Unit in which the product is measured (liters, kilograms, packages, etc.).
unit: string;
+ // Categories into which the product belongs.
+ // Since API version **v16**.
+ categories: Integer[];
+
// The price for one ``unit`` of the product. Zero is used
// to imply that this product is not sold separately, or
// that the price is not fixed, and must be supplied by the
@@ -1919,7 +2081,7 @@ Inspecting inventory
// A list of taxes paid by the merchant for one unit of this product.
// Optional since **v15**.
- taxes: Tax[];
+ taxes?: Tax[];
// Number of units of the product in stock in sum in total,
// including all existing sales ever. Given in product-specific
