api-donau.rst (5347B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2014-2023 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Christian Grothoff 17 @author Pius Loosli 18 @author Lukas Matyja 19 @author Johannes Casaburi 20 21 .. _donau-api: 22 23 ================= 24 Donau RESTful API 25 ================= 26 27 The API specified here follows the :ref:`general conventions <http-common>` 28 for all details not specified in the individual requests. 29 The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_ 30 defines all specific terms used in this section. 31 32 .. _donau-overview: 33 34 35 36 ------------ 37 API Overview 38 ------------ 39 40 This is intended to provide a quick overview of the whole REST API. For a more detailed view of the protocol, see the protocol specification. 41 42 The chapters group the families of requests frequently encountered when using the Donau API: 43 44 * :ref:`Status information<donau_status>`: get the public signing keys of the Donau, the donation unit key, the Donaus config or some entropy 45 * :ref:`Issue receipts<donau_issue>`: For use by charities: Issue receipts with blinded unique donor ids from a donor. 46 * :ref:`Donation statement<donation_statement>`: Summarizes the donation receipts to the donation statement signature which is made over the total yearly donation amount, 47 the year and the hash of taxid+salt. Provides an API to get the donation statement signature. 48 * :ref:`Charity administration and status information<donau_charity>`: 49 50 * For use by administrators to add/modify a charity 51 * For use by charities to get their remaining donation volume 52 53 54 --------------- 55 Version History 56 --------------- 57 58 The current protocol version is **v0**. 59 60 * The merchant is currently targeting protocol version **v0**. 61 * The donau validator app is currently targeting protocol version **v0**. 62 63 **Version history:** 64 65 * ``v0``: This is the first implementation. 66 67 **Upcoming versions:** 68 69 * none anticipated 70 71 **Ideas for future version:** 72 73 * ``vXXX``: marker for features not yet targeted for release 74 75 76 .. include:: tos.rst 77 78 .. _donau_status: 79 80 ---------------------------------------- 81 Donau public keys and status information 82 ---------------------------------------- 83 84 This API is used by donors and charities to obtain global information about 85 the Donau, such as online signing keys and available donation units. This is 86 typically the first call any Donau client makes, as it returns information 87 required to process all of the other interactions with the Donau. The 88 returned information is secured by signature(s) from the Donau, especially the 89 long-term offline signing key of the Donau, which clients should cache. 90 91 .. include:: donau/get-keys.rst 92 93 .. include:: donau/get-seed.rst 94 95 .. include:: donau/get-config.rst 96 97 .. include:: donau/get-history.rst 98 99 100 .. _donau_issue: 101 102 -------------- 103 Issue receipts 104 -------------- 105 106 Inspired by the Taler exchange :ref:`Withdrawal<exchange-withdrawal>`. 107 108 This API is used to obtain valid, attested donation receipts from the Donau. 109 Use the :ref:`charity GET route<donau_charity_get>` to see the remaining donation volume for the current year. 110 111 CSR Issue 112 ~~~~~~~~~~~ 113 114 .. include:: donau/post-csr-issue.rst 115 116 117 Batch Issue 118 ~~~~~~~~~~~ 119 This is the effectiv issue receipts request. Depending on the amount of the donation a 120 certain amount of blinded unique donation identifiers, or for short BUDIs, are required. 121 Every BUDI will be signed by the corresponding requested donation unit, which is associated with a value. 122 This API is used by the charity but the array of `BlindedDonationReceiptKeyPair` are coming from the donor. 123 124 To make the request idempotent, the hash of the hole request is recorded under the 125 corresponding charity_id by the Donau. 126 127 .. include:: donau/post-batch-issue-CHARITY_ID.rst 128 129 .. _donation_statement: 130 131 ------------------ 132 Donation statement 133 ------------------ 134 135 Inspired by the Taler exchange :ref:`Deposit<deposit-par>`. 136 137 Donation statement operations are requested by a donor. 138 139 .. include:: donau/post-batch-submit.rst 140 141 .. include:: donau/get-donation-statement-YEAR-HASH_DONOR_ID.rst 142 143 .. _donau_charity: 144 145 --------------------------------------------- 146 Charity administration and status information 147 --------------------------------------------- 148 149 The administration requests require an authorized bearer token to be set in the HTTP "Authorization" Header. This token can be set by a proxy validating authentication/authorization (using e.g. LDAP). 150 The GET status requests require an authorized bearer token as well. 151 152 .. include:: donau/get-charities.rst 153 154 .. _donau_charity_get: 155 156 .. include:: donau/get-charity-CHARITY_ID.rst 157 158 .. include:: donau/post-charities.rst 159 160 .. include:: donau/patch-charities-CHARITY_ID.rst 161 162 .. include:: donau/delete-charities-CHARITY_ID.rst