Merge branch 'master' of git+ssh://git.taler.net/docs

1 files changed, 73 insertions, 46 deletions

diff --git a/core/api-corebank.rst b/core/api-corebank.rst
index 87c4f969..afab932c 100644
--- a/core/api-corebank.rst
+++ b/core/api-corebank.rst
@@ -1,7 +1,7 @@
 ..
   This file is part of GNU TALER.
 
-  Copyright (C) 2014-2023 Taler Systems SA
+  Copyright (C) 2014-2024 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
@@ -23,6 +23,7 @@ Taler Core Bank API
 ====================
 
 .. contents:: Table of Contents
+  :local:
 
 Introduction
 ------------
@@ -66,7 +67,7 @@ Config
 
   **Response:**
 
-  :http:statuscode:`200 OK`: 
+  :http:statuscode:`200 OK`:
     Response is a `Config`.
 
   **Details:**
@@ -82,11 +83,16 @@ Config
       // The format is "current:revision:age".
       version: string;
 
+      // Bank display name to be used in user interfaces.
+      // For consistency use "Taler Bank" if missing.
+      // @since v4, will become mandatory in the next version.
+      bank_name?: string;
+
       // If 'true' the server provides local currency conversion support
       // If 'false' some parts of the API are not supported and return 501
       allow_conversion: boolean;
 
-      // If 'true' anyone can register 
+      // If 'true' anyone can register
       // If 'false' only admin can
       allow_registrations: boolean;
 
@@ -104,7 +110,7 @@ Config
 
       // Default debt limit for newly created accounts
       default_debit_threshold: Amount;
-      
+
       // Currency used by this bank.
       currency: string;
 
@@ -113,6 +119,11 @@ Config
 
       // TAN channels supported by the server
       supported_tan_channels: TanChannel[];
+
+      // Wire transfer type supported by the bank.
+      // Default to 'iban' is missing
+      // @since v4, will become mandatory in the next version.
+      wire_type?: string;
     }
 
 
@@ -156,7 +167,7 @@ Account Management
       // Addresses where to send the TAN for protected operations.
       contact_data?: ChallengeContactData;
 
-      // 'payto' URI of a fiat bank account with a 'receiver-name' parameter.
+      // IBAN 'payto' URI of a fiat bank account with a 'receiver-name' parameter.
       // If 'receiver-name' is missing, ``name`` will be used instead.
       // Payments will be sent to this bank account
       // when the user wants to convert the regional currency
@@ -164,7 +175,8 @@ Account Management
       cashout_payto_uri?: string;
 
       // Internal payto URI of this bank account.
-      // Used mostly for testing.
+      // Used mostly for testing, this field is ignored if the bank payment
+      // method is not IBAN.
       payto_uri?: string;
 
       // If present, set the max debit allowed for this user
@@ -252,7 +264,7 @@ Account Management
       // Addresses where to send the TAN for protected operations.
       contact_data?: ChallengeContactData;
 
-      // 'payto' URI of a fiat bank account with a 'receiver-name' parameter.
+      // IBAN 'payto' URI of a fiat bank account with a 'receiver-name' parameter.
       // If 'receiver-name' is missing, ``name`` will be used instead.
       // Payments will be sent to this bank account
       // when the user wants to convert the regional currency
@@ -298,7 +310,7 @@ Account Management
 .. http:patch:: /accounts/$USERNAME/auth
 
   Allows changing the account's password.
-  
+
 
   **Request:**
 
@@ -332,13 +344,13 @@ Account Management
 
   Show those accounts whose histories are publicly visible.  For example,
   accounts from donation receivers.  As such, this request is unauthenticated.
-  
+
 
   **Request:**
 
   :query delta: *Optional.*
     Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned.  Defaults to ``-20`` to return the last 20 entries.
-  :query start: *Optional.* 
+  :query start: *Optional.*
     Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign.
   :query filter_name: *Optional.*
     Pattern to filter on the account legal name.  Given
@@ -375,6 +387,10 @@ Account Management
 
       // Is this a taler exchange account?
       is_taler_exchange: boolean;
+
+      // Opaque unique ID used for pagination.
+      // @since v4, will become mandatory in the next version.
+      row_id?: Integer;
     }
 
 .. http:get:: /accounts
@@ -388,7 +404,7 @@ Account Management
 
   :query delta: *Optional.*
     Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned.  Defaults to ``-20`` to return the last 20 entries.
-  :query start: *Optional.* 
+  :query start: *Optional.*
     Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign.
   :query filter_name: *Optional.*
     Pattern to filter on the account legal name.  Given
@@ -444,6 +460,18 @@ Account Management
 
       // Is this a taler exchange account?
       is_taler_exchange: boolean;
+
+      // Opaque unique ID used for pagination.
+      // @since v4, will become mandatory in the next version.
+      row_id?: Integer;
+
+      // Current status of the account
+      // active: the account can be used
+      // deleted: the account has been deleted but is retained for compliance 
+      // reasons, only the administrator can access it
+      // Default to 'active' is missing
+      // @since v4, will become mandatory in the next version.
+      status?: "active" | "deleted";
     }
 
 .. _bank-account-info:
@@ -487,8 +515,8 @@ Account Management
       // as well.
       contact_data?: ChallengeContactData;
 
-      // 'payto' URI pointing the bank account
-      // where to send cashouts.  This field is optional
+      // IBAN 'payto' URI with a 'receiver-name'  parameter of a fiat bank
+      // account where to send cashouts. This field is optional
       // because not all the accounts are required to participate
       // in the merchants' circuit.  One example is the exchange:
       // that never cashouts.  Registering these accounts can
@@ -531,7 +559,7 @@ Transactions
 
   :query delta: *Optional.*
     Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned.  Defaults to ``-20`` to return the last 20 entries.
-  :query start: *Optional.* 
+  :query start: *Optional.*
     Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign.
   :query long_poll_ms: Optional number to express how many milliseconds the server
     should wait for at least one result to be shown.  If not given, the server
@@ -606,6 +634,12 @@ Transactions
       // query string parameter of the 'payto' field.  In case it
       // is given in both places, the payto_uri's takes the precedence.
       amount: string;
+
+      // Nonce to make the request idempotent.  Requests with the same
+      // ``request_uid`` that differ in any of the other fields
+      // are rejected.
+      // @since v4, will become mandatory in the next version.
+      request_uid?: ShortHashCode;
     }
 
   **Response:**
@@ -624,6 +658,7 @@ Transactions
     * ``TALER_EC_BANK_SAME_ACCOUNT`` : creditor account is the same than ``USERNAME``.
     * ``TALER_EC_BANK_UNKNOWN_CREDITOR`` : creditor account was not found.
     * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds.
+    * ``TALER_EC_BANK_TRANSFER_REQUEST_UID_REUSED``: an operation with the same ``request_uid`` but different details has been submitted before.
 
   **Details:**
 
@@ -697,16 +732,16 @@ Taler Withdrawals
 
   **Response:**
 
-  :http:statuscode:`204 No content`: 
+  :http:statuscode:`204 No content`:
     The withdrawal operation has been aborted.
   :http:statuscode:`404 Not found`:
     The withdrawal operation was not found.
-  :http:statuscode:`409 Conflict`: 
+  :http:statuscode:`409 Conflict`:
     The withdrawal operation has been confirmed previously and can't be aborted.
 
 .. http:get:: /withdrawals/$WITHDRAWAL_ID
 
-  Retrieve public information about ``WITHDRAWAL_ID`` withdrawal operation.  
+  Retrieve public information about ``WITHDRAWAL_ID`` withdrawal operation.
   Does not require further authentication as knowledge of ``WITHDRAWAL_ID``
   serves as an authenticator.
 
@@ -811,7 +846,7 @@ Cashouts
 
   :http:statuscode:`200 OK`:
     The cashout request was correctly created.
-    This returns the `CashoutPending` response.
+    This returns the `CashoutResponse` response.
   :http:statuscode:`202 Accepted`:
     2FA is required for this operation. This returns the `Challenge` response.
   :http:statuscode:`404 Not found`:
@@ -878,7 +913,7 @@ Cashouts
 
   :query delta: *Optional.*
     Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned.  Defaults to ``-20`` to return the last 20 entries.
-  :query start: *Optional.* 
+  :query start: *Optional.*
     Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign.
 
   **Response:**
@@ -915,7 +950,7 @@ Cashouts
 
   :query delta: *Optional.*
     Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned.  Defaults to ``-20`` to return the last 20 entries.
-  :query start: *Optional.* 
+  :query start: *Optional.*
     Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign.
 
   .. note::
@@ -980,7 +1015,7 @@ Cashouts
       // Info of the last successful transmission of the TAN challenge.
       tan_info: string;
     }
-  
+
   .. ts:def:: Challenge
 
     interface Challenge {
@@ -988,7 +1023,7 @@ Cashouts
       // operation.
       challenge_id: string;
     }
-  
+
   .. ts:def:: TanChannel
 
     enum TanChannel {
@@ -999,7 +1034,7 @@ Cashouts
 
 .. http:post:: /accounts/$USERNAME/challenge/$CHALLENGE_ID/confirm
 
-  Solves the ``CHALLENGE_ID`` challenge and performs the protected operation.
+  Solves the ``CHALLENGE_ID`` challenge and allows performing the protected operation.
 
   When the challenge is confirmed, you can call the protected endpoint again with ``CHALLENGE_ID`` in the ``X-Challenge-Id`` HTTP header and an empty request body.
 
@@ -1025,7 +1060,7 @@ Cashouts
     * ``TALER_EC_BANK_TAN_CHALLENGE_EXPIRED`` : expired TAN.
   :http:statuscode:`429 Too many requests`:
     Too many failed confirmation attempts, a new TAN must be requested.
-  
+
 
 Monitor
 -------
@@ -1060,7 +1095,7 @@ Monitor
 
   **Response:**
 
-  :http:statuscode:`200 OK`: 
+  :http:statuscode:`200 OK`:
     The bank responds with `MonitorResponse`.
   :http:statuscode:`400 Bad Request`:
     This error may indicate that the *which* parameter is not appropriate for the selected *timeframe*.  For example, timeframe=month and which=20 would result in this error.
@@ -1073,7 +1108,7 @@ Monitor
     factors to serve different views to their users.
 
   .. ts:def:: MonitorResponse
-    
+
     // Union discriminated by the "type" field.
     type MonitorResponse =
       | MonitorNoConversion
@@ -1089,7 +1124,7 @@ Monitor
       // bank account.
       talerInCount: Integer;
 
-      // Overall volume that has been paid to a Taler 
+      // Overall volume that has been paid to a Taler
       // exchange by another bank account.
       talerInVolume: Amount;
 
@@ -1097,7 +1132,7 @@ Monitor
       // bank account.
       talerOutCount: Integer;
 
-      // Overall volume that has been paid by a Taler 
+      // Overall volume that has been paid by a Taler
       // exchange to another bank account.
       talerOutVolume: Amount;
     }
@@ -1108,7 +1143,7 @@ Monitor
     interface MonitorWithConversion {
       type: "with-conversions";
 
-      // How many cashin operations were confirmed by a 
+      // How many cashin operations were confirmed by a
       // wallet owner. Note: wallet owners
       // are NOT required to be customers of the libeufin-bank.
       cashinCount: Integer;
@@ -1136,7 +1171,7 @@ Monitor
       // bank account.
       talerInCount: Integer;
 
-      // Overall volume that has been paid to a Taler 
+      // Overall volume that has been paid to a Taler
       // exchange by another bank account.
       talerInVolume: Amount;
 
@@ -1144,14 +1179,14 @@ Monitor
       // bank account.
       talerOutCount: Integer;
 
-      // Overall volume that has been paid by a Taler 
+      // Overall volume that has been paid by a Taler
       // exchange to another bank account.
       talerOutVolume: Amount;
     }
 
 
-Taler Bank Integration API
---------------------------
+Endpoints for Integrated Sub-APIs
+---------------------------------
 
 .. http:any:: /taler-integration/*
 
@@ -1159,8 +1194,6 @@ Taler Bank Integration API
   :doc:`GNU Taler bank integration API </core/api-bank-integration>`.
   This API handles the communication with Taler wallets.
 
-Taler Wire Gateway API
-----------------------
 
 .. http:any:: /accounts/$USERNAME/taler-wire-gateway/*
 
@@ -1169,31 +1202,25 @@ Taler Wire Gateway API
 
    The endpoints are only available for accounts configured with ``is_taler_exchange=true``.
 
-Taler Revenue API
------------------
 
 .. http:any:: /accounts/$USERNAME/taler-revenue/*
 
    All endpoints under this prefix are specified
    by the :doc:`GNU Taler Revenue API </core/api-bank-revenue>`.
 
-Taler Conversion Info API
--------------------------
 
 .. http:any:: /conversion-info/*
 
    All endpoints under this prefix are specified
    by the :doc:`GNU Taler Conversion Info API </core/api-bank-conversion-info>`.
 
-EBICS Host
-----------
-
-The Taler bank can be configured to serve bank account transactions and allow
-payment initiations via the EBICS protocol.
-
-This is an optional feature, not all implementations of the API support it.
 
 .. http:post:: /ebicshost
 
    EBICS base URL.  This URL allows clients to make EBICS requests to one of
    the configured EBICS hosts.
+
+   The Taler bank can be configured to serve bank account transactions and
+   allow payment initiations via the EBICS protocol.
+
+   This is an optional feature, not all implementations of the API support it.