From 5f538d13b733bf45272881e818084dfe173e0c28 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Sat, 9 May 2020 12:04:42 +0200 Subject: rename file --- libeufin/api-nexus.rst | 325 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 219 insertions(+), 106 deletions(-) (limited to 'libeufin/api-nexus.rst') diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst index 745182cf..e96b6862 100644 --- a/libeufin/api-nexus.rst +++ b/libeufin/api-nexus.rst @@ -1,187 +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 ---------------- -Users are the entity that access accounts. They do not necessarily correspond -to the actual legal owner of an account. Their main purpose in the nexus is -access management. +.. http:get:: /user -.. http:get:: /users + Get information about the current user (based on the authentication information + in this request). - List users. + **Response:** - **Required permission:** Administrator. + .. ts:def:: GetUserResponse + + interface UserResponse { + + // User name + username: string; + + // Is it a superuser? + superuser: boolean; + } .. http:post:: /users - Create a new user. + Create a new user. Only the super-user can call this API. + + **Request:** - **Required permission:** Administrators. + 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:: /bank-accounts + + **Response:** - List bank accouts managed by nexus. + 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:: /bank-accounts +.. http:post:: /bank-accounts//prepared-payments/submit - List bank accouts managed by nexus. + Ask nexus to submit one prepare payment at the bank. + **Request:** -.. http:get:: /bank-accounts/{acctid}/history + .. ts:def:: SubmitPayment - :query method: Method to query the bank transaction (cached, ebics, fints, ...) + interface SubmitPayment { + // Unique identifier of the (previously) prepared payment + // to submit at the bank. + uuid: string; - Query the transaction history of an account via the specified method. + // 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:: /bank-accounts/{acctid}/payments - List payments made with this bank account via nexus. +.. http:get:: /bank-accounts//prepared-payments/$uuid + + Ask the status of payment ``$uuid``. -.. http:post:: /bank-accounts/{acctid}/payments + **Response:** - Initiate a payment. + .. ts:def:: PaymentStatus + interface PaymentStatus { -Low-level EBICS API -------------------- + // Payment unique identifier + uuid: string; -.. http:post:: /ebics/subscribers/{id}/backup - - Ask the server to export the three keys, protected with passphrase. + // True for submitted payments + submitted: boolean; - .. ts:def:: NexusEbicsBackupRequest - - interface NexusEbicsBackupRequest { - passphrase: string; - } + // Creditor IBAN + creditorIban: string; + // Creditor BIC + creditorBic: string; - .. ts:def:: NexusEbicsBackupResponse + // Creditor legal name + creditorName: string; - interface NexusEbicsBackupResponse { - - // The three passphrase-protected private keys in the PKCS#8 format + // Amount + amount: string; - authBlob: string; // base64 - encBlob: string; // base64 - sigBlob: string; // base64 - hostID: string; - userID: string; - partnerID: string; - ebicsURL: 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:: /ebics/subscribers/{id}/restoreBackup +.. http:post:: /bank-accounts//prepared-payments - Ask the server to restore the keys. Always creates a NEW - "{id}" account, and fails if it exists already. + 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 PreparedPaymentRequest { + // IBAN that will receive the payment. + iban: string; + // BIC hosting the IBAN. + bic: string; + // Legal subject that will receive the payment. + name: string; + // payment subject. + subject: 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; + } - .. ts:def:: NexusEbicsRestoreBackupRequest +.. http:post:: /bank-accounts//collected-transactions - interface NexusEbicsRestoreBackupRequest { - - // passphrase to decrypt the keys - passphrase: string; + Ask the default transport to download the latest transactions + related to ``my-acct`` and store them locally. - // The three passphrase-protected private keys in the PKCS#8 format - authBlob: string; // base64 - encBlob: string; // base64 - sigBlob: string; // base64 - hostID: string; - userID: string; - partnerID: string; - ebicsURL: string; - } + **Request:** - .. ts:def:: NexusEbicsCreateSubscriber + .. ts:def:: CollectedTransaction -.. http:post:: /ebics/subscribers + interface CollectedTransaction { + // 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; + } - Create a new subscriber. Create keys for the subscriber that - will be used in later operations. +.. http:get:: /bank-accounts//collected-transactions - .. ts:def:: NexusEbicsCreateSubscriber + Shows which transactions are stored locally at nexus. - interface NexusEbicsCreateSubscriber { - ebicsUrl: string; - hostID: string; - partnerID: string; - userID: string; - systemID: string? - } + **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 -.. http:get:: /ebics/subscribers - List EBICS subscribers managed by nexus. + **Response:** A list of `Transaction` objects. + .. ts:def:: Transaction -.. http:get:: /ebics/subscribers/{id} + interface Transaction { + // local bank account involved in the transaction. + account: string; - Get details about an EBICS subscriber. + // counterpart IBAN + counterpartIban: string; -.. http:get:: /ebics/subscriber/{id}/keyletter + // counterpart BIC + counterpartBic: string; - Get a formatted letter (mark-down) to confirm keys via ordinary mail. + // counterpart holder name + counterpartName: string; -.. http:post:: /ebics/subscriber/{id}/sendIni + // amount, in the format [-]CURRENCY:XX.YY, + // where the minus sign as prefix indicates + // a debit for the user's bank account. + amount: string + } - Send INI message to the EBICS host. +Bank Transports +--------------- -.. http:post:: /ebics/subscriber/{id}/sendHia +Bank transports connect the local LibEuFin bank account +to the real bank. - Send HIA message to the EBICS host. +.. http:post:: /bank-transports + + Activate a new bank transport for the requesting user. + + **Request:** + Object of the type `BankTransport` -.. http:get:: /ebics/subscriber/{id}/sendHtd + **Response:** - Send HTD message to the EBICS host. + :status 409 Conflict: The ``name`` field exists already for + the requesting user. -.. http:post:: /ebics/subscriber/{id}/sync + **Details:** - Synchronize with the EBICS server. Sends the HPB message - and updates the bank's keys. + .. ts:def:: BankTransport -.. http:post:: /ebics/subscriber/{id}/sendEbicsOrder + interface BankTransport { - Sends an arbitrary bank-technical EBICS order. Can be an upload - order or a download order. + // Mnemonic identifier for the transport bein created. + name: string; - .. ts:def:: NexusEbicsSendOrderRequest:: + // Optional field to restore a previous transport. + backup: TransportBackup; - interface NexusEbicsSendOrderRequest { - // Bank-technical order type, such as C54 (query transactions) - // or CCC (initiate payment) - orderType: string; + // Type of the transport (ebics, fints, native, ..) + type: string; + } - // Generic order parameters, such as a date range for querying - // an account's transaction history. - orderParams: OrderParams - // Body (XML, MT940 or whatever the bank server wants) - // of the order type, if it is an upload order - orderMessage: string; - } + .. ts:def:: TransportBackup + + interface TransportBackup { + // The information needed in this type depend entirely + // on which transport is being restored. -.. http:post:: /ebics/subscriber/{id}/ebicsOrders + } + +.. http:post:: /bank-transports//sendMSG. + + Perform the ``MSG`` operation offered by ``transport-name`` + **without** affecting the nexus database. - .. note:: + **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. - This one should be implemented last and specified better! + **Response:** - Return a list of previously sent ebics messages together with their status. - This allows retrying sending a message, if there was a crash during sending - the message. + :status 404 Not Found: ``transport-name`` doesn't exist for + the requesting user. -- cgit v1.2.3