taler-docs

post-management-instances.rst (5349B)

---

 .. _post-management-instances:
 
 .. http:post:: /management/instances
 
   This request will be used to create a new merchant instance in the backend.
   It is only available for the implicit ``admin`` instance.
 
   **Required permission:** ``instances-write``
 
   **Request:**
 
   The request must be a `InstanceConfigurationRequest`.
 
   **Response:**
 
   :http:statuscode:`200 Ok`:
     An instance has been created and a login token is being returned.
     The response body will be a `InstanceCreatedResponse`
   :http:statuscode:`202 Accepted`:
     2FA is required for this operation, usually to validate the
     email and/or phone numbers registered for the instance.
     This returns the `ChallengeResponse`. @since **v21**
   :http:statuscode:`204 No content`:
     The backend has successfully created the instance.
   :http:statuscode:`400 Bad Request`:
     The request body is malformed or a required field is missing.
     Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` or ``TALER_EC_GENERIC_PARAMETER_MISSING``.
   :http:statuscode:`409 Conflict`:
     This instance already exists, but with other configuration options.
     Use "PATCH" to update an instance configuration. Alternatively,
     the currency provided in the configuration does not match the
     currency supported by this backend. Another possible conflict
     would be if a deleted but not purged instance is known under this
     ID to the backend.
     Returned with ``TALER_EC_MERCHANT_PRIVATE_POST_INSTANCES_ALREADY_EXISTS`` or
     ``TALER_EC_MERCHANT_PRIVATE_POST_INSTANCES_PURGE_REQUIRED``.
   :http:statuscode:`413 Request entity too large`:
     The uploaded body is to long, it exceeds the size limit.
     Returned with an error code of
     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
   :http:statuscode:`500 Internal Server Error`:
     The server experienced an internal failure.
     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``,
     ``TALER_EC_GENERIC_DB_START_FAILED`` or
     ``TALER_EC_GENERIC_DB_COMMIT_FAILED``.
 
   **Details:**
 
   .. ts:def:: InstanceConfigurationRequest
 
     interface InstanceConfigurationRequest {
 
       // Name of the merchant instance to create (will become $INSTANCE).
       // Must match the regex ``^[A-Za-z0-9][A-Za-z0-9_.@-]+$``.
       id: string;
 
       // Merchant name corresponding to this instance.
       name: string;
 
       // Merchant email for customer contact and password reset.
       email?: string;
 
       // Merchant phone number for password reset (2-FA)
       // @since **v21**.
       phone_number?: string;
 
       // Merchant public website.
       website?: string;
 
       // Merchant logo.
       logo?: ImageDataUrl;
 
       // Authentication settings for this instance
       auth: InstanceAuthConfigurationMessage;
 
       // The merchant's physical address (to be put into contracts).
       address: Location;
 
       // The jurisdiction under which the merchant conducts its business
       // (to be put into contracts).
       jurisdiction: Location;
 
       // Use STEFAN curves to determine default fees?
       // If false, no fees are allowed by default.
       // Can always be overridden by the frontend on a per-order basis.
       use_stefan: boolean;
 
       // If the frontend does NOT specify a payment deadline, how long should
       // offers we make be valid by default?
       // Optional @since **v22** (before the setting was mandatory).
       // If not provided, the global merchant default will be used.
       default_pay_delay?: RelativeTime;
 
       // If the frontend does NOT specify a refund deadline, how long should
       // refunds be allowed by default? Added on top of the
       // payment deadline.
       // @since **v22**
       default_refund_delay?: RelativeTime;
 
       // If the frontend does NOT specify an execution date, how long should
       // we tell the exchange to wait to aggregate transactions before
       // executing the wire transfer?  This delay is added on top of
       // the refund deadline and afterwards subject to rounding
       // via the ``default_wire_transfer_rounding_interval``.
       // Optional @since **v22** (before the setting was mandatory).
       // If not provided, the global merchant default will be used.
       default_wire_transfer_delay?: RelativeTime;
 
       // How far should the wire deadline (if computed with the help of
       // the ``default_wire_transfer_delay``) be rounded up to compute
       // the ultimate wire deadline?
       // @since **v22**, defaults to no rounding if not given.
       default_wire_transfer_rounding_interval?: RoundingInterval;
     }
 
   .. ts:def:: InstanceCreatedResponse
 
     interface InstanceCreatedResponse {
 
       // The login token that can be used to access resources
       // that are in scope for some time. Must be prefixed
       // with "Bearer " when used in the "Authorization" HTTP header.
       // Will already begin with the RFC 8959 prefix.
       // **Since v19**
       access_token: string;
 
       // Legacy field for the access token.
       // @deprecated since **v19**.
       token: string;
 
       // Scope of the access token
       scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";
 
       // True if the access token can be refreshed.
       refreshable: boolean;
 
       // Time when the access token expires.
       expiration: Timestamp;
 
     }