diff options
Diffstat (limited to 'libeufin/api-nexus.rst')
| -rw-r--r-- | libeufin/api-nexus.rst | 1044 |
1 files changed, 0 insertions, 1044 deletions
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst deleted file mode 100644 index 5f3e7a6c..00000000 --- a/libeufin/api-nexus.rst +++ /dev/null @@ -1,1044 +0,0 @@ -.. target audience: core developer - -Nexus API -########### - -.. contents:: Table of Contents - -HTTP API -======== - -Configuration -------------- - -Returns configuration values currently used by the Nexus process. -This API is mostly used by testing jobs. - -.. http:get:: {nexusBase}/service-config - - **Response:** - - .. ts:def:: ServiceConfigResponse - - interface ConfigResponse { - - // Connection string to the database. - dbConn: string; - } - - -Returns configuration values currently used by Nexus. - -.. http:get:: {nexusBase}/config - - **Response:** - - .. ts:def:: ConfigResponse - - interface ConfigResponse { - - currency: string; - - // nexus version, X.Y.Z format. - version: string; - } - - -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. - -User Management ---------------- - -.. http:get:: {nexusBase}/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; - - // Password - password: string; - } - -.. http:post:: {nexusBase}/users/password - - Change password of a user. The username is extracted from - the HTTP authentication parameters. - - **Request:** - - .. code-block:: ts - - interface UserChangePassword { - newPassword: string; - } - -.. http:post:: {nexusBase}/users - - Create a new user. Only a superuser can call this API. - - **Request:** - - The body is a `User` object. - - **Response:** - - :http:statuscode:`409 Conflict`: Username is not available. - - **Details:** - - .. ts:def:: User - - interface User { - - // User name - username: string; - - // Initial password - password: string; - } - - -.. http:get:: {nexusBase}/users - - Return list of users. - -.. _nexus-permissions-api: - -Permissions API ---------------- - -The permissions API manages authorization of access of subjects (usually users) -to resources. - -Permissions are modeled a set of ``(subject, resource, permission)`` triples. -Subjects and resources consist of a type and an identifier. - -Superusers are not subject to further permission checks, they are allowed -to do any operation. - -The following subject types are currently supported: - -* ``user``: An authenticated user. The subject ID - is interpreted as the user ID. - -The following permissions are currently defined: - -* ``facade.talerWireGateway.history``: Allows querying the - transaction history through a Taler wire gateway facade. -* ``facade.talerWireGateway.transfer``: Allows creating payment initiations - to transfer money via a Taler wire gateway facade. - -The following resource IDs are currently supported: - -* ``facade``: A LibEuFin facade. The resource ID is interpreted as the - facade name. - -.. http:get:: {nexusbase}/permissions - - List all permissions. - - **Response** - - .. ts:def:: QueryPermissionsResponse - - interface QueryPermissionsResponse { - permissions: { - subjectType: string; - subjectId: string; - resourceType: string; - resourceId: string; - permissionName: string - }[]; - } - -.. http:post:: {nexusbase}/permissions - - Modify permissions. - - **Request** - - .. ts:def:: QueryPermissionsResponse - - interface QueryPermissionsResponse { - action: "grant" | "revoke"; - permission: { - subjectType: string; - subjectId: string; - resourceType: string; - resourceId: string; - permissionName: string - }; - } - - **Response** - - The response is an empty JSON object. - - -Test API --------- - - -.. http:post:: {nexusbase}/bank-accounts/{acctid}/test-camt-ingestion/{type} - - This call allows tests to **directly** give Nexus a Camt document. After - the processing, all the payment(s) details should be ingested as if the - Camt came normally from a bank / the Sandbox. ``acctid`` must match the - label of a locally imported bank account, and ``type`` for now can only be - ``C53``. - - **Response** - - The successful case should respond with a ``200 OK`` and a empty JSON body. - - -Bank Accounts -------------- - -The LibEuFin maintains a copy of the bank account transaction history and balance information, -manages payment initiations of the account and tracks the initiations of payments. - -.. http:get:: {nexusBase}/bank-accounts - - **Response:** - - 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; - } - - -.. http:get:: {nexusBase}/bank-accounts/{my-acct} - - Get basic information about the bank account named ``my-acct``. - - interface BankAccountInfoWithBalance { - // ID number of the database row being the default bank connection - // of `my-acct`. - defaultBankConnection: number; - // Payto://-URI of `my-acct`. - accountPaytoUri: string; - // Balance of `my-acct` as it was downloaded from the bank - // along the last Camt document. A human-readable message - // will inform the requester, should this value not be found. - lastSeenBalance: string; - } - -.. http:post:: {nexusBase}/bank-accounts/{acctid}/payment-initiations/{pmtid}/submit - - Ask nexus to submit one prepare payment at the bank. - - :http:statuscode:`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 { - // Can be "BOOK" or "PDNG" ('pending'). - status: string; - - // Payment unique identifier - paymentInitiationId: 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 { - - // This type indicates the time range of the query. - // It can assume the following values: - // - // 'latest': retrieves the last transactions from the bank. - // If there are older unread transactions, those will *not* - // be downloaded. - // - // 'all': retrieves all the transactions from the bank, - // until the oldest. - // - // 'previous-days': currently *not* implemented, it will allow - // the request to download transactions from - // today until N days before. - // - // 'since-last': retrieves all the transactions since the last - // time one was downloaded. - // - rangeType: string; - - // Because transactions are delivered by banks in "batches", - // then every batch can have different qualities. This value - // lets the request specify which type of batch ought to be - // returned. Currently, the following two type are supported: - // - // 'report': intra-day information - // 'statement': prior day bank statement - level: string; - - // Bank connection to use. It is a *optional* value that - // defaults to the default bank connection, if not given. - bankConnection: string; - } - - **Response:** - - .. code-block:: ts - - interface NewTransactions { - // How many transactions are new to Nexus. - newTransactions: number; - // How many transactions got downloaded by the request. - // Note that a transaction can be downloaded multiple - // times but only counts as new once. - downloadedTransactions: number; - } - -.. 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 object with a unique field named ``transactions`` - that contains a list of `Transaction` objects. - - .. ts:def:: Transaction - - interface Transaction { - - // money moved by the transaction - amount: string; - - // CRDT or DBIT - creditDebitIndicator: string - - // Two of the most used values are BOOK, or PENDING - status: string; - - // FIXME - bankTransactionCode: string; - - // FIXME - valueDate: string; - - // When this payment got booked. In the form YYYY-MM-DD - bookingDate: string; - - // FIXME - accountServicerRef: string; - - // FIXME - batches: { - // list of batched transactions - batchTransactions: BatchedTransaction[]; - }; - } - - .. ts:def:: BatchedTransaction - - interface BatchedTransaction { - // FIXME - amount: string; - // FIXME - creditDebitIndicator: string; - // FIXME - details { - debtor: { - name: string; - }; - debtorAccount: { - iban: string; - }; - // Missing, when the payment is DBIT. - debtorAgent: { - bic: string; - }; - creditor: { - name: string; - }; - creditorAccount: { - iban: string; - }; - // Missing, when the payment is CRDT. - creditorAgent: { - iban: string; - }; - // FIXME - endToEndId: string; - // FIXME - unstructuredRemittanceInformation: string; - } - } - -Scheduling API --------------- - -.. http:post:: {nexusBase}/bank-accounts/{acctid}/schedule - - This endpoint allows the caller to define a recurrent - execution of a task. - - **Request** - - .. ts:def:: ScheduleTask - - interface ScheduleTask { - name: string; - - // a Unix-compatible cron pattern representing - // the frequency of execution of this task. - cronspec: string; - - // Can take values "fetch" (to download the history - // of the requester's bank account) or "submit" (to submit - // any initiated payment associated to the requester's - // bank account). - type: string; - - // Currently only used for "fetch" operations - params: { - level: "report" | "statement" | "all"; - rangeType: "latest" | "all" | "previous-days" | "since-last"; - }; - } - - - -.. http:get:: {nexusBase}/bank-accounts/{acctid}/schedule/{taskId} - - **Response** - - .. ts:def:: NexusTask - - // This object is a mere reflection of - // what the Nexus database keeps to implement - // the scheduling feature. - - interface NexusTask { - // FIXME: document all. - resourceType: string; - resourceId: string; - taskName: string; - taskType: string; - taskCronSpec: string; - taskParams: string; - nextScheduledExecutionSec: number; - prevScheduledExecutionSec: number; - } - - -.. http:delete:: {nexusBase}/bank-accounts/{acctid}/schedule/{taskId} - - This call deletes the task associated to ``taskId``. - -.. http:get:: {nexusBase}/bank-accounts/{acctid}/schedule - - **Response** - - .. code-block:: ts - - interface TaskCollection { - - // This field can contain *multiple* objects of the type sampled below. - schedule: { - - 'task-name': { - cronspec: string; - type: string; // fetch | submit - - // Depends on the type. Submit has it empty, whereas - // the fetch type includes the time range and the report - // level. - params: any; - } - } - } - - -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. - - **Request:** - - This request can accept two formats, depending on whether a - new bank connection is being made, or a connection backup is - being restored. - - - This type allows the creation of new bank accounts. - - .. ts:def:: NewBankConnection - - interface NewBankConnection { - - source: string; // only "new" allowed - - // connection name. - name: string; - - // type of the connection to make: "ebics" for example. - type: string; - - data: BankConnectionNew; - } - - This type allows to restore a previously made bank connection. - - .. ts:def:: BankConnectionRestoreRequest - - interface BankConnectionRestoreRequest { - - source: "backup"; - - // connection name. - name: string; - - // Backup data, as typically returned by the "../export-backup" API. - backup: BankConnectionBackup; - - passphrase?: string; - } - - - .. 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'. - - // 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 connection is being restored. - } - - **Response:** - - :http:statuscode:`406 Not acceptable`: a connection with the - requested name already exists for this user. - -.. http:post:: {nexusBase}/bank-connections/delete-connection - - **Request:** - - .. ts:def:: BankConnectionDeletion - - interface BankConnectionDeletion { - // label of the bank connection to delete - bankConnectionId: string; - } - -.. http:get:: {nexusBase}/bank-connections - - List available bank connections. - - **Response** - - A JSON object whose ``bankConnections`` element is a list of the following type: - - .. ts:def:: BankConnection - - interface BankConnection { - - // connection type. For example "ebics". - type: string; - - // connection name as given by the user at - // the moment of creation. - name: string; - } - - -.. http:get:: {nexusBase}/bank-connections/{connId} - - Get information about one bank connection. - - .. ts:def:: BankConnectionInfo - - interface BankConnectionInfo { - type: string; - owner: string; - // if true, this connection can be used to communicate - // with the bank. - ready: boolean; - // Depends on the type. - details: any; - } - - -.. http:post:: {nexusBase}/bank-connections/{connId}/connect - - Initialize the connection by talking to the bank. - -.. http:post:: {nexusBase}/bank-connections/{connId}/export-backup - - Make a passphrase-encrypted backup of this connection. - -.. http:post:: {nexusBase}/bank-connections/{connId}/fetch-accounts - - Update accounts that are accessible via this bank connection. - -.. http:get:: {nexusBase}/bank-connections/{connId}/accounts - - List the bank accounts that this bank connection provides access to. - - .. ts:def:: OfferedBankAccount - - interface OfferedBankAccount { - - // Unique identifier for the offered account - offeredAccountId: string; - - // IBAN of the offered account - iban: string; - - // BIC of the account's financial institution - bic: string; - - // Account owner name - ownerName: string; - - // If the account has been imported, - // this field contains the ID of the - // Nexus bank account associated with it. - nexusBankAccountId: string | null; - } - -.. http:post:: {nexusBase}/bank-connections/{connId}/import-account - - Import a bank account provided by the connection into the Nexus. - - 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. - - 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. - - .. ts:def:: ImportBankAccount - - interface ImportBankAccount { - - // Identifier for the bank account, as returned by /accounts - // of the bank connection. - offeredAccountId: string; - - // Nexus-local identifier for the bank account. - nexusBankAccountId: string; - } - - -.. http:get:: <nexus>/bank-connections/{connId}/messages - - List *some* details of all the ISO2022 messages gotten from the bank. It - responds with a list of the following elements: - - .. code-block:: ts - - interface BankMessageInfo { - - // the message type, typically how the containing layer - // (Ebics, for example) would label this information. For - // Camt.053 types, this value is "C53". - code: string; - - // the unique identifier of the message. - messageId: string; - - // bytes length of the message. - length: number; - } - - - -.. http:get:: <nexus>/bank-connections/{connId}/messages/{msgId} - - Return the ISO20022 XML corresponding to ``msgId``. - - -Facades -------- - -.. http:get:: <nexus>/facades/{fcid} - - **Response:** A `FacadeShowInfo` pointed to by ``fcid``. - - -.. http:get:: <nexus>/facades - - List available facades that belong to the requesting user. - - **Response:** A list of the following elements: - -.. ts:def:: FacadeShowInfo - - interface FacadeShowInfo { - - // Name of the facade, same as the "fcid" parameter. - name: string; - - // Type of the facade. - // For example, "taler-wire-gateway". - type: string; - - // Bas URL of the facade. - baseUrl: string; - - // details depending on the facade type. - config: any; - } - -.. http:delete:: {nexus}/facades/{fcid} - - Delete a facade. - -.. http:post:: {nexus}/facades - - Create a new facade. - - **Request:** - - .. code-block:: ts - - interface FacadeInfo { - // Name of the facade, same as the "fcid" parameter. - name: string; - - // Type of the facade. - // For example, "taler-wire-gateway" or "anastasis". - type: 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. - -Anastasis API. --------------- - -This is a read-only API offering a view over *only* the incoming -transactions of a bank account. It is named after the typical user - -a Anastasis service - but can be used in any case where only the -incoming transactions are of interest. - -.. http:get:: ${BASE_URL}/history/incoming - - Return a list of transactions made to the customer. - - The bank account of the customer is determined via the base URL and/or the - user name in the ``Authorization`` header. In fact the transaction history - might come from a "virtual" account, where multiple real bank accounts are - merged into one history. - - Transactions are identified by an opaque numeric identifier, referred to here - as *row ID*. The semantics of the row ID (including its sorting order) are - determined by the bank server and completely opaque to the client. - - The list of returned transactions is determined by a row ID *starting point* - and a signed non-zero integer *delta*: - - * If *delta* is positive, return a list of up to *delta* transactions (all matching - the filter criteria) strictly **after** the starting point. The transactions are sorted - in **ascending** order of the row ID. - * If *delta* is negative, return a list of up to *-delta* transactions (all matching - the filter criteria) strictly **before** the starting point. The transactions are sorted - in **descending** order of the row ID. - - If *starting point* is not explicitly given, it defaults to: - - * A value that is **smaller** than all other row IDs if *delta* is **positive**. - * A value that is **larger** than all other row IDs if *delta* is **negative**. - - **Request** - - :query start: *Optional.* - Row identifier to explicitly set the *starting point* of the query. - :query delta: - The *delta* value that determines the range of the query. - :query long_poll_ms: *Optional.* If this parameter is specified and the - result of the query would be empty, the bank will wait up to ``long_poll_ms`` - milliseconds for new transactions that match the query to arrive and only - then send the HTTP response. A client must never rely on this behavior, as - the bank may return a response immediately or after waiting only a fraction - of ``long_poll_ms``. - - **Response** - - :http:statuscode:`200 OK`: JSON object of type `IncomingHistory`. - :http:statuscode:`400 Bad request`: Request malformed. The bank replies with an `ErrorDetail` object. - :http:statuscode:`401 Unauthorized`: Authentication failed, likely the credentials are wrong. - :http:statuscode:`404 Not found`: The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object. - - .. ts:def:: IncomingHistory - - interface IncomingHistory { - - // Array of incoming transactions. - incoming_transactions : IncomingBankTransaction[]; - - } - - .. ts:def:: IncomingBankTransaction - - interface IncomingBankTransaction { - - // Opaque identifier of the returned record. - row_id: SafeUint64; - - // Date of the transaction. - date: Timestamp; - - // Amount transferred. - amount: Amount; - - // Payto URI to identify the receiver of funds. - // This must be one of the exchange's bank accounts. - credit_account: string; - - // Payto URI to identify the sender of funds. - debit_account: string; - - // subject of the incoming payment. - subject: string; - - } - -The anastasis facade --------------------- - -The ``anastasis`` facade has the following configuration: - - -.. ts:def:: AnastasisFacadeConfig - - interface AnastasisFacadeConfig { - // Bank account and connection that is abstracted over. - bankAccount: string; - bankConnection: string; - - currency: string; - - // Corresponds to whether we trust C52, C53 or C54 (SEPA ICT) - // for incoming transfers. - reserveTransferLevel: "statement" | "report" | "notification"; - } - -The taler-wire-gateway facade ------------------------------ - -The ``taler-wire-gateway`` facade has the following configuration: - - -.. ts:def:: TalerWireGatewayFacadeConfig - - interface TalerWireGatewayFacadeConfig { - // Bank account and connection that is - // abstracted over. - bankAccount: string; - bankConnection: string; - - currency: string; - - // Corresponds to whether we trust C52, C53 or C54 (SEPA ICT) - // for incoming transfers. - reserveTransferLevel: "statement" | "report" | "notification"; - } |