[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: nexus API upgrade
From: |
gnunet |
Subject: |
[taler-docs] branch master updated: nexus API upgrade |
Date: |
Thu, 07 May 2020 14:40:21 +0200 |
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 a0164bc nexus API upgrade
a0164bc is described below
commit a0164bcd7c88360ccd11fecc00b4a57f61fe4d5f
Author: Marcello Stanisci <address@hidden>
AuthorDate: Thu May 7 14:38:28 2020 +0200
nexus API upgrade
---
libeufin/api-nexus2.rst | 231 ++++++++++++++++++++++++++++++++++++++++++++++++
libeufin/index.rst | 2 +-
2 files changed, 232 insertions(+), 1 deletion(-)
diff --git a/libeufin/api-nexus2.rst b/libeufin/api-nexus2.rst
new file mode 100644
index 0000000..0802cf0
--- /dev/null
+++ b/libeufin/api-nexus2.rst
@@ -0,0 +1,231 @@
+Nexus API
+###########
+
+HTTP API
+========
+
+Authentication
+--------------
+
+**Every** request made to nexus must be authenticated
+using the *HTTP basic auth* mechanism.
+
+Users Management
+----------------
+
+.. http:post:: <nexus>/users
+
+ Create a new user. Only the super-user can call this API.
+
+ **Request:**
+
+ The body is a `User` object.
+
+ **Response:**
+
+ :status 409 Conflict: Username is not available.
+
+ **Details:**
+
+ .. ts:def:: User
+
+ interface User {
+
+ // User name
+ username: string;
+
+ // Shadow password
+ shadowPassword: string;
+ }
+
+Bank Account Management
+-----------------------
+
+.. http:get:: <nexus>/bank-accounts
+
+ Return the list of bank accounts belonging to the requesting
+ user.
+
+ **Response:** A list of `BankAccount` objects.
+
+ .. ts:def:: BankAccount
+
+ interface BankAccount {
+ // mnemonic name identifying this bank account.
+ account: string;
+ // IBAN
+ iban: string;
+ // BIC
+ bic: string;
+ // Legal subject owning the account.
+ holder: string;
+ }
+
+.. http:post:: <nexus>/bank-accounts/<my-acct>/prepare-payment
+
+ Ask nexus to prepare instructions for a new payment. **The technique
+ to submit prepared payments at the bank is still work in progress!**
+ Note that ``my-acct`` is the bank account that will be **debited**
+ after this operation.
+
+.. There are (at least) two styles to specify the bank-transport
+.. to use: (1) we specify it here in a field the name of the bank-transport,
+.. or (2) we associate a ID to this prepared payment, and make another
+.. endpoint that accepts the payment's ID and the bank-transport to
+.. use for the submission. Style (2) seems more flexible.
+
+ **Request:**
+ .. ts:def:: PreparedPayment
+
+ interface PreparedPayment {
+ // IBAN that will receive the payment.
+ iban: string;
+ // BIC hosting the IBAN.
+ bic: string;
+ // Legal subject that will receive the payment.
+ name: string;
+
+ // amount, in the format CURRENCY:XX.YY
+ amount: string
+ }
+
+ **Response:**
+
+ **Details:**
+
+.. http:post:: <nexus>/bank-accounts/<my-acct>/collect-transactions
+
+ Ask the default transport to download the latest transactions
+ and store them locally.
+
+ **Request:**
+ The request body is a `CollectTransactions` JSON object.
+ ``my-acct`` is the mnemonic identifier that any bank account
+ stored locally at the nexus has. Typically, it is the real
+ bank that assigns such identifiers to the bank accounts.
+
+ **Details**
+
+ .. ts:def:: CollectTransactions
+
+ interface CollectTransactions {
+ // Optional field to specify the bank transport to
+ // use for such operation.
+ bankTransport: string;
+ // dashed date (YYYY-MM-DD) of the earliest payment
+ // in the result. Optional, defaults to "earliest
+ // possible" date.
+ start: string;
+ // dashed date (YYYY-MM-DD) of the earliest payment
+ // in the result. Optional, defaults to "latest
+ // possible" date.
+ end: string;
+ }
+
+.. http:post:: <nexus>/collected-transactions
+
+ Shows which transactions are stored locally at nexus.
+
+ **Request:**
+
+ .. ts:def:: TimeRange
+
+ interface TimeRange {
+ // start date of desired payments. Optional,
+ // defaults to "earliest possible" date.
+ start: string;
+ // end date of desired payments. Optional,
+ // defaults to "latest possible" date.
+ end: string;
+ }
+
+ **Response:** A list of `Transaction` objects.
+
+ .. ts:def:: Transaction
+
+ interface Transaction {
+ // local bank account involved in the transaction.
+ account: string;
+
+ // counterpart IBAN
+ counterpartIban: string;
+
+ // counterpart BIC
+ counterpartBic: string;
+
+ // counterpart holder name
+ counterpartName: string;
+
+ // amount, in the format [-]CURRENCY:XX.YY,
+ // where the minus sign as prefix indicates
+ // a debit for the user's bank account.
+ amount: string
+ }
+
+Bank Transports
+---------------
+
+Bank transports connect the local LibEuFin bank account
+to the real bank.
+
+.. http:post:: <nexus>/bank-transports
+
+ Activate a new bank transport for the requesting user.
+
+ **Request:**
+ Object of the type `BankTransport`
+
+ **Response:**
+
+ :status 409 Conflict: The ``name`` field exists already for
+ the requesting user.
+
+ **Details:**
+
+ .. ts:def:: BankTransport
+
+ interface BankTransport {
+
+ // Mnemonic identifier for the transport bein created.
+ name: string;
+
+ // Optional field to restore a previous transport.
+ backup: TransportBackup;
+
+ // Type of the transport (ebics, fints, native, ..)
+ type: string;
+ }
+
+
+ .. ts:def:: TransportBackup
+
+ interface TransportBackup {
+
+ // The information needed in this type depend entirely
+ // on which transport is being restored.
+
+ }
+
+.. http:post:: <nexus>/bank-transports/<transport-name>/sendMSG.
+
+ Perform the ``MSG`` operation offered by ``transport-name``
+ **without** affecting the nexus database.
+
+ **Response:**
+
+ :status 404 Not Found: ``transport-name`` doesn't exist for
+ the requesting user.
+
+.. http:post:: <nexus>/bank-transports/<transport-name>/syncMSG.
+
+ Some transports **do** have operations that aren't semantically
+ related to a bank account but need to be stored locally at the nexus.
+ One typical example is the downloading of the bank's keys vie the
+ EBICS transport. This API lets the user perform the ``MSG``
+ operation that should result in new data being stored locally
+ at the nexus.
+
+ **Response:**
+
+ :status 404 Not Found: ``transport-name`` doesn't exist for
+ the requesting user.
diff --git a/libeufin/index.rst b/libeufin/index.rst
index 9dc6268..ea3c7aa 100644
--- a/libeufin/index.rst
+++ b/libeufin/index.rst
@@ -10,5 +10,5 @@ LibEuFin is a project providing free software tooling for
European FinTech.
ebics
architecture
api-sandbox
- api-nexus
+ api-nexus2
iso20022
--
To stop receiving notification emails like this one, please contact
address@hidden.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-docs] branch master updated: nexus API upgrade,
gnunet <=