api-donau.rst (5317B)
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 98 .. _donau_issue: 99 100 -------------- 101 Issue receipts 102 -------------- 103 104 Inspired by the Taler exchange :ref:`Withdrawal<exchange-withdrawal>`. 105 106 This API is used to obtain valid, attested donation receipts from the Donau. 107 Use the :ref:`charity GET route<donau_charity_get>` to see the remaining donation volume for the current year. 108 109 CSR Issue 110 ~~~~~~~~~~~ 111 112 .. include:: donau/post-csr-issue.rst 113 114 115 Batch Issue 116 ~~~~~~~~~~~ 117 This is the effectiv issue receipts request. Depending on the amount of the donation a 118 certain amount of blinded unique donation identifiers, or for short BUDIs, are required. 119 Every BUDI will be signed by the corresponding requested donation unit, which is associated with a value. 120 This API is used by the charity but the array of `BlindedDonationReceiptKeyPair` are coming from the donor. 121 122 To make the request idempotent, the hash of the hole request is recorded under the 123 corresponding charity_id by the Donau. 124 125 .. include:: donau/post-batch-issue-CHARITY_ID.rst 126 127 .. _donation_statement: 128 129 ------------------ 130 Donation statement 131 ------------------ 132 133 Inspired by the Taler exchange :ref:`Deposit<deposit-par>`. 134 135 Donation statement operations are requested by a donor. 136 137 .. include:: donau/post-batch-submit.rst 138 139 .. include:: donau/get-donation-statement-YEAR-HASH_DONOR_ID.rst 140 141 .. _donau_charity: 142 143 --------------------------------------------- 144 Charity administration and status information 145 --------------------------------------------- 146 147 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). 148 The GET status requests require an authorized bearer token as well. 149 150 .. include:: donau/get-charities.rst 151 152 .. _donau_charity_get: 153 154 .. include:: donau/get-charity-CHARITY_ID.rst 155 156 .. include:: donau/post-charities.rst 157 158 159 .. include:: donau/patch-charities-{charity_id}.rst 160 161 162 .. include:: donau/delete-charities-{charity_id}.rst