[taler-docs] branch master updated: spec merchant API v16 with inventory categories

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 1935794c spec merchant API v16 with inventory categories
1935794c is described below

commit 1935794c1df3858f9312c2d14b81d26a5de7b188
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sat May 25 20:26:26 2024 +0200

    spec merchant API v16 with inventory categories
---
 core/api-donau.rst    |  32 +++++-----
 core/api-merchant.rst | 166 +++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 181 insertions(+), 17 deletions(-)

diff --git a/core/api-donau.rst b/core/api-donau.rst
index 800257de..d065c604 100644
--- 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
index 0e45cbad..06aaecac 100644
--- 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

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.