taler-docs

commit 1fc69399985813871b3048c285cc2853e44bbd3b
parent eca37b90da5622d8f255ce158011d379684c4902
Author: Christian Grothoff <christian@grothoff.org>
Date:   Tue,  2 Jun 2026 21:23:21 +0200

document GET /history endpoint

Diffstat:
M
core/api-donau.rst
 | 
2
++
A
core/donau/get-history.rst
 | 
51
+++++++++++++++++++++++++++++++++++++++++++++++++++

2 files changed, 53 insertions(+), 0 deletions(-)
diff --git a/core/api-donau.rst b/core/api-donau.rst
@@ -94,6 +94,8 @@ long-term offline signing key of the Donau, which clients should cache.
 
 .. include:: donau/get-config.rst
 
+.. include:: donau/get-history.rst
+
 
 .. _donau_issue:
 
diff --git a/core/donau/get-history.rst b/core/donau/get-history.rst
@@ -0,0 +1,51 @@
+.. http:get:: /history
+
+  Return the finalized year-end donation totals for all charities.
+  The history table stores one record per charity, written when the
+  Donau closes out a donation year for that charity (i.e., when
+  ``receipts_to_date`` is rolled over to a new year). Each record
+  gives the ``final_amount`` accumulated during ``donation_year``
+  before the rollover occurred.
+
+  Only allowed if the request comes with the administrator bearer token.
+
+  **Request:**
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The request was successful, and the response is a `HistoryResponse`.
+  :http:statuscode:`204 No Content`:
+    No year-end history records exist yet (no year has been closed out).
+  :http:statuscode:`403 Forbidden`:
+    The request did not contain an accepted administrator bearer token in its header.
+    Returned with error code ``TALER_EC_GENERIC_TOKEN_PERMISSION_INSUFFICIENT``.
+  :http:statuscode:`500 Internal Server Error`:
+    The Donau encountered an internal database error.
+    Returned with error code ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
+
+  **Details:**
+
+  .. ts:def:: HistoryResponse
+
+    interface HistoryResponse {
+      // Array of year-end totals, one entry per charity that has
+      // had at least one year closed out.
+      history: CharityYearSummary[];
+    }
+
+  .. ts:def:: CharityYearSummary
+
+    interface CharityYearSummary {
+
+      // Unique ID of the charity within the Donau.
+      charity_id: Integer;
+
+      // Total amount of donation receipts issued for this charity
+      // during ``donation_year``, recorded at year-end rollover.
+      final_amount: Amount;
+
+      // The calendar year to which ``final_amount`` applies.
+      donation_year: Integer;
+
+    }