diff options
Diffstat (limited to 'libeufin/api-sandbox.rst')
| -rw-r--r-- | libeufin/api-sandbox.rst | 921 |
1 files changed, 693 insertions, 228 deletions
diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst index b75fcf8d..afbc3513 100644 --- a/libeufin/api-sandbox.rst +++ b/libeufin/api-sandbox.rst @@ -2,99 +2,530 @@ .. _sandbox-api: -Current Sandbox API -################### +Sandbox API +########### -.. - Current Sandbox endpoints. +Sandbox emulates a minimal bank, to provide EBICS access to test +`Taler <https://taler.net>`_. The top-level API defines two main +groups: `demobanks <Demobanks_>`_ and `legacy <Legacy API_>`_. +Currently, `error types <error-types_>`_ are common to both groups. - GET / - Welcome message. +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. + +Circuit API +^^^^^^^^^^^ + +This API offers to manage a selected group of users who act as businesses +for a local currency. Policies to disincentivize cashout operations may +also apply, making therefore this setup a *circuit* within a wider traditional +currency. + +For brevity, the list of response statuses for each endpoint may not be exhaustive. + +.. note:: + This API requires to **disable** ordinary registrations in the + configuration, to avoid other APIs from circumventing this registration + policy. See ``libeufin-sandbox config --help``. + +The following endpoints are served under ``/demobanks/default/circuit-api``. + +Accounts +-------- + +.. http:post:: /accounts + + Create a new bank account. Only the administrator is allowed. + + **Request:** + + .. ts:def:: CircuitAccountRequest + + interface CircuitAccountRequest { + // Username + username: string; + + // Password. + password: string; + + // Addresses where to send the TAN. If + // this field is missing, then the cashout + // won't succeed. + contact_data: CircuitContactData; + + // Legal subject owning the account. + name: string; + + // 'payto' address pointing the bank account + // where to send payments, in case the user + // wants to convert the local currency back + // to fiat. + cashout_address: string; + + // IBAN of this bank account, which is therefore + // internal to the circuit. Randomly generated, + // when it is not given. + internal_iban?: string; + } + + .. ts:def:: CircuitContactData + + interface CircuitContactData { + + // E-Mail address + email?: string; + + // Phone number. + phone?: string; + } + + + **Response:** + + :http:statuscode:`204 No content`: + The account was successfully created. + :http:statuscode:`400 Bad request`: + Input data was invalid. For example, the client specified a invalid + phone number or e-mail address. + :http:statuscode:`403 Forbidden`: + The response should indicate one of the following reasons. + + * A institutional username was attempted, like ``admin`` or ``bank``. + * A non admin user tried the operation. + + :http:statuscode:`409 Conflict`: + At least one registration detail was not available, + the error message should inform about it. + +.. http:delete:: /accounts/$username + + Delete the account whose username is ``$username``. The deletion + succeeds only if the balance is *zero*. Only the administrator is + allowed. + + **Response:** + + :http:statuscode:`204 No content`: + The account was successfully deleted. + :http:statuscode:`403 Forbidden`: + The administrator specified a institutional username, like + ``admin`` or ``bank``. + :http:statuscode:`404 Not found`: + The username was not found. + :http:statuscode:`412 Precondition failed`: + The balance was not zero. + + +.. http:patch:: /accounts/$username + + Allows the administrator and the user to reconfigure + the account data of ``$username``. + + **Request:** + + .. ts:def:: CircuitAccountReconfiguration + + interface CircuitAccountReconfiguration { + + // Addresses where to send the TAN. + contact_data: CircuitContactData; + + // 'payto' address pointing the bank account + // where to send payments, in case the user + // wants to convert the local currency back + // to fiat. + cashout_address: string; + } + + **Response:** + + :http:statuscode:`204 No content`: + Operation successful. + + :http:statuscode:`404 Not found`: + The account pointed by ``$username`` + was not found. + +.. http:patch:: /accounts/$username/auth + + Allows administrators *and* ordinary users to + change the account's password. + + **Request:** + + .. ts:def:: AccountPasswordChange + + interface AccountPasswordChange { + + // New password. + new_password: string; + } + + **Response:** + + :http:statuscode:`204 No content`: + Operation successful. + +.. http:get:: /accounts + + Obtains a list of all the accounts registered at the bank. + It returns only the information that this API handles, without + any balance or transactions list. The :doc:`Access API </core/api-bank-access>` + offers that. This request is only available to the administrator. + + **Response:** + + `CircuitAccounts <circuit-accounts_>`_ + + .. _circuit-accounts: + + .. ts:def:: CircuitAccounts + + interfaces CircuitAccounts { + customers: CircuitAccountMinimalData[]; + } + + .. ts:def:: CircuitAccountMinimalData + + interface CircuitAccountMinimalData { + // Username + username: string; + + // Legal subject owning the account. + name: string; - ** Camt debug ** + } - POST /admin/payments/camt - give last statement of requesting account +.. http:get:: /accounts/$username - ** Bank accounting ** + Obtains information relative to the account owned by + ``$username``. The request is available to the administrator + and ``$username`` itself. - POST /admin/bank-accounts/$accountLabel - create bank account (no EBICS involved) + **Response:** - GET /admin/bank-accounts - Give summary of all the bank accounts. + .. ts:def:: CircuitAccountData + + interface CircuitAccountData { + // Username + username: string; - GET /admin/bank-accounts/$accountLabel - give general information about a bank account + // IBAN hosted at Libeufin Sandbox + iban: string; - ** Transactions ** + contact_data: CircuitContactData; - 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. + // Legal subject owning the account. + name: string; - GET /admin/bank-accounts/$accountLabel/transactions - Inform about all the transactions of one bank account. + // 'payto' address pointing the bank account + // where to send cashouts. + cashout_address: string; + } - POST /admin/bank-accounts/$accountLabel/generate-transactions - Generate one incoming and one outgoing transaction - for one bank account. + :http:statuscode:`403 Forbidden`: + The user is not allowed. - ** EBICS subscribers management ** +Cashouts +-------- - POST /admin/ebics/subscribers - Create a new EBICS subscriber. +.. http:post:: /cashouts - GET /admin/ebics/subscribers - Give details of all the EBICS subscribers in the bank. + Initiates a conversion 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. The request is only available to ordinary users, not + to the administrator. - POST /admin/ebics/bank-accounts - Create a *new* bank account and link it with a existing - EBICS subscriber. + .. note:: + + Consult the `cashout rates call <cashout-rates_>`_ to learn + about any applicable fee or exchange rate. - ** EBICS host management ** + **Request:** - POST /admin/ebics/hosts/$hostID/rotate-keys - Change the bank's keys used in EBICS communication. + `CashoutRequest <cashout-request_>`_ - POST /admin/ebics/hosts - Create a new EBICS host. + .. ts:def:: TanChannel - GET /admin/ebics/hosts - Show details of all the EBICS hosts in the bank. + enum TanChannel { + SMS = "sms", + EMAIL = "email" + } - ** EBICS serving ** + .. _cashout-request: - POST /ebicsweb - Processes a EBICS request. + .. ts:def:: CashoutRequest - ** Taler .. ** + interface CashoutRequest { - GET /taler - Show one taler://-URI to initiate a withdrawal. + // Optional subject to associate to the + // cashout operation. This data will appear + // as the incoming wire transfer subject in + // the user's external bank account. + subject?: string; - - Taler integration API. + // That is the plain amount that the user specified + // to cashout. Its $currency is the circuit currency. + amount_debit: Amount; + + // That is the amount that will effectively be + // transferred by the bank to the user's bank + // account, that is external to the circuit. + // It is expressed in the fiat currency and + // is calculated after the cashout fee and the + // exchange rate. See the /cashout-rates call. + amount_credit: Amount; + + // Which channel the TAN should be sent to. If + // this field is missing, it defaults to SMS. + // The default choice prefers to change the communication + // channel respect to the one used to issue this request. + tan_channel?: TanChannel; + } + + **Response:** + + .. ts:def:: CashoutPending + + interface CashoutPending { + // UUID identifying the operation being created + // and now waiting for the TAN confirmation. + uuid: string; + } + + :http:statuscode:`202 Accepted`: + The cashout request was correctly created and + the TAN authentication now is pending. + :http:statuscode:`400 Bad request`: + The exchange rate was incorrectly applied. + :http:statuscode:`403 Forbidden`: + A institutional user (``admin`` or ``bank``) tried the operation. + :http:statuscode:`409 Conflict`: + The user did not share any contact data where to send the TAN. + :http:statuscode:`412 Precondition failed`: + The account does not have sufficient funds. + :http:statuscode:`503 Service unavailable`: + The bank does not support the TAN channel for this operation. + +.. http:post:: /cashouts/$cashoutId/abort + + Aborts the ``$cashoutId`` operation. Original author + *and* admin are both allowed. + + **Response:** + + :http:statuscode:`204 No content`: + ``$cashoutId`` was found in the *pending* state + and got successfully aborted. + :http:statuscode:`404 Not found`: + ``$cashoutId`` is not found. Note: that happens + also when ``$cashoutId`` got aborted before this request. + :http:statuscode:`412 Precondition failed`: + ``$cashoutId`` was already confirmed. + +.. http:post:: /cashouts/$cashoutId/confirm + + Confirms the ``$cashoutId`` operation by accepting its + TAN. The request should still be authenticated with + the users credentials. Only the original author is allowed. + + **Request:** - - Demobank configuration API. - ToDo. + .. ts:def:: CashoutConfirm + + interface CashoutConfirm { - - Taler access API. - ToDo. + // the TAN that confirms $cashoutId. + tan: string; + } + + **Response:** + + :http:statuscode:`204 No content`: + ``$cashoutId`` was found in the *pending* state and + got successfully confirmed. + :http:statuscode:`403 Forbidden`: + wrong TAN. + :http:statuscode:`404 Not found`: + ``$cashoutId`` is not found. Note: that happens + also when ``$cashoutId`` got aborted before this request. + :http:statuscode:`409 Conflict`: + A institutional user (``admin`` or ``bank``) tried the operation. + :http:statuscode:`412 Precondition failed`: + ``$cashoutId`` was already confirmed. + +.. _cashout-rates: + +.. http:get:: /config + + **Response:** + + .. ts:def:: Config + + interface Config { + // Name of this API, always "circuit". + name: string; + // API version in the form $n:$n:$n + version: string; + // Contains ratios and fees related to buying + // and selling the circuit currency. + ratios_and_fees: RatiosAndFees; + } + + .. ts:def:: RatiosAndFees + + interface RatiosAndFees { + // Exchange rate to buy the circuit currency from fiat. + buy_at_ratio: float; + // Exchange rate to sell the circuit currency for fiat. + sell_at_ratio: float; + // Fee to subtract after applying the buy ratio. + buy_in_fee: float; + // Fee to subtract after applying the sell ratio. + sell_out_fee: float; + } + + + Example. Given a circuit currency CC, a fiat currency FC, + a *sell_at_ratio* = 0.9 and *sell_out_fee* = 0.03, selling + 10 CC would result in the following FC: (10 * 0.9) - 0.03 + = 8.97 FC. On the other hand, given *buy_at_ratio* = 1.1 + and *buy_in_fee* = 0.01, a user wanting to spend 10 FC to + buy the CC would result in the following CC: (10 * 1.1) - + 0.01 = 10.99 CC. + + .. note:: + + the terms 'sell out' and 'cashout' may be used interchangeably. + +.. http:get:: /cashouts/$cashoutId + + Informs about the status of the ``$cashoutId`` operation. + The request is available to the administrator and the original author. + + **Response:** + + `CashoutStatusResponse <cashout-status_>`_ + + .. _cashout-status: + + .. ts:def:: CashoutStatus + + interface CashoutStatusResponse { + + status: CashoutStatus; + } + + .. ts:def:: CashoutStatus + + enum CashoutStatus { + + // The payment was initiated after a valid + // TAN was received by the bank. + CONFIRMED = "confirmed", + + // The cashout was created and now waits + // for the TAN by the author. + PENDING = "pending", + } + + **Response:** + + :http:statuscode:`404 Not found`: + The cashout operation was not found. That is + *also* the case of ``$cashoutId`` being an aborted + operation. + +Access API +^^^^^^^^^^ -EBICS. -^^^^^^ +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. -Hosts. -++++++ +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 - Creates a new Ebics host. + Create a new EBICS host. **Request:** - .. ts:def:: EbicsHostRequest + .. ts:def:: EbicsHostRequest interface EbicsHostRequest { @@ -112,7 +543,7 @@ Hosts. **Response:** - .. ts:def:: EbicsHostResponse + .. ts:def:: EbicsHostResponse interface EbicsHostResponse { @@ -128,9 +559,8 @@ Hosts. meant for tests (as the Sandbox itself is) and no backup will be produced along this operation. - -Subscribers. -++++++++++++ +EBICS Subscribers +^^^^^^^^^^^^^^^^^ .. http:post:: /admin/ebics/bank-accounts @@ -138,12 +568,16 @@ Subscribers. **Request:** - .. ts:def:: BankAccountRequest + .. ts:def:: BankAccountRequest - interface BankAccountRequest { + interface BankAccountRequest { // Ebics subscriber - subscriber: string; + subscriber: { + userID: string; + partnerID: string; + systemID: string; + }; // IBAN iban: string; @@ -156,19 +590,51 @@ Subscribers. // 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 - Creates a new Ebics subscriber. + 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:: SubscriberRequest + .. ts:def:: SubscriberRequestDeprecated - interface SubscriberRequest { + interface SubscriberRequestDeprecated { // hostID hostID: string; @@ -179,239 +645,238 @@ Subscribers. // partnerID partnerID: string; - // systemID + // systemID, optional. systemID: string; } +Bank accounts +^^^^^^^^^^^^^ -.. http:get:: /admin/ebics/subscribers - - Shows the list of all the subscribers in the system. - - **Response:** +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`. - .. ts:def:: SubscribersResponse +.. note:: - interface SubscribersResponse { + The current version allows only one bank account per + customer, where the bank account name (also called 'label') + equals the owner's username. - subscribers: Subscriber[] - } - - .. ts:def:: Subscriber +.. http:get:: /admin/bank-accounts - interface Subscriber { + Give summary of all the bank accounts. Only admin allowed. - // userID - userID: string; + **Response:** - // partnerID - partnerID: string; + .. ts:def:: AdminBankAccount - // hostID - hostID: string; + interface AdminBankAccount { - } + // IBAN + iban: string; + // BIC + bic: string; -Bank accounts. -^^^^^^^^^^^^^^ + // human name + name: string; -.. http:get:: /admin/bank-accounts + // bank account label + label: string; + } - Give summary of all the bank accounts. .. http:get:: /admin/bank-accounts/$accountLabel Give information about a bank account. + **Response:** -Main EBICS service. -^^^^^^^^^^^^^^^^^^^ + .. ts:def:: AdminBankAccountBalance -.. http:post:: /ebicsweb + 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; + } - Serves all the Ebics requests. +.. http:post:: /admin/bank-accounts/$accountLabel + Create bank account. Existing users without a bank account + can request too. -Transactions. -^^^^^^^^^^^^^ + **Request:** :ts:type:`AdminBankAccount` -JSON. -+++++ +Transactions +^^^^^^^^^^^^ .. http:get:: /admin/bank-accounts/$accountLabel/transactions Inform about all the transactions of one bank account. -.. http:post:: /admin/bank-accounts/$accountLabel/generate-transactions + **Response:** + + .. ts:def:: AdminTransactions + + interface AdminTransactions { + payments: AdminTransaction[]; + } - Generate one incoming and one outgoing transaction for one bank account. + .. ts:def:: AdminTransaction + + interface AdminTransaction { -.. http:post:: /admin/bank-accounts/$accountLabel/simulate-incoming-transaction + // Label of the bank account involved in this payment. + accountLabel: string; - Book one incoming transaction for $accountLabel. - The debtor (not required to be in the same bank) - information is taken from the request. + // Creditor IBAN + creditorIban: string; + // Debtor IBAN + debtorIban: string; -Camt. -+++++ + // 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; -.. http:post:: /admin/payments/camt + // ID of the Pain.001 that initiated this payment. + paymentInformationId: string; - Return the last statement of the requesting account. + // Unstructured remittance information. + subject: string; - **Request** + // 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; - .. code-block:: tsref + // Legal name of the creditor. + creditorName: string; - interface CamtParams { + // BIC of the debtor IBAN. + debtorBic: string; - // label of the bank account being queried. - bankaccount: string; + // Legal name of the debtor. + debtorName: string; - // The Camt type to return. Only '53' is allowed - // at this moment. - type: number; + // Payment's currency + currency: string; + + // Have values 'credit' or 'debit' relative + // to the requesting user. + creditDebitIndicator: string; } - **Response** +.. 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. - The expected Camt.053 document. + **Request:** + + .. ts:def:: AdminSimulateTransaction -Future Sandbox API -################## + interface AdminSimulateTransaction { -Resources. ----------- + // Debtor IBAN. + debtorIban: string; -Sandbox serves the following resources: + // Debtor BIC. + debtorBic: string; - - Demobanks. - - Bank accounts. - - Subscribers. - - Transactions. - - Customers. - - Reports. - -The resources are subject to all CRUD operations, via by two -types of users: the 'admin' and the customers. The admin has -rights on all of them. + // Debtor name. + debtorName: string; -One of the main differences with the previous versions is the -removal of the "/admin" initial component. If the administrator -authenticates for one operation, then this one is of type `admin`: -no need for a dedicate and extra URI part. + // Amount number (without currency) as a string. + amount: string; -For example, mocking transactions in the system was a typical -/admin-operation, but since transactions themselves are resources -and any resource is subject to CRUD operations, then mocking one -becomes just a `C` operation on the 'transactions' resources. If -a test case wants to simplify the authentication - by hard-coding -the credentials, for example - before mocking one transaction, then -it can impersonate the administrator. + // Payment subject. + subject: string; + } -.. note:: - ``POST``-ing to a endpoint with a trailing ``$id`` means - modification of a existing resource. +.. http:post:: /admin/payments/camt -Demobanks -^^^^^^^^^ + Return the last camt.053 document from the requesting account. -Demobanks are the main containers of all the other resources. -They take configuration values, like the currency for example. + **Request** -.. http:get:: /admin/demobanks -.. http:get:: /admin/demobanks/$id -.. http:post:: /admin/demobanks -.. http:post:: /admin/demobanks/$id -.. http:delete:: /admin/demobanks/$id + .. code-block:: tsref -Bank accounts. -^^^^^^^^^^^^^^ + interface CamtParams { -Bank accounts collect money of customers and participate -in transactions. + // label of the bank account being queried. + bankaccount: string; -The ``$base`` is one demobank, in the form ``/demobanks/$id``. -That is due because a bank account must inherit some defaults -from the demobank, like the currency. + // The Camt type to return. Only '53' is allowed + // at this moment. + type: number; + } -.. http:get:: $base/bankaccounts -.. http:get:: $base/bankaccounts/$id -.. http:post:: $base/bankaccounts -.. http:post:: $base/bankaccounts/$id -.. http:delete:: $base/bankaccounts/$id + **Response** -Subscribers. -^^^^^^^^^^^^ + The last Camt.053 document related to the bank account + mentioned in the request body. -Subscribers are (optional) customers identities for protocols -other than the native one. -A subscriber is not required to have a bank account `soon`. Therefore, -it can be created, and later be linked to one bank account. For this -reason, the ``$base`` should not mention one bank account. +.. _error-types: -.. note:: +====== +Errors +====== - Creating a subscriber is a time-consuming operation that goes often - through slow channels, therefore it should basically never be done - more than once. +The JSON type coming along a non 2xx response is the following: -.. http:get:: $base/subscribers -.. http:get:: $base/subscribers/$id -.. http:post:: $base/subscribers -.. http:post:: $base/subscribers/$id -.. http:delete:: $base/subscribers/$id +.. ts:def:: SandboxError -Transactions. -^^^^^^^^^^^^^ + interface SandboxError { + error: SandboxErrorDetail; + } -Transactions are money movements between bank accounts. +.. ts:def:: SandboxErrorDetail -For convenience, ``$base`` **could** mention one bank account -to let customers see their transactions without defining "history" -query parameters: like ``$demobank/bankaccounts/$bankaccountId/transactions``. + interface SandboxErrorDetail { -At the same time, transactions should be easy to query regardless -of whose bank account they involve -- for administrative reasons, for -example. Hence, a "global" URI scheme like ``$demobank/transactions?param=XXX`` -should be offered as well. + // String enum classifying the error. + type: ErrorType; -.. http:get:: $base/transactions -.. http:get:: $base/transactions/$id -.. http:post:: $base/transactions -.. http:post:: $base/transactions/$id -.. http:delete:: $base/transactions/$id + // Human-readable error description. + description: string; + } -Customers. -^^^^^^^^^^ +.. 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", -Customers are persons that **can** have one bank account. As -with subscribers, ``$base`` should not mention any bank account -so as to leave more flexibility to assign new bank accounts to -the same customer. - -.. 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 statement. A report lives -even after a bank account gets deleted or a customer leaves -the bank, therefore ``$base`` should only mention a demobank -instance. - -.. http:get:: $base/reports -.. http:get:: $base/reports/$id -.. http:post:: $base/reports -.. http:post:: $base/reports/$id -.. http:delete:: $base/reports/$id + /** + * 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" + } |