taler-docs

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

---

 .. 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, or the ``budikeypairs`` array is empty or contains malformed entries.
     Returned with error code ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` or
     ``TALER_EC_GENERIC_JSON_INVALID``.
     Before protocol **v2**, an exceeded per-year limit was also
     reported with this status (see 409).
   :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:`409 Conflict`:
     The request conflicts with the state of the Donau. Clients must
     distinguish the cases by the error code:
 
     * ``TALER_EC_DONAU_GENERIC_DONATION_UNIT_WRONG_YEAR``: the year specified
       does not match the validity year for the given donation unit key.
     * ``TALER_EC_DONAU_EXCEEDING_DONATION_LIMIT``: the total donation amount
       exceeds what remains of the charity's per-year limit.
       Since protocol **v2**; before, this was a 400.
   :http:statuscode:`410 Gone`:
     The year specified is in the past, and the Donau does
     not permit issuing donation receipts in the past. The
     client should pick a donation unit from the current year.
     Returned with an error code of
     ``TALER_EC_DONAU_GENERIC_DONATION_UNIT_EXPIRED``.
   :http:statuscode:`425 Too Early`:
     The year specified is in the future, and the Donau
     does not permit issuing donation receipts in the future.
     The client may retry the request in the specified year,
     at that point it may succeed. Returned with an error code of
     ``TALER_EC_DONAU_GENERIC_DONATION_UNIT_TOO_EARLY``.
   :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;
     }