taler-docs

post-batch-issue-CHARITY_ID.rst (5263B)

---

 .. http:POST:: /batch-issue/$CHARITY_ID
 
   Send in a `IssueReceiptsRequest` and ask the Donau to sign all it's contained BUDIs.
 
   **Request:** `IssueReceiptsRequest`
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The request was successful, and the response is a `BlindedDonationReceiptSignaturesResponse`.
     Also returned for idempotent re-requests of an already-processed batch.
   :http:statuscode:`400 Bad Request`:
     The request was malformed. This can occur when the ``$CHARITY_ID`` cannot be
     parsed, the ``budikeypairs`` array is empty or contains malformed entries,
     or the total donation amount exceeds the charity's per-year limit.
     Returned with error code ``TALER_EC_GENERIC_PARAMETER_MALFORMED``,
     ``TALER_EC_GENERIC_JSON_INVALID``, or
     ``TALER_EC_DONAU_EXCEEDING_DONATION_LIMIT``.
   :http:statuscode:`403 Forbidden`:
     The charity signature is invalid.
     Returned with error code ``TALER_EC_DONAU_CHARITY_SIGNATURE_INVALID``.
   :http:statuscode:`404 Not Found`:
     The charity is unknown to the Donau, or at least one of the referenced
     donation unit keys could not be found.
     Returned with error code ``TALER_EC_DONAU_CHARITY_NOT_FOUND`` or
     ``TALER_EC_DONAU_GENERIC_DONATION_UNIT_UNKNOWN``.
   :http:statuscode:`500 Internal Server Error`:
     The Donau encountered an internal error, such as a database failure or
     a signing helper problem.
     Returned with error code ``TALER_EC_GENERIC_DB_FETCH_FAILED`` or
     ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``
   :http:statuscode:`503 Service unavailable`:
     The donau is lacking the keys to create the donation statement.
     Returned with error code
     ``TALER_EC_DONAU_GENERIC_KEYS_MISSING``.
 
   **Details:**
 
   .. ts:def:: IssueReceiptsRequest
 
     interface IssueReceiptsRequest {
 
       // Signature by the charity approving that the
       // Donau should sign the donation receipts below.
       charity_sig: EddsaSignature;
 
       // Year for which the donation receipts are expected.
       // Also determines which keys are used to sign the
       // blinded donation receipts.
       year: Integer;
 
       // Array of blinded donation receipts to sign.
       // Must NOT be empty (if no donation receipts
       // are desired, just leave the entire ``donau``
       // argument blank).
       budikeypairs: BlindedDonationReceiptKeyPair[];
     }
 
   .. ts:def:: BlindedDonationReceiptKeyPair
 
     interface BlindedDonationReceiptKeyPair {
       // Hash of the public key that should be used to sign
       // the donation receipt.
       h_donation_unit_pub: HashCode;
 
       // Blinded value to give to the Donau to sign over.
       blinded_udi: BlindedUniqueDonationIdentifier;
     }
 
   .. ts:def:: BlindedUniqueDonationIdentifier
 
     type BlindedUniqueDonationIdentifier = RSABUDI | CSBUDI ;
 
   .. ts:def:: RSABUDI
 
     interface RSABUDI {
       cipher: "RSA";
       rsa_blinded_identifier: string;          // Crockford Base32 encoded
     }
 
   .. ts:def:: CSBUDI
 
     // For donation unit signatures based on Blind Clause-Schnorr, the BUDI
     // consists of the public nonce and two Curve25519 scalars which are two
     // blinded challenges in the Blinded Clause-Schnorr signature scheme.
     // See https://taler.net/papers/cs-thesis.pdf for details.
     interface CSBUDI {
       cipher: "CS";
       cs_nonce: string;      // Crockford Base32 encoded
       cs_blinded_c0: string; // Crockford Base32 encoded
       cs_blinded_c1: string; // Crockford Base32 encoded
     }
 
   .. ts:def:: BUDIBlindingKeyP
 
     // Secret for blinding/unblinding.
     // An RSA blinding secret, which is basically
     // a 256-bit nonce, converted to Crockford Base32.
     type BUDIBlindingKeyP = string;
 
   .. ts:def:: BlindedDonationReceiptSignaturesResponse
 
     interface BlindedDonationReceiptSignaturesResponse {
       // Total amount over which all the blind signatures are signing.
       issued_amount: Amount;
 
       // Array of the blind signatures.
       blind_signatures: BlindedDonationReceiptSignature[];
     }
 
   .. ts:def:: BlindedDonationReceiptSignature
 
     type BlindedDonationReceiptSignature =
       | RSABlindedDonationReceiptSignature
       | CSBlindedDonationReceiptSignature;
 
   .. ts:def:: RSABlindedDonationReceiptSignature
 
     interface RSABlindedDonationReceiptSignature {
       cipher: "RSA";
 
       // (blinded) RSA signature
       blinded_rsa_signature: BlindedRsaSignature;
     }
 
   .. ts:def:: CSBlindedDonationReceiptSignature
 
     interface CSBlindedDonationReceiptSignature {
       cipher: "CS";
 
       // Signer chosen bit value, 0 or 1, used
       // in Clause Blind Schnorr to make the
       // ROS problem harder.
       b: Integer;
 
       // Blinded scalar calculated from c_b.
       s: Cs25519Scalar;
     }
 
   .. ts:def:: IssueError
 
     interface IssueError{
       max_per_year: Amount;
       current_year: Amount;
     }
 
   .. ts:def:: DonationUnitUnknownError
 
     interface DonationUnitUnknownError{
       unknown_hash_pub_donation_unit: HashCode[];
       donau_pub: EddsaPublicKey;
       donau_sig: EddsaSignature;
     }
 
   .. ts:def:: DonationUnitExpiredMessage
 
     interface DonationUnitExpiredMessage{
       h_donation_unit_pub: HashCode;
       donau_pub: EddsaPublicKey;
       donau_sig: EddsaSignature;
     }