taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

post-batch-submit.rst (2541B)

      1 .. http:POST:: /batch-submit
      2 
      3   Send in donation receipts for the current or one of the past fiscal years.
      4   The donor will reveive the signed total back, which is called the
      5   donation statement.
      6 
      7   **Request:** `SubmitDonationReceiptsRequest`
      8 
      9   **Response:**
     10 
     11   :http:statuscode:`201 Created`:
     12     The request was successful, and a donation statement is now available. The response will be empty.
     13   :http:statuscode:`400 Bad Request`:
     14     The request body is malformed, required fields are missing, or the
     15     ``donation_receipts`` array is empty or contains malformed entries.
     16     Returned with error code ``TALER_EC_GENERIC_JSON_INVALID`` or
     17     ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     18   :http:statuscode:`403 Forbidden`:
     19     One of the donation receipt signatures is invalid.
     20     Returned with error code ``TALER_EC_DONAU_DONATION_RECEIPT_SIGNATURE_INVALID``.
     21   :http:statuscode:`404 Not Found`:
     22     At least one of the donation unit keys is not known to the Donau.
     23     Returned with error code ``TALER_EC_DONAU_GENERIC_DONATION_UNIT_UNKNOWN``.
     24   :http:statuscode:`409 Conflict`:
     25     A duplicate donor identifier nonce was detected within the submitted receipts.
     26     Returned with error code ``TALER_EC_DONAU_DONOR_IDENTIFIER_NONCE_REUSE``.
     27   :http:statuscode:`500 Internal Server Error`:
     28     The Donau encountered an internal database error.
     29     Returned with error code ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
     30 
     31   **Details:**
     32 
     33   .. ts:def:: SubmitDonationReceiptsRequest
     34 
     35     interface SubmitDonationReceiptsRequest{
     36       // hashed taxpayer ID plus salt
     37       h_donor_tax_id: HashCode;
     38       // All donation receipts must be for this year.
     39       donation_year: Integer;
     40       // Receipts should be sorted by amount.
     41       donation_receipts: DonationReceipt[];
     42     }
     43 
     44   .. ts:def:: DonationReceipt
     45 
     46     interface DonationReceipt {
     47       h_donation_unit_pub: HashCode;
     48       nonce: string;
     49       donation_unit_sig: DonationReceiptSignature;
     50     }
     51 
     52   .. ts:def:: DonationReceiptSignature
     53 
     54     type DonationReceiptSignature = RSADonationReceiptSignature | CSDonationReceiptSignature ;
     55 
     56   .. ts:def:: RSADonationReceiptSignature
     57 
     58     interface RSADonationReceiptSignature {
     59       cipher: "RSA";
     60 
     61       // RSA signature
     62       rsa_signature: RsaSignature;
     63     }
     64 
     65   .. ts:def:: CSDonationReceiptSignature
     66 
     67     interface CSDonationReceiptSignature {
     68       cipher: "CS";
     69 
     70       // R value component of the signature.
     71       cs_signature_r: Cs25519Point;
     72 
     73       // s value component of the signature.
     74       cs_signature_s: Cs25519Scalar;
     75     }