diff options
Diffstat (limited to 'libeufin/api-nexus.rst')
| -rw-r--r-- | libeufin/api-nexus.rst | 1060 |
1 files changed, 0 insertions, 1060 deletions
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst deleted file mode 100644 index 2ec90322..00000000 --- a/libeufin/api-nexus.rst +++ /dev/null @@ -1,1060 +0,0 @@ -.. target audience: core developer - -Nexus API -########### - -.. contents:: Table of Contents - -HTTP API -======== - -In the current version, the API calls are only available to -the superuser, when no authorization condition is explictly stated. - -Configuration -------------- - - -Returns configuration values currently used by Nexus. -This call is unauthenticated. - -.. http:get:: {nexusBase}/config - - **Response:** - - .. ts:def:: ConfigResponse - - interface ConfigResponse { - - // 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. The username carried - along the HTTP basic auth points at the user to be shown. - - **Response:** - - .. ts:def:: GetUserResponse - - interface UserResponse { - - // User name - username: string; - - // Is this a super user? - superuser: Boolean; - } - -.. http:post:: {nexusBase}/users/{userName}/password - - Change password of the ``{userName}`` user. The call is - available to any superuser on any username. - - **Request:** - - .. code-block:: ts - - interface UserChangePassword { - newPassword: string; - } - - **Response:** - - :http:statuscode:`200 OK`: The password was successfully changeD. - - -.. 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 the list of all users. - - **Response:** - - .. ts:def:: UsersResponse - - interface UsersResponse { - users: UserResponse[]; - } - -.. _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. - -* ``bank-account``: A Nexus bank account, currently used in - `scheduled tasks <nexus-task_>`_ of type ``fetch`` and ``submit``. - -.. http:get:: {nexusbase}/permissions - - Lists all permissions. - - **Response** - - .. ts:def:: QueryPermissionsResponse - - interface QueryPermissionsResponse { - permissions: LibeufinPermission[]; - } - -.. http:post:: {nexusbase}/permissions - - Modifies permissions. - - **Request** - - .. ts:def:: QueryPermissionsResponse - - interface QueryPermissionsResponse { - action: "grant" | "revoke"; - permission: LibeufinPermission; - } - - **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 an empty JSON body. - -Bank Accounts -------------- - -Neuxs 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. - The list is held in the ``accounts`` field. - - .. 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``. - - .. ts:def:: BankAccountInfoWithBalance - - 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 - - Asks 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} - - Asks 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 - - Asks 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:** - - Refer to :ref:`FetchParams <fetch-params>` for - ``level`` and ``rangeType`` specifications. - - .. ts:def:: CollectedTransaction - - interface CollectedTransaction { - level: string; - rangeType: string; - // Bank connection to use. Uses the default bank connection, - // when 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:statuscode:`500 Internal Server Error`: Nexus itself had a problem - along the operation, and not the bank. - - -.. http:get:: {nexusBase}/bank-accounts/{acctid}/transactions - - Shows all the transactions fetched for ``{acctid}``. - - **Query parameters:** - - **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 to assign to the task being created. - 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 but required - // for any type of task. Whatever value "submit" tasks pass - // here, it is not going to be consumed by Nexus. Typically, - // submit tasks pass FetchParams with all of its fields set - // as null. - params: FetchParams; - } - - -.. http:get:: {nexusBase}/bank-accounts/{acctid}/schedule/{taskId} - - Shows ``taskId`` state. - - .. _nexus-task: - - **Response** - - .. ts:def:: NexusTask - - // This object is a mere reflection of - // what the Nexus database keeps to implement - // the scheduling feature. - - interface NexusTask { - // The resource being impacted by this operation. - // Typically a (Nexus) bank account being ``fetch``ed - // or whose payments are ``submit``ted. In this cases, - // this value is the "bank-account" constant. - resourceType: string; - // Name of the resource. In case of "bank-account", that - // is the name under which the bank account was imported - // from the bank. - resourceId: string; - // Task name, equals 'taskId' - taskName: string; - // Values allowed are "fetch" or "submit". - taskType: string; - // FIXME: describe. - taskCronSpec: string; - // Only meaningful for "fetch" types. - taskParams: FetchParams; - // Timestamp in secons when the next iteration will run. - nextScheduledExecutionSec: number; - // Timestamp in seconds when the previous iteration ran. - 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 - - Shows all the scheduled tasks from ``acctid``. - - **Response** - - .. ts:def:: TaskCollection - - interface TaskCollection { - - // This field can contain *multiple* objects of the type sampled below. - schedule: { - - 'task-name': { - cronspec: string; - type: "fetch" | "submit"; - params: FetchParams; - } - } - } - - -Bank Connections ----------------- - -Bank connections connect the local Nexus bank account to the 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. - - .. _new-conn: - - .. 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; - - // Strictly dependent from the connection type. - data: any; - } - - This type allows to restore a previously made bank connection. - - .. _restore-conn: - - .. ts:def:: BankConnectionRestore - - interface BankConnectionRestore { - - source: "backup"; - - // connection name. - name: string; - - // Backup data, as typically returned by the - // "../export-backup" API. - backup: any; - - passphrase?: string; - } - - The following examples show the EBICS types for creating and - restoring a connection. - - This type is found in the ``data`` field of `NewBankConnection <new-conn_>`_. - - .. _ebics-new-conn: - - .. ts:def:: EbicsNewConnection - - interface EbicsNewConnection { - userID: string, - partnerID: string, - hostID: string, - ebicsURL: string, - systemID?: string - } - - This type is found in the ``backup`` field of `BankConnectionRestore <restore-conn_>`_. - - .. ts:def:: EbicsBackup - - interface EbicsBackup { - type: string, // constant to "ebics" - userID: string, - partnerID: string, - hostID: string, - ebicsURL: string, - - // The following three values are the EBICS private keys. - authBlob: string, - encBlob: string, - sigBlob: string - } - - **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; - } - - For example, the following type occupies the ``details`` - field for EBICS connections. - - .. ts:def:: EbicsConnectionInfo - - interface EbicsConnectionInfo { - ebicsUrl: string; - ebicsHostId: string; - partnerId: string; - userId: string; - } - -.. http:post:: {nexusBase}/bank-connections/{connId}/connect - - Initialize the connection by talking to the bank. For EBICS - connections, this endpoint causes Nexus to submit its own keys - and download the bank's. That however **still** requires the - user to send the public keys to the bank via post, in order - to start operating. - -.. 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. - After this operation, Nexus has stored the names of each bank - account, under ``connId``, that the bank communicated. - - Note: after this operation, Nexus **still** needs to - `assign each bank account a local name <import-account_>`_ , - in order to start operating. - -.. _import-account: - -.. http:post:: {nexusBase}/bank-connections/{connId}/import-account - - Import a bank account provided by the connection into the Nexus. - This operation assigns a local name to one bank account that was - downloaded from the bank. - - 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 local bank account whose ID equals ``nexusBankAccountId`` - already exists, this call fails if ``offeredAccountId`` and ``nexusBankAccountId`` - have different IBANs. If instead the IBAN is the same, this call merely - associates ``offeredAccountId`` to ``nexusBankAccountId`` internally - in the database without changing ``nexusBankAccountId`` default connection. - - .. 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; - } - - **Response:** - - :http:statuscode:`409 Conflict`: ``nexusBankAccountId`` exists already but - its IBAN is different from the one carried by ``offeredAccountId``. - -.. http:get:: {nexusBase}/bank-connections/{connId}/accounts - - List the bank accounts that this bank connection provides access to. - - **Response:** - - The response is a JSON object whose ``accounts`` field is a list of the - following type. - - .. 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, - // null otherwise. - nexusBankAccountId: string | null; - } - - -.. http:get:: <nexus>/bank-connections/{connId}/messages - - List *some* details of all the ISO2022 messages gotten from - the bank. - - **Response:** - - The response is a JSON object whose ``bankMessages`` field - is a list of the following type. - - .. 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` whose name is ``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; - } - - For "taler-wire-gateway" and "anastasis" facades, - ``config`` contains the following type: - - .. ts:def:: TalerAnastasisFacadeState - - interface TalerFacadeState { - // Bank connection this facade relies on. - bankConnection: string; - // (Nexus local) bank account associated to this facade. - bankAccount: string; - // Whether the facade seeks reports or statements from the bank. - reserveTransferLevel?: string; - currency?: string; - } - -.. http:delete:: {nexus}/facades/{fcid} - - Deletes a facade. - -.. http:post:: {nexus}/facades - - Creates 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. Only the - // following type is available. - config: TalerAnastasisFacadeState; - } - -Bank Connection Protocols -------------------------- - -.. http:get:: {nexus}/bank-connection-protocols - - Lists supported bank connection protocols. - -.. http:post:: {nexus}/bank-connection-protocols/ebics/test-host - - Check if 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 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. The name comes from the use in -`Anastasis <https://www.anastasis.lu>`_. - -.. http:get:: ${BASE_URL}/history/incoming - - Returns a list of transactions made to the customer. - - Transactions are identified by a numeric identifier, - that reflects the order in which Nexus downloaded each - transaction from the bank. - - The list of returned transactions is determined by a row - ID *starting point* and a signed non-zero integer *delta*: - - * If *delta* is positive, returns 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, Nexus 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 - Nexus 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. Nexus 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. Nexus 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. - // Typically an 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; - } - -Reaching the facade -------------------- - -Once a facade with name ``fcid`` and type ``ftype`` has been -created, all its endpoints become offered by the following base -URL: - -.. code-block:: console - - $NEXUS_URL/facades/$fcid/$ftype - -For example, a ``taler-wire-gateway`` facade named ``foo`` will -offer its endpoints under - -.. code-block:: console - - https://nexus.example.com/facades/foo/taler-wire-gateway/ |