diff options
author | Christian Grothoff <christian@grothoff.org> | 2020-05-09 17:50:39 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2020-05-09 17:50:39 +0200 |
commit | 864be019f75faad33b76c534459498c5eede7b83 (patch) | |
tree | 43d050871bd7c4fb35ff4b4dbc6ea1beabbe29e8 /libeufin/api-nexus2.rst | |
parent | 38df5382734bcf4de85c0f65e27a1b8800594ad9 (diff) | |
parent | 9224d72693bc53336103ed1f8294372fb8648682 (diff) | |
download | docs-864be019f75faad33b76c534459498c5eede7b83.tar.gz docs-864be019f75faad33b76c534459498c5eede7b83.tar.bz2 docs-864be019f75faad33b76c534459498c5eede7b83.zip |
Merge branch 'master' of git+ssh://git.taler.net/docs
Diffstat (limited to 'libeufin/api-nexus2.rst')
-rw-r--r-- | libeufin/api-nexus2.rst | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/libeufin/api-nexus2.rst b/libeufin/api-nexus2.rst new file mode 100644 index 00000000..2cd0b2eb --- /dev/null +++ b/libeufin/api-nexus2.rst @@ -0,0 +1,300 @@ +Nexus API +########### + +HTTP API +======== + +Authentication +-------------- + +Currently every request made to nexus must be authenticated using the *HTTP +basic auth* mechanism. + +Other authentication mechanisms (e.g. OpenID Connect) might +be supported in the future. + +Users Management +---------------- + +.. http:get:: <nexus>/user + + Get information about the current user (based on the authentication information + in this request). + + **Response:** + + .. ts:def:: GetUserResponse + + interface UserResponse { + + // User name + username: string; + + // Is it a superuser? + superuser: boolean; + } + +.. 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:: CreateUserRequest + + interface User { + + // User name + username: string; + + // Initial password + password: string; + } + +Bank Account Management +----------------------- + +.. http:get:: <nexus>/bank-accounts + + **Response:** + + A list of `BankAccount` objects + that belong to the requester. + + .. 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>/prepared-payments/submit + + Ask nexus to submit one prepare payment at the bank. + + **Request:** + + .. ts:def:: SubmitPayment + + interface SubmitPayment { + // Unique identifier of the (previously) prepared payment + // to submit at the bank. + uuid: string; + + // Optional field to specify the bank transport to use + // for the submission. + transport: string; + } + + :status 404 Not Found: the unique identifier **or** + the bank transport could not be found in the system + + +.. http:get:: <nexus>/bank-accounts/<my-acct>/prepared-payments/$uuid + + Ask the status of payment ``$uuid``. + + **Response:** + + .. ts:def:: PaymentStatus + + interface PaymentStatus { + + // Payment unique identifier + uuid: string; + + // True for submitted payments + submitted: boolean; + + // Creditor IBAN + creditorIban: string; + + // Creditor BIC + creditorBic: string; + + // Creditor legal name + creditorName: string; + + // Amount + amount: string; + + // Date of submission (in dashed form YYYY-MM-DD) + submissionDate: string; + + // Date of preparation (in dashed form YYYY-MM-DD) + preparationDate: string; + } + +.. http:post:: <nexus>/bank-accounts/<my-acct>/prepared-payments + + Ask nexus to prepare instructions for a new payment. + Note that ``my-acct`` is the bank account that will be + **debited** after this operation. + + **Request:** + + .. ts:def:: PreparedPaymentRequest + + 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:** + + .. ts:def:: PreparedPaymentResponse + + interface PreparedPaymentResponse { + + // Opaque identifier to be communicated when + // the user wants to submit the payment to the + // bank. + uuid: string; + } + +.. http:post:: <nexus>/bank-accounts/<my-acct>/collected-transactions + + Ask the default transport to download the latest transactions + related to ``my-acct`` and store them locally. + + **Request:** + + .. 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:get:: <nexus>/bank-accounts/<my-acct>/collected-transactions + + Shows which transactions are stored locally at nexus. + + **Query parameters:** + + * **start** start (dashed YYYY-MM-DD) date of desired payments. + Optional, defaults to "earliest possible" date + * **end** end (dashed YYYY-MM-DD) date of desired payments. + Optional, defaults to "earliest possible" date + + + **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. |