diff options
| -rw-r--r-- | core/api-donau.rst | 180 | ||||
| -rw-r--r-- | core/api-exchange.rst | 1 |
2 files changed, 59 insertions, 122 deletions
diff --git a/core/api-donau.rst b/core/api-donau.rst index b8f33a0e..57a66603 100644 --- a/core/api-donau.rst +++ b/core/api-donau.rst @@ -155,44 +155,44 @@ should cache. } - .. ts:def:: DonauDonationUnitKeyGroup + .. ts:def:: DonationUnitKeyGroup - type DonauDonationUnitKeyGroup = - | DonauDonationUnitKeyGroupRsa - | DonauDonationUnitKeyGroupCs; + type DonationUnitKeyGroup = + | DonationUnitKeyGroupRsa + | DonationUnitKeyGroupCs; - .. ts:def:: DonauDonationUnitKeyGroupRsa + .. ts:def:: DonationUnitKeyGroupRsa - interface DonauDonationUnitKeyGroupRsa extends DonauDonationUnitKeyGroupCommon { + interface DonationUnitKeyGroupRsa extends DonationUnitKeyGroupCommon { cipher: "RSA"; denoms: ({ rsa_pub: RsaPublicKey; - } & DonauDonationUnitKeyCommon)[]; + } & DonationUnitKeyCommon)[]; } - .. ts:def:: DonauDonationUnitKeyGroupCs + .. ts:def:: DonationUnitKeyGroupCs - interface DonauDonationUnitKeyGroupCs extends DonauDonationUnitKeyGroupCommon { + interface DonationUnitKeyGroupCs extends DonationUnitKeyGroupCommon { cipher: "CS"; denoms: ({ cs_pub: Cs25519Point; - } & DonauDonationUnitKeyCommon)[]; + } & DonationUnitKeyCommon)[]; } - .. ts:def:: DonauDonationUnitKeyGroupCommon + .. ts:def:: DonationUnitKeyGroupCommon - // Common attributes for all denomination groups - interface DonauDonationUnitKeyGroupCommon { + // Common attributes for all donation unit groups + interface DonationUnitKeyGroupCommon { // How much was donated based on this donation receipt. value: Amount; } - .. ts:def:: DonauDonationUnitKeyCommon + .. ts:def:: DonationUnitKeyCommon - interface DonauDonationUnitKeyCommon { + interface DonationUnitKeyCommon { // For which year is this denomination unit key valid. year: Integer; @@ -204,24 +204,24 @@ should cache. lost?: boolean; } - .. ts:def:: DonauDonationUnitKey + .. ts:def:: DonationUnitKey - type DonauDonationUnitKey = - | RsaDonauDonationUnitKey - | CSDonauDonationUnitKey; + type DonationUnitKey = + | RsaDonationUnitKey + | CSDonationUnitKey; - .. ts:def:: RsaDonauDonationUnitKey + .. ts:def:: RsaDonationUnitKey - interface RsaDonauDonationUnitKey { + interface RsaDonationUnitKey { cipher: "RSA"; // RSA public key rsa_public_key: RsaPublicKey; } - .. ts:def:: CSDonauDonationUnitKey + .. ts:def:: CSDonationUnitKey - interface CSDonauDonationUnitKey { + interface CSDonationUnitKey { cipher: "CS"; // Public key of the denomination. @@ -255,7 +255,7 @@ should cache. Issue receipts ---------------------------------------- -Inspired by Taler's `Withdraw`. +Inspired by the Taler exchange :ref:`Withdrawal<exchange-withdrawal>`. This API is used by the charity to obtain valid, attested donation receipts from the donau. Use the :ref:`charity GET route<donau_charity_get>` to see the remaining donation volume for the current year. @@ -280,7 +280,7 @@ All incoming `BDID` are recorded under the corresponding charity_id by the donau interface IssueReceiptsRequest { charity_signature: EddsaSignature; - year: int; + year: Integer; bdids: BDID[]; } @@ -323,6 +323,8 @@ All incoming `BDID` are recorded under the corresponding charity_id by the donau ----------------------------- Submit receipts (ex Deposit) ----------------------------- +Inspired by the Taler exchange :ref:`Deposit<deposit-par>`. + .. http:POST:: /submit @@ -341,7 +343,7 @@ Submit receipts (ex Deposit) interface SubmitRequest{ taxnr_hashed: HashCode; - year: int; + year: Integer; donation_receipts: DonationReceipt[]; } @@ -419,11 +421,11 @@ Charity administration and status information .. ts:def:: Charity interface Charity{ - charity_id: int, + charity_id: Integer; pub_key: RsaPublicKey; max_per_year: Amount; current_year: Amount; - receipts_to_date: int; + receipts_to_date: Integer; } .. _donau_charity_get: @@ -462,15 +464,27 @@ Charity administration and status information pub_key: RsaPublicKey; max_per_year: Amount; current_year: Amount; - receipts_to_date: int; + receipts_to_date: Integer; } .. ts:def:: CharityResponse interface CharityResponse{ - id: int; + id: Integer; } + +.. http:PATCH:: /charities/{id} + + Modify a charity + + **Request:** `CharityRequest` + + **Response:** + + :http:statuscode:`200 OK`: + The request was successful. + .. http:get:: /charities/$CHARITY_ID/history Request information about the history of a charity. @@ -480,108 +494,30 @@ Charity administration and status information **Response:** :http:statuscode:`200 OK`: - The Donau responds with a `CharityStatus` object; the charity was known to the Donau. - :http:statuscode:`403 Forbidden`: - The *TALER_SIGNATURE_CHARITY_HISTORY_REQUEST* is invalid. - This response comes with a standard `ErrorDetail` response. Alternatively, the provided timestamp is not close to the current time. + The Donau responds with a `CharityHistory` object; the charity was known to the Donau. + :http:statuscode:`400 Bad request`: + The charity id is malformed. :http:statuscode:`404 Not found`: The charity key does not belong to a charity known to the donau. **Details:** - .. ts:def:: CharityHistoryRequest - - interface CharityHistoryRequest { - // Signature of type - // ``TALER_SIGNATURE_CHARITY_HISTORY_REQUEST`` - // over a `TALER_CharityHistoryRequestSignaturePS`. - charity_sig: EddsaSignature; + .. ts:def:: CharityHistory - // Time when the client made the request. - // Timestamp must be reasonably close to the time of - // the donau, otherwise the donau may reject - // the request. - request_timestamp: Timestamp; + interface CharityHistory { + charityHistoryYears: CharityHistoryYear[]; + donau_sig: EddsaSignature; } - .. ts:def:: CharityStatus - - interface CharityStatus { - // Balance left in the charity. - balance: Amount; - - // If set, gives the maximum age group that the client is required to set - // during withdrawal. - maximum_age_group: number; - - // Transaction history for this charity. - // May be partial (!). - history: TransactionHistoryItem[]; - } - - Objects in the transaction history have the following format: - - .. ts:def:: TransactionHistoryItem - - // Union discriminated by the "type" field. - type TransactionHistoryItem = - | CharityWithdrawTransaction - | CharityCreditTransaction; - - .. ts:def:: CharityWithdrawTransaction - - interface CharityWithdrawTransaction { - type: "WITHDRAW"; + .. ts:def:: CharityHistoryYear - // Amount withdrawn. - amount: Amount; - - // Hash of the denomination public key of the receipt. - h_denom_pub: HashCode; - - // Hash of the blinded receipt to be signed. - h_receipt_envelope: HashCode; - - // Signature over a `TALER_WithdrawRequestPS` - // with purpose ``TALER_SIGNATURE_WALLET_CHARITY_WITHDRAW`` - // created with the charity's private key. - charity_sig: EddsaSignature; - - // Fee that is charged for withdraw. - withdraw_fee: Amount; + interface CharityHistoryYear { + year: Integer; + //pub_key: RsaPublicKey; + final_amout: Amount; + // for statistics + max_per_year: Amount; } - .. ts:def:: CharityCreditTransaction - - interface CharityCreditTransaction { - type: "CREDIT"; - - // Amount deposited. - amount: Amount; - - // Sender account ``payto://`` URL. - sender_account_url: string; - - // Opaque identifier internal to the donau that - // uniquely identifies the wire transfer that credited the charity. - wire_reference: Integer; - - // Timestamp of the incoming wire transfer. - timestamp: Timestamp; - } - - -.. http:PATCH:: /charities/{id} - - Modify a charity - - **Request:** `CharityRequest` - - **Response:** - - :http:statuscode:`200 OK`: - The request was successful, and the response is a `CharityResponse`. - - diff --git a/core/api-exchange.rst b/core/api-exchange.rst index a2826761..5bdebef0 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -1591,6 +1591,7 @@ This part of the API is for the use by auditors interacting with the exchange. } +.. _exchange-withdrawal: ---------- Withdrawal |