From a0164bcd7c88360ccd11fecc00b4a57f61fe4d5f Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Thu, 7 May 2020 14:38:28 +0200 Subject: nexus API upgrade --- libeufin/api-nexus2.rst | 231 ++++++++++++++++++++++++++++++++++++++++++++++++ libeufin/index.rst | 2 +- 2 files changed, 232 insertions(+), 1 deletion(-) create mode 100644 libeufin/api-nexus2.rst diff --git a/libeufin/api-nexus2.rst b/libeufin/api-nexus2.rst new file mode 100644 index 00000000..0802cf07 --- /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:: /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:: /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:: /bank-accounts//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:: /bank-accounts//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:: /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:: /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:: /bank-transports//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:: /bank-transports//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 9dc62685..ea3c7aa3 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 -- cgit v1.2.3