taler-docs

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

post-private-tokenfamilies.rst (3211B)

      1 .. http:post:: [/instances/$INSTANCE]/private/tokenfamilies
      2 
      3   This is used to create a token family.
      4 
      5   **Required permission:** ``tokenfamilies-write`` (see :ref:`Scopes <merchant-api-scopes>`)
      6 
      7   **Request:**
      8 
      9   The request must be a `TokenFamilyCreateRequest`.
     10 
     11   **Response:**
     12 
     13   :http:statuscode:`204 No content`:
     14     The token family was created successfully.
     15 
     16   :http:statuscode:`400 Bad Request`:
     17     The request body is malformed.
     18     Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     19   :http:statuscode:`404 Not found`:
     20     The merchant backend is unaware of the instance.
     21   :http:statuscode:`409 Conflict`:
     22     A token family with this slug already exists.
     23     Returned with ``TALER_EC_MERCHANT_POST_TOKEN_FAMILY_CONFLICT``.
     24   :http:statuscode:`413 Request entity too large`:
     25     The uploaded body is to long, it exceeds the size limit.
     26     Returned with an error code of
     27     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     28   :http:statuscode:`500 Internal Server Error`:
     29     The server experienced an internal failure.
     30     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``,
     31     ``TALER_EC_GENERIC_DB_START_FAILED``,
     32     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     33     ``TALER_EC_GENERIC_DB_SOFT_FAILURE``,
     34     ``TALER_EC_GENERIC_DB_COMMIT_FAILED`` or
     35     ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``.
     36 
     37   **Details:**
     38 
     39   .. ts:def:: TokenFamilyCreateRequest
     40 
     41     interface TokenFamilyCreateRequest {
     42 
     43       // Identifier for the token family.
     44       slug: Slug;
     45 
     46       // Human-readable name for the token family.
     47       name: string;
     48 
     49       // Human-readable description for the token family.
     50       description: string;
     51 
     52       // Optional map from IETF BCP 47 language tags to localized descriptions.
     53       description_i18n?: { [lang_tag: string]: string };
     54 
     55       // Additional meta data, such as the ``trusted_domains``
     56       // or ``expected_domains``. Depends on the ``kind``.
     57       extra_data?: object;
     58 
     59       // Start time of the token family's validity period.
     60       // If not specified, merchant backend will use the current time.
     61       valid_after?: Timestamp;
     62 
     63       // End time of the token family's validity period.
     64       // If not specified, the token family is valid indefinitely.
     65       // Optional since protocol **v36**.
     66       valid_before?: Timestamp;
     67 
     68       // Validity duration of an issued token.
     69       duration: RelativeTime;
     70 
     71       // Rounding granularity for the start validity of keys.
     72       // The desired time is rounded down to a multiple of this
     73       // granularity and then the ``start_offset`` is added to
     74       // compute the actual start time of the token keys' validity.
     75       // The end is then computed by adding the ``duration``.
     76       // Must be 1 minute, 1 hour, 1 day, 1 week, 30 days, 90 days
     77       // or 365 days (1 year).
     78       validity_granularity: RelativeTime;
     79 
     80       // Offset to subtract from the start time rounded to ``validity_granularity``
     81       // to compute the actual start time for a key.
     82       // Default is zero.
     83       start_offset: RelativeTime;
     84 
     85       // Kind of the token family.
     86       kind: TokenFamilyKind;
     87 
     88    }
     89 
     90   .. ts:def:: TokenFamilyKind
     91 
     92     enum TokenFamilyKind {
     93       Discount = "discount",
     94       Subscription = "subscription",
     95     }