pass over nexus api, ~75%

1 files changed, 75 insertions, 31 deletions

diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index a052a35e..a5e8609f 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -196,7 +196,6 @@ Test API
 
   The successful case should respond with a ``200 OK`` and an empty JSON body.
 
-
 Bank Accounts
 -------------
 
@@ -616,6 +615,8 @@ Bank connections connect the local Nexus bank account to the bank.
 
   This type is found in the ``data`` field of `NewBankConnection <new-conn_>`_.
 
+  .. _ebics-new-conn:
+
   .. ts:def:: EbicsNewConnection
 
     interface EbicsNewConnection {
@@ -696,10 +697,25 @@ Bank connections connect the local Nexus bank account to the bank.
         details: any;
       }
 
+   For example, the following type occupies the ``details``
+   field for EBICS connections.
+
+   .. ts:def:: EbicsConnectionInfo
+
+     interface EbicsConnectionInfo {
+       ebicsUrl: string;
+       ebicsHostId: string;
+       partnerId: string;
+       userId: string;
+     }
 
 .. http:post:: {nexusBase}/bank-connections/{connId}/connect
 
-   Initialize the connection by talking to the bank.
+   Initialize the connection by talking to the bank.  For EBICS
+   connections, this endpoint causes Nexus to submit its own keys
+   and download the bank's.  That however **still** requires the
+   user to send the public keys to the bank via post, in order
+   to start operating.
 
 .. http:post:: {nexusBase}/bank-connections/{connId}/export-backup
 
@@ -708,10 +724,58 @@ Bank connections connect the local Nexus bank account to the bank.
 .. http:post:: {nexusBase}/bank-connections/{connId}/fetch-accounts
 
    Update accounts that are accessible via this bank connection.
+   After this operation, Nexus has stored the names of each bank
+   account, under ``connId``, that the bank communicated.
+
+   Note: after this operation, Nexus **still** needs to
+   `assign each bank account a local name <import-account_>`_ ,
+   in order to start operating.
+
+.. _import-account:
+
+.. http:post:: {nexusBase}/bank-connections/{connId}/import-account
+
+  Import a bank account provided by the connection into the Nexus.
+  This operation assigns a local name to one bank account that was
+  downloaded from the bank.
+
+  If no Nexus bank account with the ID ``nexusBankAccountId`` exists,
+  a new one will be created, and it will have ``connId`` as the
+  default bank connection.
+
+  If an existing local bank account with the same ID already exists,
+  this call fails if ``offeredAccountId`` and ``nexusBankAccountId``
+  have different IBANs.  Note: for each local bank account, Nexus only
+  uses its default connection and this call does NOT change the default
+  connection of the existing local bank account; in this case, it merely
+  associates ``offeredAccountId`` to ``nexusBankAccountId`` internally
+  in the database.
+
+  .. ts:def:: ImportBankAccount
+
+     interface ImportBankAccount {
+
+       // Identifier for the bank account, as returned by /accounts
+       // of the bank connection.
+       offeredAccountId: string;
+
+       // Nexus-local identifier for the bank account.
+       nexusBankAccountId: string;
+     }
+
+  **Response:**
+
+  :http:statuscode:`409 Conflict`: ``nexusBankAccountId`` exists already but
+  its IBAN is different from the one carried by ``offeredAccountId``.
 
 .. http:get:: {nexusBase}/bank-connections/{connId}/accounts
 
-   List the bank accounts that this bank connection provides access to.
+  List the bank accounts that this bank connection provides access to.
+
+  **Response:**
+
+  The response is a JSON object whose ``accounts`` field is a list of the
+  following type.
 
   .. ts:def:: OfferedBankAccount
 
@@ -731,39 +795,21 @@ Bank connections connect the local Nexus bank account to the bank.
 
        // If the account has been imported,
        // this field contains the ID of the
-       // Nexus bank account associated with it.
+       // Nexus bank account associated with it,
+       // null otherwise.
        nexusBankAccountId: string | null;
      }
 
-.. http:post:: {nexusBase}/bank-connections/{connId}/import-account
-
-  Import a bank account provided by the connection into the Nexus.
-
-  If no Nexus bank account with the ID ``nexusBankAccountId`` exists,
-  a new one will be created, and it will have ``connId`` as the
-  default bank connection.
-
-  If an existing Nexus bank account with the same ID already exists,
-  this connection will be added as an available connection for it.
-  This only succeeds if the bank account has the same IBAN.
-
-  .. ts:def:: ImportBankAccount
 
-     interface ImportBankAccount {
-
-       // Identifier for the bank account, as returned by /accounts
-       // of the bank connection.
-       offeredAccountId: string;
-
-       // Nexus-local identifier for the bank account.
-       nexusBankAccountId: string;
-     }
+.. http:get:: <nexus>/bank-connections/{connId}/messages
 
+  List *some* details of all the ISO2022 messages gotten from
+  the bank.
 
-.. http:get:: <nexus>/bank-connections/{connId}/messages
+  **Response:**
 
-  List *some* details of all the ISO2022 messages gotten from the bank.  It
-  responds with a list of the following elements:
+  The response is a JSON object whose ``bankMessages`` field
+  is a list of the following type.
 
   .. code-block:: ts
 
@@ -781,8 +827,6 @@ Bank connections connect the local Nexus bank account to the bank.
       length: number;
     }
 
-
-
 .. http:get:: <nexus>/bank-connections/{connId}/messages/{msgId}
 
   Return the ISO20022 XML corresponding to ``msgId``.