diff options
Diffstat (limited to 'libeufin/api-nexus.rst')
| -rw-r--r-- | libeufin/api-nexus.rst | 567 |
1 files changed, 458 insertions, 109 deletions
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst index 745182cf..d58b43bd 100644 --- a/libeufin/api-nexus.rst +++ b/libeufin/api-nexus.rst @@ -1,187 +1,536 @@ Nexus API ########### +.. contents:: Table of Contents HTTP API ======== -Users Management ----------------- +Authentication +-------------- -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. +Currently every request made to nexus must be authenticated using the *HTTP +basic auth* mechanism. -.. http:get:: <nexus>/users +Other authentication mechanisms (e.g. OpenID Connect) might +be supported in the future. - List users. +User Management +--------------- - **Required permission:** Administrator. +.. http:get:: {nexusBase}/user -.. http:post:: <nexus>/users + Get information about the current user (based on the authentication information + in this request). - Create a new user. + **Response:** - **Required permission:** Administrators. + .. ts:def:: GetUserResponse + interface UserResponse { -Bank Account Management ------------------------ + // User name + username: string; -.. http:get:: <nexus>/bank-accounts + // Is it a superuser? + superuser: boolean; + } - List bank accouts managed by nexus. +.. http:post:: {nexusBase}/users + Create a new user. Only a superuser can call this API. -.. http:post:: <nexus>/bank-accounts + **Request:** - List bank accouts managed by nexus. + The body is a `User` object. + **Response:** -.. http:get:: <nexus>/bank-accounts/{acctid}/history + :status 409 Conflict: Username is not available. - :query method: Method to query the bank transaction (cached, ebics, fints, ...) + **Details:** - Query the transaction history of an account via the specified method. + .. ts:def:: User + interface User { -.. http:get:: <nexus>/bank-accounts/{acctid}/payments + // User name + username: string; - List payments made with this bank account via nexus. + // Initial password + password: string; + } -.. http:post:: <nexus>/bank-accounts/{acctid}/payments - Initiate a payment. +.. http:get:: {nexusBase}/users + Return list of users. -Low-level EBICS API -------------------- +Bank Accounts +------------- -.. http:post:: <nexus>/ebics/subscribers/{id}/backup +The LibEuFin maintains a copy of the bank account transaction history and balance information, +manages payment initiations of the account and tracks the of payment initiations. + +.. http:get:: {nexusBase}/bank-accounts - Ask the server to export the three keys, protected with passphrase. + **Response:** - .. ts:def:: NexusEbicsBackupRequest - - interface NexusEbicsBackupRequest { - passphrase: string; - } + A list of `BankAccount` objects + that belong to the requester. + .. ts:def:: BankAccount + + interface BankAccount { + // mnemonic name identifying this bank account. + nexusBankAccountId: string; + // IBAN + iban: string; + // BIC + bic: string; + // Legal subject owning the account. + ownerName: string; + } - .. ts:def:: NexusEbicsBackupResponse +.. http:post:: {nexusBase}/bank-accounts/{acctid}/payment-initiations/{pmtid}/submit - interface NexusEbicsBackupResponse { - - // The three passphrase-protected private keys in the PKCS#8 format + Ask nexus to submit one prepare payment at the bank. + + :status 404 Not Found: the unique identifier **or** + the bank connection could not be found in the system + + +.. http:get:: {nexus}/bank-accounts/{my-acct}/payment-initiations/{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; + + // Subject + subject: string; + + // Date of submission (in dashed form YYYY-MM-DD) + submissionDate: string; + + // Date of preparation (in dashed form YYYY-MM-DD) + preparationDate: string; + } + +.. http:get:: {nexusBase}/bank-accounts/{my-acct}/payment-initiations + + Ask nexus the list of initiated payments. At this stage of the API, + **all** is returned: submitted and non submitted payments. + + **Response** + + .. ts:def:: InitiatedPayments + + interface InitiatedPayments { + + // list of all the initiated payments' UID. + initiatedPayments: PaymentStatus[]; + } + + +.. http:post:: {nexusBase}/bank-accounts/{my-acct}/payment-initiations + + 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; + } + +.. http:post:: {nexusBase}/bank-accounts/{acctid}/fetch-transactions + + Nexus will download bank transactions using the given connection. + + **Request:** + + .. ts:def:: CollectedTransaction + + interface CollectedTransaction { + // Optional field to specify the bank connection to + // use for such operation. + bankConnection?: 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:: {nexusBase}/bank-accounts/{acctid}/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; + + // Dashed date YYYY-MM(01-12)-DD(01-31) of the transaction. + date: string; + + // Payment subject. + subject: string; + } + + +Bank Connections +---------------- + +Bank connections connect the local LibEuFin bank account +to the real bank. + +.. http:post:: <nexus>/bank-connections + + Activate a new bank connection for the requesting user. - authBlob: string; // base64 - encBlob: string; // base64 - sigBlob: string; // base64 - hostID: string; - userID: string; - partnerID: string; - ebicsURL: string; - } + **Request:** + .. ts:def:: BankConnectionRestoreRequest -.. http:post:: <nexus>/ebics/subscribers/{id}/restoreBackup + interface BankConnectionRestoreRequest { + + source: "new" | "backup"; + + name: string; + + // Restore a previous connection. Take precedence + // over the 'new' field. + backup?: BankConnectionBackup; + + passphrase?: string; + + // Data to create a fresh bank connection without + // restoring any backup. + data?: BankConnectionNew; + } + + + .. ts:def:: BankConnectionNew + + interface BankConnectionNew { + + // This type is strictly dependent on + // the connection being created. For Ebics, + // it will contain the required fields (as strings): + // 'ebicsURL', 'userID', 'partnerID', 'hostID', and + // the optional 'systemID'. - Ask the server to restore the keys. Always creates a NEW - "{id}" account, and fails if it exists already. + // Other connection types, like 'local' (used for testing + // purposes skipping any interaction with the bank service) + // and 'fints' are all work in progress! + + } + + + .. ts:def:: BankConnectionBackup + + interface BankConnectionBackup { + + // The information needed in this type depend entirely + // on which connectionis being restored. + + } + + **Response:** + + :status 409 Conflict: The ``name`` field exists already for + the requesting user. - .. ts:def:: NexusEbicsRestoreBackupRequest +.. http:post:: {nexusBase}/bank-connections/delete-connection - interface NexusEbicsRestoreBackupRequest { + **Request:** + + .. ts:def:: BankConnectionDeletion + + interface BankConnectionDeletion { + // label of the bank connection to delete + bankConnectionId: string; + } + +.. http:get:: {nexusBase}/bank-connections + + List available bank connections. + + +.. http:get:: {nexusBase}/bank-connections/{connId} + + Get information about one bank connection. + + .. ts:def:: BankConnectionInfo - // passphrase to decrypt the keys - passphrase: string; + interface BankConnectionInfo { + bankConnectionId: string; + + bankConnectionType: string; + + // Is this bank connection ready, or + // are we waiting for the bank to activate + // the connection? + ready: boolean; + + // Did the user review the bank's keys? + bankKeysReviewed: boolean; + } + + +.. http:post:: {nexusBase}/bank-connections/{connId}/connect + + Initialize the connection by talking to the bank. - // 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; - } +.. http:post:: {nexusBase}/bank-connections/{connId}/export-backup - .. ts:def:: NexusEbicsCreateSubscriber + Make a passphrase-encrypted backup of this connection. -.. http:post:: <nexus>/ebics/subscribers +.. http:post:: {nexusBase}/bank-connections/{connId}/fetch-accounts - Create a new subscriber. Create keys for the subscriber that - will be used in later operations. + Update accounts that are accessible via this bank connection. - .. ts:def:: NexusEbicsCreateSubscriber +.. http:get:: {nexusBase}/bank-connections/{connId}/accounts - interface NexusEbicsCreateSubscriber { - ebicsUrl: string; - hostID: string; - partnerID: string; - userID: string; - systemID: string? - } + List the bank accounts that this bank connection provides access to. + .. ts:def:: OfferedBankAccount -.. http:get:: <nexus>/ebics/subscribers + interface OfferedBankAccount { - List EBICS subscribers managed by nexus. + // Unique identifier for the offered account + offeredAccountId: string; + // IBAN of the offered account + iban: string; -.. http:get:: <nexus>/ebics/subscribers/{id} + // BIC of the account's financial institution + bic: string; - Get details about an EBICS subscriber. + // Account owner name + ownerName: string; -.. http:get:: <nexus>/ebics/subscriber/{id}/keyletter + // If the account has been imported, + // this field contains the ID of the + // Nexus bank account associated with it. + nexusBankAccountId: string | null; + } - Get a formatted letter (mark-down) to confirm keys via ordinary mail. +.. http:post:: {nexusBase}/bank-connections/{connId}/import-account -.. http:post:: <nexus>/ebics/subscriber/{id}/sendIni + Import a bank account provided by the connection into the Nexus. - Send INI message to the EBICS host. + 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. -.. http:post:: <nexus>/ebics/subscriber/{id}/sendHia + 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. - Send HIA message to the EBICS host. + .. ts:def:: ImportBankAccount -.. http:get:: <nexus>/ebics/subscriber/{id}/sendHtd + interface ImportBankAccount { - Send HTD message to the EBICS host. + // Identifier for the bank account, as returned by /accounts + // of the bank connection. + offeredAccountId: string; -.. http:post:: <nexus>/ebics/subscriber/{id}/sync + // Nexus-local identifier for the bank account. + nexusBankAccountId: string; + } - Synchronize with the EBICS server. Sends the HPB message - and updates the bank's keys. +Facades +------- -.. http:post:: <nexus>/ebics/subscriber/{id}/sendEbicsOrder +.. http:get:: <nexus>/facades - Sends an arbitrary bank-technical EBICS order. Can be an upload - order or a download order. + List available facades. - .. ts:def:: NexusEbicsSendOrderRequest:: +.. http:post:: {nexus}/facades + + Create a new facade; it requires a `FacadeInfo` as the request's body. + +.. http:get:: {nexus}/facades/${fcid} + + Get details about a facade. + + .. ts:def:: FacadeInfo + + interface FacadeInfo { + // Name of the facade, same as the "fcid" parameter. + name: string; + + // Type of the facade. + // For example, "taler-wire-gateway". + type: string; + + // Name of the user that created the facade. + // Whenever the facade accesses a resource it is allowed to + // access, the creator must *also* have access to that resource. + creator: string; + + // Bank accounts that the facade has read/write + // access to. + bankAccountsRead: string[]; + bankAccountsWrite: string[]; + + // Bank connections that the facade has read/write + // access to. + bankConnectionsRead: string[]; + bankConnectionsWrite: string[]; + + // Facade-specific configuration details. + config: any; + } + + +Bank Connection Protocols +------------------------- + +.. http:get:: {nexus}/bank-connection-protocols + + List supported bank connection protocols. + +.. http:post:: {nexus}/bank-connection-protocols/ebics/test-host + + Check if the nexus can talk to an EBICS host. + This doesn't create a new connection in the database, + and is useful during setup when the user hasn't entered + the full details for the connection yet. + + .. ts:def:: EbicsHostTestRequest + + interface EbicsHostTestRequest { + ebicsBaseUrl: string; + ebicsHostId: string; + } + + +EBICS-specific APIs +------------------- + +The following endpoints are only available for EBICS bank connections. +They are namespaced under the ``/ebics/`` sub-resource. + +.. http:post:: {nexusBase}/bank-connections/{connection-name}/ebics/download/{msg} + + .. warning:: + + Use with care. Typically only necessary for testing and debugging. + + Perform an EBICS download transaction of type ``msg``. + This request will not affect any bank account or other state + in the nexus database. It will just make a request to the bank + and return the answer. + +.. http:post:: {nexusBase}/bank-connections/{connection-name}/ebics/upload/{msg} + + .. warning:: + + Use with care. Typically only necessary for testing and debugging. + + Perform an EBICS upload transaction of type ``msg``. + This request will not affect any bank account or other state + in the nexus database. It will just make a request to the bank + and return the answer. - interface NexusEbicsSendOrderRequest { - // Bank-technical order type, such as C54 (query transactions) - // or CCC (initiate payment) - orderType: string; - // Generic order parameters, such as a date range for querying - // an account's transaction history. - orderParams: OrderParams +The taler-wire-gateway facade +----------------------------- - // Body (XML, MT940 or whatever the bank server wants) - // of the order type, if it is an upload order - orderMessage: string; - } +The ``taler-wire-gateway`` facade has the following configuration: -.. http:post:: <nexus>/ebics/subscriber/{id}/ebicsOrders +.. ts:def:: TalerWireGatewayFacadeConfig + + interface TalerWireGatewayFacadeConfig { + // Bank account and connection that is + // abstracted over. + bankAccount: string; + bankConnection: string; - .. note:: + // Corresponds to whether we trust C52, C53 or C54 (SEPA ICT) + // for incoming transfers. + reserveTransferLevel: "statement" | "report" | "notification"; - This one should be implemented last and specified better! + // Time between incremental requests + intervalIncremental: string; - 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. + // FIXME: maybe more scheduling parameters? + } |