path: root/libeufin/api-sandbox.rst

.. target audience: developer, core developer

.. _sandbox-api:

Resources.
##########

Sandbox serves the following resources:

 - Demobanks.
 - Bank accounts.
 - Subscribers.
 - Transactions.
 - Customers.
 - Reports.
 
Such resources are subject to all CRUD operations through
two main trunks: ``/admin`` and ``/demobanks``.

the admin trunk has total rights on all of them, whereas the
``/demobank`` can only reach as far as a bank customer is allowed
to.  For example, under the admin trunk will be possible to create
and/or delete a new demobank (with its own configuration values),
but that'll be forbidden under the demobank trunk.

Hence typically, the admin trunk has all the accesses protected
by a access token.

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

Future Sandbox API
##################

.. note::

   ``POST``-ing to a endpoint with a trailing ``$id`` means
   modification of a existing resource.

Demobanks
^^^^^^^^^

Demobanks contain bank accounts, and are configurable.

.. http:get:: /admin/demobanks
.. http:get:: /admin/demobanks/$id
.. http:post:: /admin/demobanks
.. http:post:: /admin/demobanks/$id
.. http:delete:: /admin/demobanks/$id

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

Bank accounts collect money of users and participate
in transactions.

.. http:get:: $base/bankaccounts
.. http:get:: $base/bankaccounts/$id
.. http:post:: $base/bankaccounts
.. http:post:: $base/bankaccounts/$id
.. http:delete:: $base/bankaccounts/$id

Subscribers.
^^^^^^^^^^^^

Subscribers are (optional) customers identities for protocols
other than the native one.

.. http:get:: $base/subscribers
.. http:get:: $base/subscribers/$id
.. http:post:: $base/subscribers
.. http:post:: $base/subscribers/$id
.. http:delete:: $base/subscribers/$id

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

Transactions are money movements between bank accounts.

.. http:get:: $base/transactions
.. http:get:: $base/transactions/$id
.. http:post:: $base/transactions
.. http:post:: $base/transactions/$id
.. http:delete:: $base/transactions/$id

.. note::
   A "history" endpoint can be implemented by providing
   some filtering parameters to the first GET call.

Customers.
^^^^^^^^^^

Customers are persons with at least one bank account.

.. http:get:: $base/customers
.. http:get:: $base/customers/$id
.. http:post:: $base/customers
.. http:post:: $base/customers/$id
.. http:delete:: $base/customers/$id

Reports.
^^^^^^^^

Reports are persistent documents witnessing transactions.
A typical example is a Camt.053 report.

.. http:get:: $base/reports
.. http:get:: $base/reports/$id
.. http:post:: $base/reports
.. http:post:: $base/reports/$id
.. http:delete:: $base/reports/$id