taler-docs

commit 5b7634735efbd3e352cf5a123c93917c85c7008f
parent c3777818d839ad9f92c6fbea670aa63d32548d10
Author: Bohdan Potuzhnyi <bohdan.potuzhnyi@gmail.com>
Date:   Tue, 23 Sep 2025 12:13:18 +0200

0010438

Diffstat:
M
core/api-donau.rst
 | 
35
++++++++++++++++++++++++++++-------

1 file changed, 28 insertions(+), 7 deletions(-)
diff --git a/core/api-donau.rst b/core/api-donau.rst
@@ -649,9 +649,12 @@ The GET status requests require an authorized bearer token as well.
       current_year: Integer;
     }
 
-.. http:POST:: /charity
+.. http:POST:: /charities
 
-  Add a charity. Only allowed if the request comes with the administrator bearer token.
+  Register a new charity with the Donau. Only allowed if the request comes with the
+  administrator bearer token. The request body defines the charity's signing key,
+  contact information, and the initial accounting values for the current business
+  year. On success the Donau assigns a numeric identifier to the charity record.
 
   **Request:** `CharityRequest`
 
@@ -662,24 +665,42 @@ The GET status requests require an authorized bearer token as well.
   :http:statuscode:`201 Created`:
     The request was successful, and the response is a `CharityResponse`.
 
+  :http:statuscode:`204 No Content`:
+    The request was syntactically valid but rejected (for example, because the
+    charity already exists). A standard `ErrorDetail` response explains the reason.
+
   :http:statuscode:`403 Forbidden`:
-    The request did not contain an accepted administrator bearer token in it's header.
+    The request did not contain an accepted administrator bearer token in its header.
+
+  :http:statuscode:`404 Not found`:
+    The referenced resource needed to create the charity was not found. This response
+    comes with a standard `ErrorDetail` response.
+
+  :http:statuscode:`413 Content too large`:
+    The request exceeded internal limits. This response comes with a standard
+    `ErrorDetail` response.
 
   .. ts:def:: CharityRequest
 
     interface CharityRequest{
+      // Long-term EdDSA public key that identifies the charity.
       charity_pub: EddsaPublicKey;
-      name: string;
-      url: string;
+      // Canonical URL that should be presented to donors.
+      charity_url: string;
+      // Human-readable display name of the charity.
+      charity_name: string;
+      // Allowed donation volume for the charity per calendar year.
       max_per_year: Amount;
+      // Donation volume that has already been received for `current_year`.
       receipts_to_date: Amount;
+      // Calendar year the accounting information refers to.
       current_year: Integer;
     }
 
   .. ts:def:: CharityResponse
 
     interface CharityResponse{
-      id: Integer;
+      charity_id: Integer;
     }
 
 
@@ -695,7 +716,7 @@ The GET status requests require an authorized bearer token as well.
     The request was successful.
 
   :http:statuscode:`403 Forbidden`:
-    The request did not contain an accepted administrator bearer token in it's header.
+    The request did not contain an accepted administrator bearer token in its header.
 
 
 .. http:DELETE:: /charities/{id}