get-history.rst (1723B)
1 .. http:get:: /history 2 3 Return the finalized year-end donation totals for all charities. 4 The history table stores one record per charity, written when the 5 Donau closes out a donation year for that charity (i.e., when 6 ``receipts_to_date`` is rolled over to a new year). Each record 7 gives the ``final_amount`` accumulated during ``donation_year`` 8 before the rollover occurred. 9 10 Only allowed if the request comes with the administrator bearer token. 11 12 **Request:** 13 14 **Response:** 15 16 :http:statuscode:`200 OK`: 17 The request was successful, and the response is a `HistoryResponse`. 18 :http:statuscode:`204 No Content`: 19 No year-end history records exist yet (no year has been closed out). 20 :http:statuscode:`403 Forbidden`: 21 The request did not contain an accepted administrator bearer token in its header. 22 Returned with error code ``TALER_EC_GENERIC_TOKEN_PERMISSION_INSUFFICIENT``. 23 :http:statuscode:`500 Internal Server Error`: 24 The Donau encountered an internal database error. 25 Returned with error code ``TALER_EC_GENERIC_DB_FETCH_FAILED``. 26 27 **Details:** 28 29 .. ts:def:: HistoryResponse 30 31 interface HistoryResponse { 32 // Array of year-end totals, one entry per charity that has 33 // had at least one year closed out. 34 history: CharityYearSummary[]; 35 } 36 37 .. ts:def:: CharityYearSummary 38 39 interface CharityYearSummary { 40 41 // Unique ID of the charity within the Donau. 42 charity_id: Integer; 43 44 // Total amount of donation receipts issued for this charity 45 // during ``donation_year``, recorded at year-end rollover. 46 final_amount: Amount; 47 48 // The calendar year to which ``final_amount`` applies. 49 donation_year: Integer; 50 51 }