[taler-docs] branch master updated: Customer API draft.

[gnunet]

This is an automated email from the git hooks/post-receive script.

ms pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 5cc3fce  Customer API draft.
5cc3fce is described below

commit 5cc3fce8075c4666f271611a3988392a14731d92
Author: MS <ms@taler.net>
AuthorDate: Tue Dec 6 17:21:11 2022 +0100

    Customer API draft.
---
 libeufin/api-sandbox.rst | 183 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 182 insertions(+), 1 deletion(-)

diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index 1f58a7d..0633165 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -15,11 +15,192 @@ 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: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:: /cashout
+
+   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:**
+
+   :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.
+
 Access API.
 ^^^^^^^^^^^
 
 Every endpoint is served under ``/demobanks/default/access-api``.
-See :doc:`/core/api-bank-access`.  This API offers *users management*.
+See :doc:`/core/api-bank-access`.  This API allows users to access
+their bank accounts and trigger Taler withdrawals.
 
 Integration API.
 ^^^^^^^^^^^^^^^^

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.