taler-docs

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

post-charities.rst (1614B)

      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 
     17   :http:statuscode:`403 Forbidden`:
     18     The request did not contain an accepted administrator bearer token in its header.
     19 
     20   :http:statuscode:`404 Not found`:
     21     The referenced resource needed to create the charity was not found. This response
     22     comes with a standard `ErrorDetail` response.
     23 
     24   :http:statuscode:`409 Conflict`:
     25     A charity with the same public key exists in the backend, but it
     26     has different details. This response
     27     comes with a standard `ErrorDetail` response.
     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     }