taler-docs

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

post-management-instances.rst (4890B)

      1 .. http:post:: /management/instances
      2 
      3   This request will be used to create a new merchant instance in the backend.
      4   It is only available for the implicit ``admin`` instance.
      5 
      6   **Required permission:** ``instances-write``
      7 
      8   **Request:**
      9 
     10   The request must be a `InstanceConfigurationRequest`.
     11 
     12   **Response:**
     13 
     14   :http:statuscode:`200 Ok`:
     15     An instance has been created and a login token is being returned.
     16     The response body will be a `InstanceCreatedResponse`
     17   :http:statuscode:`202 Accepted`:
     18     2FA is required for this operation, usually to validate the
     19     email and/or phone numbers registered for the instance.
     20     This returns the `ChallengeResponse`. @since **v21**
     21   :http:statuscode:`204 No content`:
     22     The backend has successfully created the instance.
     23   :http:statuscode:`400 Bad Request`:
     24     The request body is malformed or a required field is missing.
     25     Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` or ``TALER_EC_GENERIC_PARAMETER_MISSING``.
     26   :http:statuscode:`409 Conflict`:
     27     This instance already exists, but with other configuration options.
     28     Use "PATCH" to update an instance configuration. Alternatively,
     29     the currency provided in the configuration does not match the
     30     currency supported by this backend. Another possible conflict
     31     would be if a deleted but not purged instance is known under this
     32     ID to the backend.
     33   :http:statuscode:`500 Internal Server Error`:
     34     The server experienced an internal failure.
     35     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
     36 
     37   **Details:**
     38 
     39   .. ts:def:: InstanceConfigurationRequest
     40 
     41     interface InstanceConfigurationRequest {
     42 
     43       // Name of the merchant instance to create (will become $INSTANCE).
     44       // Must match the regex ``^[A-Za-z0-9][A-Za-z0-9_.@-]+$``.
     45       id: string;
     46 
     47       // Merchant name corresponding to this instance.
     48       name: string;
     49 
     50       // Merchant email for customer contact and password reset.
     51       email?: string;
     52 
     53       // Merchant phone number for password reset (2-FA)
     54       // @since **v21**.
     55       phone_number?: string;
     56 
     57       // Merchant public website.
     58       website?: string;
     59 
     60       // Merchant logo.
     61       logo?: ImageDataUrl;
     62 
     63       // Authentication settings for this instance
     64       auth: InstanceAuthConfigurationMessage;
     65 
     66       // The merchant's physical address (to be put into contracts).
     67       address: Location;
     68 
     69       // The jurisdiction under which the merchant conducts its business
     70       // (to be put into contracts).
     71       jurisdiction: Location;
     72 
     73       // Use STEFAN curves to determine default fees?
     74       // If false, no fees are allowed by default.
     75       // Can always be overridden by the frontend on a per-order basis.
     76       use_stefan: boolean;
     77 
     78       // If the frontend does NOT specify a payment deadline, how long should
     79       // offers we make be valid by default?
     80       // Optional @since **v22** (before the setting was mandatory).
     81       // If not provided, the global merchant default will be used.
     82       default_pay_delay?: RelativeTime;
     83 
     84       // If the frontend does NOT specify a refund deadline, how long should
     85       // refunds be allowed by default? Added on top of the
     86       // payment deadline.
     87       // @since **v22**
     88       default_refund_delay?: RelativeTime;
     89 
     90       // If the frontend does NOT specify an execution date, how long should
     91       // we tell the exchange to wait to aggregate transactions before
     92       // executing the wire transfer?  This delay is added on top of
     93       // the refund deadline and afterwards subject to rounding
     94       // via the ``default_wire_transfer_rounding_interval``.
     95       // Optional @since **v22** (before the setting was mandatory).
     96       // If not provided, the global merchant default will be used.
     97       default_wire_transfer_delay?: RelativeTime;
     98 
     99       // How far should the wire deadline (if computed with the help of
    100       // the ``default_wire_transfer_delay``) be rounded up to compute
    101       // the ultimate wire deadline?
    102       // @since **v22**, defaults to no rounding if not given.
    103       default_wire_transfer_rounding_interval?: RoundingInterval;
    104     }
    105 
    106   .. ts:def:: InstanceCreatedResponse
    107 
    108     interface InstanceCreatedResponse {
    109 
    110       // The login token that can be used to access resources
    111       // that are in scope for some time. Must be prefixed
    112       // with "Bearer " when used in the "Authorization" HTTP header.
    113       // Will already begin with the RFC 8959 prefix.
    114       // **Since v19**
    115       access_token: string;
    116 
    117       // Legacy field for the access token.
    118       // @deprecated since **v19**.
    119       token: string;
    120 
    121       // Scope of the access token
    122       scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";
    123 
    124       // True if the access token can be refreshed.
    125       refreshable: boolean;
    126 
    127       // Time when the access token expires.
    128       expiration: Timestamp;
    129 
    130     }