.. target audience: developer, core developer

.. _sandbox-api:

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

..
  Current Sandbox endpoints.

  GET /
  Welcome message.

  POST /admin/payments/camt 
  give last statement of requesting account

  ** Bank accounting **

  POST /admin/bank-accounts/$accountLabel 
  create bank account (no EBICS involved)

  GET /admin/bank-accounts
  Give summary of all the bank accounts.

  GET /admin/bank-accounts/$accountLabel 
  give general information about a bank account

  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.

  GET /admin/bank-accounts/$accountLabel/transactions
  Inform about all the transactions of one bank account.

  POST /admin/bank-accounts/$accountLabel/generate-transactions
  Generate one incoming and one outgoing transaction
  for one bank account.

  ** EBICS subscribers management **

  POST /admin/ebics/subscribers
  Create a new EBICS subscriber.

  GET /admin/ebics/subscribers
  Give details of all the EBICS subscribers in the bank.

  POST /admin/ebics/bank-accounts
  Create a *new* bank account and link it with a existing
  EBICS subscriber.

  ** EBICS host management **

  POST /admin/ebics/hosts/$hostID/rotate-keys
  Change the bank's keys used in EBICS communication.

  POST /admin/ebics/hosts
  Create a new EBICS host.

  GET /admin/ebics/hosts
  Show details of all the EBICS hosts in the bank. 

  ** EBICS serving **

  POST /ebicsweb
  Processes a EBICS request.

  ** Taler .. **

  GET /taler
  Show one taler://-URI to initiate a withdrawal.

  - Taler integration API.
    80% done.

  - Demobank configuration API.
    ToDo.

  - Taler access API.
    ToDo.

EBICS.
^^^^^^

Hosts.
++++++

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

   Creates 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.


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: string;

       // IBAN
       iban: string;

       // BIC
       bic: string;

       // human name
       name: string;

       // bank account label
       label: string;

     }


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

   Creates a new Ebics subscriber.

   **Request:**

   .. ts:def:: SubscriberRequest

     interface SubscriberRequest {

       // hostID
       hostID: string;

       // userID
       userID: string;

       // partnerID
       partnerID: string;

       // systemID
       systemID: 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;

      }


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

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

   Give summary of all the bank accounts.

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

   Give information about a bank account.


Main EBICS service.
^^^^^^^^^^^^^^^^^^^

.. http:post:: /ebicsweb

   Serves all the Ebics requests.


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

JSON.
+++++

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

   Inform about all the transactions of one bank account.

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

   Generate one incoming and one outgoing transaction for one bank account.

.. 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.


Camt.
+++++

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

  Return the last statement of 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 expected Camt.053 document.