.. target audience: developer, core developer

.. _sandbox-api:

Sandbox API
###########

Demobanks.
==========

Sandbox is designed to allow multiple *demobanks* being hosted,
where every demobank can have its own configuration (including
a different currency).  A demobank has a name, although currently
only one demobank, named ``default``, is supported.  Such demobank
activates the API segment ``/demobanks/default``, under which several
APIs are then served.  The following sections describe all such APIs.

Customer API.
^^^^^^^^^^^^^

This API allows CRUD operations on the bank's customers (also referred
as 'users').  All the calls are allowed for the administrator, whereas
**only** the `password change <customer-password-modification>`_ is allowed
for ordinary customers.

The following endpoints are served under ``/demobanks/default/customer-api``.

.. http:post:: /customers

   Create a new customer, including their bank account.

   **Request:**

   .. ts:def:: CustomerRequest
     
     interface CustomerRequest {
       // Username
       username: string;

       // Password.
       password: string;

       // E-Mail address
       email: string;

       // Phone number.
       phone: string;

       // Name denoting the legal subject being the customer.
       name: string;

       // 'payto' address pointing the bank account
       // where to send payments, in case the customer
       // wants to convert the local currency back to
       // fiat.
       payoutAddress: string;

       // IBAN to assign to this bank account.  Randomly
       // generated, when it is not given.
       iban?: string;
     }

   **Response:**

   :http:statuscode:`204 No content`:
     The customer was successfully created.
   :http:statuscode:`409 Conflict`: 
     One information was not available, the error message should inform
     about it.
   :http:statuscode:`403 Forbidden`:
     A istitutional username was attempted, like ``admin`` or ``bank``. 
   :http:statuscode:`404 Bad request`:
     Input data was invalid.  For example, the client specified a invalid
     phone number or e-mail.


.. http:delete:: /customers
  
  Delete a customer *with a zero balance* from the bank.

  **Request:**

  :query username: the username of the customer account to delete.

  **Response:**

  :http:statuscode:`204 No content`:
    The customer account was successfully deleted.
  :http:statuscode:`404 Not found`:
    The customer specified along the parameters was not found.
  :http:statuscode:`403 Forbidden`:
    The administrator specified a istitutional username, like
    ``admin`` or ``bank``.
  :http:statuscode:`412 Precondition failed`:
    The balance of the customer to delete was not zero.

.. _customer-password-modification:

.. http:patch:: /customers

   Allows administrators *and* ordinary customers to
   change customer password.

   **Request:**

   .. ts:def:: CustomerPasswordChange
      
     interface Customer {
       // Username of the customer whose password is
       // to be changed.  It is optional in case the
       // customer issues the request, because such information
       // can be retrieved from the authentication credentials.
       username?: string;

       // New password.
       newPassword: string;
     }

   **Response:**

   :http:statuscode:`204 No content`:
     Operation successful.
   :http:statuscode:`403 Forbidden`:
     A ordinary customer tried to change someone else's password.
     This error should happen *before* checking whether the target
     username exists, not to leak which usernames are already registered.
   :http:statuscode:`404 Not found`:
     The username whose password should be changed was not found.

.. http:get:: /customers

   Allows the administrator to obtain a list of all the
   customers registered at the bank.  It returns only the
   customer data (without any business information), because
   :doc:`Access API </core/api-bank-access>` may already
   be used for that.

   **Response:**

   .. ts:def:: Customers

     interfaces Customers {
       customers: CustomerData[]; 
     }

   .. ts:def:: CustomerData
     
     interface CustomerData {
       // Username
       username: string;

       // IBAN hosted at Libeufin Sandbox
       iban: string;

       // E-Mail address
       email: string;

       // Phone number.
       phone: string;

       // Name denoting the legal subject being the customer.
       name: string;

       // 'payto' address pointing the bank account
       // where to send payments, in case the customer
       // wants to convert the local currency back to
       // fiat.
       cashoutAddress: string;
     }


.. http:post:: /cashouts

   Lets the user specify an amount to be converted back
   to fiat currency.  The target account is the one specified
   at registration time.  The account to be debited is extracted
   from the authentication credentials.  The bank sends a TAN
   to the customer, to let them confirm the operation.

   ..
     FIXME: TAN first per e-mail, or phone?

   **Request:**

   .. ts:def:: CashoutRequest

     interface CashoutRequest {
       // Amount in the $currency:$value format.
       amount: string; 
     }

   **Response:**

   .. ts:def:: CashoutPending
     
     interface CashoutPending {
       // UUID identifying the operation being created
       // and now waiting the TAN confirmation.
       uuid: string; 
     }

   :http:statuscode:`202 Accepted`:
     The cashout request was correctly created and
     the TAN authentication now is pending.
   :http:statuscode:`412 Precondition failed`:
     Customer does not have sufficient funds.
   :http:statuscode:`409 Conflict`:
     A istitutional user (``admin`` or ``bank``) tried the operation.


.. http:post:: /cashouts/$cashoutId

   Confirms the cashout with UUID $cashoutId by
   accepting its TAN.  Please note that the request
   should still be authenticated with the users credentials.

   **Request:**

   .. ts:def:: CashoutConfirm
     
     interface CashoutConfirm {

       // the TAN that was shared by the bank that
       // confirms $cashoutId.
       tan: string;
     }


   **Response:**
   
   :http:statuscode:`200 OK`:
     cashout confirmed.
   :http:statuscode:`401 Unauthorized`:
     wrong TAN.
   :http:statuscode:`409 Conflict`:
     A istitutional user (``admin`` or ``bank``) tried the operation.

Access API.
^^^^^^^^^^^

Every endpoint is served under ``/demobanks/default/access-api``.
See :doc:`/core/api-bank-access`.  This API allows users to access
their bank accounts and trigger Taler withdrawals.

Integration API.
^^^^^^^^^^^^^^^^

Every endpoint is served under ``/demobanks/default/integration-api``.
See :doc:`/core/api-bank-integration`.  This API handles the communication
with Taler wallets.

Taler Wire Gateway API.
^^^^^^^^^^^^^^^^^^^^^^^

Served under ``/demobanks/default/taler-wire-gateway``.  Currently,
only the :ref:`admin/add-incoming <twg-admin-add-incoming>` endpoint
is implemented.  This endpoint allows testing, but the rest of
this API does never involve the Sandbox. 

EBICS API.
^^^^^^^^^^

.. _demobank-create-ebics-subscriber:

.. http:post:: /demobanks/default/ebics/subscribers

   Allows (only) the *admin* user to associate a bank account
   to a EBICS subscriber.  If the latter does not exist, it is
   created.

   **Request:**

   .. ts:def:: SubscriberRequest

     interface SubscriberRequest {

       // hostID
       hostID: string;

       // userID
       userID: string;

       // partnerID
       partnerID: string;

       // systemID, optional.
       systemID: string;

       // Label of the bank account to associate with
       // this subscriber.
       demobankAccountLabel: string;
     }

.. note::

  The following endpoints are **not** served under the ``/demobank/default`` segment.

Legacy API.
===========

This was the first API offered by Sandbox.  It is used in
some test cases.  One is hosted at the Wallet repository; other
MAY as well exist.

Except of the main EBICS handler located at "/ebicsweb", all
the EBICS calls have to authenticate the 'admin' user via
the HTTP basic auth scheme.

EBICS Hosts.
^^^^^^^^^^^^

.. http:post:: /admin/ebics/hosts

   Create a new EBICS host.

   **Request:**

   .. ts:def:: EbicsHostRequest

     interface EbicsHostRequest {

       // Ebics version.
       hostID: string;

       // Name of the host.
       ebicsVersion: string;
     }


.. http:get:: /admin/ebics/hosts

   Shows the list of all the hosts in the system.

   **Response:**

   .. ts:def:: EbicsHostResponse

     interface EbicsHostResponse {

       // shows the host IDs that are active in the system.
       // The Ebics version *is* missing, but it's still available
       // via the HEV message.
       ebicsHosts: string[];
     }

.. http:post:: /admin/ebics/hosts/$hostID/rotate-keys

   Overwrite the bank's Ebics keys with random ones.  This is entirely
   meant for tests (as the Sandbox itself is) and no backup will be
   produced along this operation.

EBICS Subscribers.
^^^^^^^^^^^^^^^^^^

.. http:post:: /admin/ebics/bank-accounts

  Associates a new bank account to an existing subscriber.

  **Request:**

  .. ts:def:: BankAccountRequest

    interface BankAccountRequest {

       // Ebics subscriber
       subscriber: {
         userID: string;
         partnerID: string;
         systemID: string;
       };

       // IBAN
       iban: string;

       // BIC
       bic: string;

       // human name
       name: string;

       // bank account label
       label: string;
     }

.. http:get:: /admin/ebics/subscribers

   Shows the list of all the subscribers in the system.

   **Response:**

   .. ts:def:: SubscribersResponse

     interface SubscribersResponse {

       subscribers: Subscriber[]
     }

   .. ts:def:: Subscriber

     interface Subscriber {

       // userID
       userID: string;

       // partnerID
       partnerID: string;

       // hostID
       hostID: string;

       // Label of the bank account
       // associated with this Ebics subscriber.
       demobankAccountLabel: string;
     }

.. http:post:: /admin/ebics/subscribers

   Create a new EBICS subscriber without associating
   a bank account to it.  This call is **deprecated**.
   Follow `this page <https://bugs.gnunet.org/view.php?id=7507>`_
   for updates over the EBICS management REST design.

   **Request:**

   .. ts:def:: SubscriberRequestDeprecated

     interface SubscriberRequestDeprecated {

       // hostID
       hostID: string;

       // userID
       userID: string;

       // partnerID
       partnerID: string;

       // systemID, optional.
       systemID: string;

     }

Bank accounts.
^^^^^^^^^^^^^^

The access to a particular bank account is granted either to the
owner or to admin, via the HTTP basic auth scheme.  A 'owner' is
a registered customer, who is identified by a username.  The
registration of customers is offered via the :doc:`/core/api-bank-access`.

.. note::

   The current version allows only one bank account per
   customer, where the bank account name (also called 'label')
   equals the owner's username.

.. http:get:: /admin/bank-accounts

   Give summary of all the bank accounts.  Only admin allowed.

   **Response:**

   .. ts:def:: AdminBankAccount

     interface AdminBankAccount {

       // IBAN
       iban: string;

       // BIC
       bic: string;

       // human name
       name: string;

       // bank account label
       label: string;
     }


.. http:get:: /admin/bank-accounts/$accountLabel

   Give information about a bank account.

   **Response:**

   .. ts:def:: AdminBankAccountBalance

     interface AdminBankAccountBalance {
       // Balance in the $currency:$amount format.
       balance: string; 
       // IBAN of the bank account identified by $accountLabel
       iban: string; 
       // BIC of the bank account identified by $accountLabel
       bic: string; 
       // Mentions $accountLabel
       label: string;
     }

.. http:post:: /admin/bank-accounts/$accountLabel

  Create bank account.  Existing users without a bank account
  can request too.

  **Request:** :ts:type:`AdminBankAccount`

Transactions.
^^^^^^^^^^^^^

.. http:get:: /admin/bank-accounts/$accountLabel/transactions

   Inform about all the transactions of one bank account.

   **Response:**

   .. ts:def:: AdminTransactions
   
     interface AdminTransactions {
       payments: AdminTransaction[]; 
     }

   .. ts:def:: AdminTransaction
   
     interface AdminTransaction {

       // Label of the bank account involved in this payment.
       accountLabel: string;

       // Creditor IBAN
       creditorIban: string;

       // Debtor IBAN
       debtorIban: string;

       // UID given by one financial institute to this payment.
       // FIXME: clarify whether that can be also assigned by
       // the other party's institution. 
       accountServicerReference: string;

       // ID of the Pain.001 that initiated this payment.
       paymentInformationId: string;

       // Unstructured remittance information.
       subject: string;

       // Date of the payment in the HTTP header format.
       date: string;

       // The number amount as a string.
       amount: string;

       // BIC of the creditor IBAN.
       creditorBic: string;

       // Legal name of the creditor.
       creditorName: string;

       // BIC of the debtor IBAN.
       debtorBic: string;

       // Legal name of the debtor.
       debtorName: string;

       // Payment's currency
       currency: string;

       // Have values 'credit' or 'debit' relative
       // to the requesting user.
       creditDebitIndicator: string;
     }

.. http:post:: /admin/bank-accounts/$accountLabel/generate-transactions

   Generate one incoming and one outgoing transaction for the bank account
   identified by ``$accountLabel``.  Only admin allowed.

.. http:post:: /admin/bank-accounts/$accountLabel/simulate-incoming-transaction

   Book one incoming transaction for $accountLabel.
   The debtor (not required to be in the same bank)
   information is taken from the request.  Only admin allowed.

   **Request:**
   
   .. ts:def:: AdminSimulateTransaction

     interface AdminSimulateTransaction {

       // Debtor IBAN.
       debtorIban: string; 

       // Debtor BIC.
       debtorBic: string; 

       // Debtor name.
       debtorName: string; 

       // Amount number (without currency) as a string.
       amount: string;

       // Payment subject.
       subject: string;
     }


.. http:post:: /admin/payments/camt

  Return the last camt.053 document from the requesting account.

  **Request**

  .. code-block:: tsref

    interface CamtParams {

      // label of the bank account being queried.
      bankaccount: string;

      // The Camt type to return.  Only '53' is allowed
      // at this moment.
      type: number;
    }

  **Response**

  The last Camt.053 document related to the bank account
  mentioned in the request body.


======
Errors
======

The JSON type coming along a non 2xx response is the following:

.. ts:def:: SandboxError

   interface SandboxError {
     error: SandboxErrorDetail;
   }

.. ts:def:: SandboxErrorDetail

   interface SandboxErrorDetail {

     // String enum classifying the error. 
     type: ErrorType;

     // Human-readable error description.
     message: string;
   }

.. ts:def:: ErrorType

   enum ErrorType {
     /**
      * This error can be related to a business operation,
      * a non-existent object requested by the client, or
      * even when the bank itself fails.
      */
     SandboxError = "sandbox-error",

     /**
      * It is the error type thrown by helper functions
      * from the Util library.  Those are used by both
      * Sandbox and Nexus, therefore the actual meaning
      * must be carried by the error 'message' field.
      */
     UtilError = "util-error"
   }