taler-docs

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

post-charities.rst (1836B)

      1 .. http:POST:: /charities
      2 
      3   Register a new charity with the Donau. Only allowed if the request comes with the
      4   administrator bearer token. The request body defines the charity's signing key,
      5   contact information, and the initial accounting values for the current business
      6   year. On success the Donau assigns a numeric identifier to the charity record.
      7 
      8   **Request:** `CharityRequest`
      9 
     10   **Response:**
     11 
     12   **Details:**
     13 
     14   :http:statuscode:`201 Created`:
     15     The request was successful, and the response is a `CharityResponse`.
     16   :http:statuscode:`400 Bad Request`:
     17     The request body is malformed or required fields are missing.
     18     Returned with error code ``TALER_EC_GENERIC_JSON_INVALID``.
     19   :http:statuscode:`403 Forbidden`:
     20     The request did not contain an accepted administrator bearer token in its header.
     21     Returned with error code ``TALER_EC_GENERIC_TOKEN_PERMISSION_INSUFFICIENT``.
     22   :http:statuscode:`409 Conflict`:
     23     A charity with the same public key already exists.
     24     Returned with error code ``TALER_EC_DONAU_CHARITY_PUB_EXISTS``.
     25   :http:statuscode:`500 Internal Server Error`:
     26     The Donau encountered a database error while storing the charity.
     27     Returned with error code ``TALER_EC_GENERIC_DB_STORE_FAILED``.
     28 
     29   .. ts:def:: CharityRequest
     30 
     31     interface CharityRequest {
     32 
     33       // Long-term EdDSA public key that identifies the charity.
     34       charity_pub: EddsaPublicKey;
     35 
     36       // Canonical URL that should be presented to donors.
     37       charity_url: string;
     38 
     39       // Human-readable display name of the charity.
     40       charity_name: string;
     41 
     42       // Allowed donation volume for the charity per calendar year.
     43       max_per_year: Amount;
     44     }
     45 
     46   .. ts:def:: CharityResponse
     47 
     48     interface CharityResponse {
     49 
     50       // Unique ID assigned to the charity in the backend.
     51       charity_id: Integer;
     52     }