api-donau.rst (5401B)
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 3.0, 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 **v1**. 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 * ``v1``: Adds ``build_version`` to GET ``/config`` 67 68 **Upcoming versions:** 69 70 * none anticipated 71 72 **Ideas for future version:** 73 74 * ``vXXX``: marker for features not yet targeted for release 75 76 77 .. include:: tos.rst 78 79 .. _donau_status: 80 81 ---------------------------------------- 82 Donau public keys and status information 83 ---------------------------------------- 84 85 This API is used by donors and charities to obtain global information about 86 the Donau, such as online signing keys and available donation units. This is 87 typically the first call any Donau client makes, as it returns information 88 required to process all of the other interactions with the Donau. The 89 returned information is secured by signature(s) from the Donau, especially the 90 long-term offline signing key of the Donau, which clients should cache. 91 92 .. include:: donau/get-keys.rst 93 94 .. include:: donau/get-seed.rst 95 96 .. include:: donau/get-config.rst 97 98 .. include:: donau/get-history.rst 99 100 101 .. _donau_issue: 102 103 -------------- 104 Issue receipts 105 -------------- 106 107 Inspired by the Taler exchange :ref:`Withdrawal<exchange-withdrawal>`. 108 109 This API is used to obtain valid, attested donation receipts from the Donau. 110 Use the :ref:`charity GET route<donau_charity_get>` to see the remaining donation volume for the current year. 111 112 CSR Issue 113 ~~~~~~~~~~~ 114 115 .. include:: donau/post-csr-issue.rst 116 117 118 Batch Issue 119 ~~~~~~~~~~~ 120 This is the effective issue receipts request. Depending on the amount of the donation a 121 certain amount of blinded unique donation identifiers, or for short BUDIs, are required. 122 Every BUDI will be signed by the corresponding requested donation unit, which is associated with a value. 123 This API is used by the charity but the array of `BlindedDonationReceiptKeyPair` are coming from the donor. 124 125 To make the request idempotent, the hash of the whole request is recorded under the 126 corresponding charity_id by the Donau. 127 128 .. include:: donau/post-batch-issue-CHARITY_ID.rst 129 130 .. _donation_statement: 131 132 ------------------ 133 Donation statement 134 ------------------ 135 136 Inspired by the Taler exchange :ref:`Deposit<deposit-par>`. 137 138 Donation statement operations are requested by a donor. 139 140 .. include:: donau/post-batch-submit.rst 141 142 .. include:: donau/get-donation-statement-YEAR-HASH_DONOR_ID.rst 143 144 .. _donau_charity: 145 146 --------------------------------------------- 147 Charity administration and status information 148 --------------------------------------------- 149 150 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). 151 The GET status requests require an authorized bearer token as well. 152 153 .. include:: donau/get-charities.rst 154 155 .. _donau_charity_get: 156 157 .. include:: donau/get-charity-CHARITY_ID.rst 158 159 .. include:: donau/post-charities.rst 160 161 .. include:: donau/patch-charities-CHARITY_ID.rst 162 163 .. include:: donau/delete-charities-CHARITY_ID.rst