[taler-docs] branch master updated (73ba6125 -> 1dd373c2)

[gnunet]

This is an automated email from the git hooks/post-receive script.

antoine pushed a change to branch master
in repository docs.

    from 73ba6125 corebank: clarify cash-in
     new 48d2a70f harmonise style
     new d09c6024 Improve corebank account API
     new 1dd373c2 Improve corebank cashout API

The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 core/api-bank-integration.rst | 12 +++++------
 core/api-bank-revenue.rst     |  4 +---
 core/api-bank-wire.rst        | 13 ++++--------
 core/api-corebank.rst         | 46 +++++++++++++++++++++----------------------
 4 files changed, 32 insertions(+), 43 deletions(-)

diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
index 4a9650dc..d5fab1ca 100644
--- a/core/api-bank-integration.rst
+++ b/core/api-bank-integration.rst
@@ -64,11 +64,11 @@ Withdrawing
 Withdrawals with a Taler-integrated bank are based on withdrawal operations.
 Some user interaction (on the bank's website or a Taler-enabled ATM) creates a
 withdrawal operation record in the bank's database.  The wallet can use a 
unique identifier
-for the withdrawal operation (the ``wopid``) to interact with the withdrawal 
operation.
+for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the 
withdrawal operation.
 
-.. http:get:: ${BANK_API_BASE_URL}/withdrawal-operation/${wopid}
+.. http:get:: /withdrawal-operation/$WITHDRAWAL_ID
 
-  Query information about a withdrawal operation, identified by the ``wopid``.
+  Query information about a withdrawal operation, identified by the 
``WITHDRAWAL_ID``.
 
   **Request:**
 
@@ -123,14 +123,13 @@ for the withdrawal operation (the ``wopid``) to interact 
with the withdrawal ope
       wire_types: string[];
     }
 
-.. http:post:: ${BANK_API_BASE_URL}/withdrawal-operation/${wopid}
+.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
 
   **Request:**
 
   .. ts:def:: BankWithdrawalOperationPostRequest
 
     interface BankWithdrawalOperationPostRequest {
-
       // Reserve public key.
       reserve_pub: string;
 
@@ -144,7 +143,7 @@ for the withdrawal operation (the ``wopid``) to interact 
with the withdrawal ope
     The bank has accepted the withdrawal operation parameters chosen by the 
wallet.
     The response is a `BankWithdrawalOperationPostResponse`.
   :http:statuscode:`404 Not found`:
-    The bank does not know about a withdrawal operation with the specified 
``wopid``.
+    The bank does not know about a withdrawal operation with the specified 
``WITHDRAWAL_ID``.
   :http:statuscode:`409 Conflict`:
     * ``TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT`` : 
       The wallet selected a different exchange or reserve public key under the 
same withdrawal ID.
@@ -157,7 +156,6 @@ for the withdrawal operation (the ``wopid``) to interact 
with the withdrawal ope
   .. ts:def:: BankWithdrawalOperationPostResponse
 
     interface BankWithdrawalOperationPostResponse {
-
       // The transfer has been confirmed and registered by the bank.
       // Does not guarantee that the funds have arrived at the exchange 
already.
       transfer_done: boolean;
diff --git a/core/api-bank-revenue.rst b/core/api-bank-revenue.rst
index 393c0ea1..05daa40b 100644
--- a/core/api-bank-revenue.rst
+++ b/core/api-bank-revenue.rst
@@ -34,7 +34,7 @@ The bank library authenticates requests to the bank merchant 
API using
 Querying the transaction history
 --------------------------------
 
-.. http:get:: ${BASE_URL}/history
+.. http:get:: /history
 
   Return a list of transactions made from an exchange to the merchant.
 
@@ -96,7 +96,6 @@ Querying the transaction history
   .. ts:def:: MerchantIncomingHistory
 
     interface MerchantIncomingHistory {
-
       // Array of incoming transactions.
       incoming_transactions : MerchantIncomingBankTransaction[];
 
@@ -111,7 +110,6 @@ Querying the transaction history
   .. ts:def:: MerchantIncomingBankTransaction
 
     interface MerchantIncomingBankTransaction {
-
       // Opaque identifier of the returned record.
       row_id: SafeUint64;
 
diff --git a/core/api-bank-wire.rst b/core/api-bank-wire.rst
index 3a196d7a..86422626 100644
--- a/core/api-bank-wire.rst
+++ b/core/api-bank-wire.rst
@@ -36,7 +36,7 @@ The bank library authenticates requests to the wire gateway 
via
 Making Transactions
 -------------------
 
-.. http:post:: ${BASE_URL}/transfer
+.. http:post:: /transfer
 
   This API allows the exchange to make a transaction, typically to a merchant. 
 The bank account
   of the exchange is not included in the request, but instead derived from the 
user name in the
@@ -91,7 +91,6 @@ Making Transactions
   .. ts:def:: TransferResponse
 
     interface TransferResponse {
-
       // Timestamp that indicates when the wire transfer will be executed.
       // In cases where the wire transfer gateway is unable to know when
       // the wire transfer will be executed, the time at which the request
@@ -111,7 +110,7 @@ Querying the transaction history
 --------------------------------
 
 
-.. http:get:: ${BASE_URL}/history/incoming
+.. http:get:: /history/incoming
 
   Return a list of transactions made from or to the exchange.
 
@@ -174,7 +173,6 @@ Querying the transaction history
   .. ts:def:: IncomingHistory
 
     interface IncomingHistory {
-
       // Array of incoming transactions.
       incoming_transactions : IncomingBankTransaction[];
 
@@ -244,7 +242,7 @@ Querying the transaction history
     }
 
 
-.. http:get:: ${BASE_URL}/history/outgoing
+.. http:get:: /history/outgoing
 
   Return a list of transactions made by the exchange, typically to a merchant.
 
@@ -303,7 +301,6 @@ Querying the transaction history
   .. ts:def:: OutgoingHistory
 
     interface OutgoingHistory {
-
       // Array of outgoing transactions.
       outgoing_transactions : OutgoingBankTransaction[];
 
@@ -318,7 +315,6 @@ Querying the transaction history
   .. ts:def:: OutgoingBankTransaction
 
     interface OutgoingBankTransaction {
-
       // Opaque identifier of the returned record.
       row_id: SafeUint64;
 
@@ -348,7 +344,7 @@ exposed by bank gateways in production.
 
 .. _twg-admin-add-incoming:
 
-.. http:post:: ${BASE_URL}/admin/add-incoming
+.. http:post:: /admin/add-incoming
 
   Simulate a transfer from a customer to the exchange.  This API is *not*
   idempotent since it's only used in testing.
@@ -391,7 +387,6 @@ exposed by bank gateways in production.
   .. ts:def:: AddIncomingResponse
 
     interface AddIncomingResponse {
-
       // Timestamp that indicates when the wire transfer will be executed.
       // In cases where the wire transfer gateway is unable to know when
       // the wire transfer will be executed, the time at which the request
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
index 81ee66b4..2b1418a6 100644
--- a/core/api-corebank.rst
+++ b/core/api-corebank.rst
@@ -216,7 +216,7 @@ Account Management
   :http:statuscode:`404 Not found`:
     The account pointed by ``$USERNAME`` was not found.
   :http:statuscode:`409 Conflict`:
-    * ``TALER_EC_BANK_RESERVED_USERNAME_CONFLICT`` : a reserved username was 
attempted, like ``admin`` or ``bank``
+    * ``TALER_EC_BANK_RESERVED_USERNAME_CONFLICT`` : a reserved username was 
attempted, like ``admin`` or ``bank``.
     * ``TALER_EC_BANK_ACCOUNT_BALANCE_NOT_ZERO``: the account balance was not 
zero.
 
 .. _account-reconfig:
@@ -230,7 +230,6 @@ Account Management
   .. ts:def:: AccountReconfiguration
 
     interface AccountReconfiguration {
-
       // Addresses where to send the TAN for transactions.
       // Currently only used for cashouts.
       // If missing, cashouts will fail.
@@ -263,11 +262,12 @@ Account Management
     Operation successful.
   :http:statuscode:`401 Unauthorized`:
     Invalid credentials or missing rights.
-  :http:statuscode:`403 Forbidden`:
-    * An admin account tried to make its account an exchange
-    * A non-admin user tried to change properties reserved for the admin
   :http:statuscode:`404 Not found`:
     The account pointed by ``$USERNAME`` was not found.
+  :http:statuscode:`409 Conflict`:
+    * ``TALER_EC_BANK_PATCH_ADMIN_EXCHANGE``: an admin user has tried to 
become an exchange.
+    * ``TALER_EC_BANK_NON_ADMIN_PATCH_LEGAL_NAME`` : a non-admin user has 
tried to change their legal name.
+    * ``TALER_EC_BANK_NON_ADMIN_PATCH_DEBT_LIMIT``: a non-admin user has tried 
to change their debt limit.
 
 
 .. _account-password-reconfig:
@@ -297,13 +297,13 @@ Account Management
     The account pointed by ``$USERNAME`` was not found.
   :http:statuscode:`401 Unauthorized`:
     Invalid credentials or missing rights.
-  :http:statuscode:`403 Forbidden`:
-    The user is not allowed to change the ``$USERNAME`` password or
-    the "old_password" field in the request doesn't match the current pasword.
+  :http:statuscode:`409 Conflict`:
+    * ``TALER_EC_BANK_NON_ADMIN_PATCH_MISSING_OLD_PASSWORD``: a non-admin user 
has tried to change their password whihout providing the current one.
+    * ``TALER_EC_BANK_PATCH_BAD_OLD_PASSWORD`` : provided old password does 
not match current password.
 
 .. _account-list:
 
-.. http:get:: ${BANK_API_BASE_URL}/public-accounts
+.. http:get:: /public-accounts
 
   Show those accounts whose histories are publicly visible.  For example,
   accounts from donation receivers.  As such, this request is unauthenticated.
@@ -447,7 +447,7 @@ Account Management
 Transactions
 ------------
 
-.. http:get:: ${BANK_API_BASE_URL}/accounts/${USERNAME}/transactions
+.. http:get:: /accounts/$USERNAME/transactions
 
   Retrieve a subset of transactions related to $USERNAME.  Without
   query parameters, it returns the last 5 transactions.
@@ -496,9 +496,9 @@ Transactions
       transactions: BankAccountTransactionInfo[];
     }
 
-.. http:get:: 
${BANK_API_BASE_URL}/accounts/${USERNAME}/transactions/${transaction_id}
+.. http:get:: /accounts/$USERNAME/transactions/$TRANSACTION_ID
 
-  Retrieve the transaction whose identifier is ``transaction_id``.
+  Retrieve the transaction whose identifier is ``TRANSACTION_ID``.
 
   **Response:**
 
@@ -523,12 +523,12 @@ Transactions
       subject: string;
 
       // Transaction unique ID.  Matches
-      // $transaction_id from the URI.
+      // $TRANSACTION_ID from the URI.
       row_id: number;
       date: Timestamp;
     }
 
-.. http:post:: ${BANK_API_BASE_URL}/accounts/${USERNAME}/transactions
+.. http:post:: /accounts/$USERNAME/transactions
 
   Create a new transaction where the bank account with the label ``USERNAME`` 
is **debited**.
 
@@ -537,7 +537,6 @@ Transactions
   .. ts:def:: BankAccountTransactionCreate
 
     interface CreateBankAccountTransactionCreate {
-
       // Address in the Payto format of the wire transfer receiver.
       // It needs at least the 'message' query string parameter.
       payto_uri: string;
@@ -568,7 +567,7 @@ Transactions
 Taler Withdrawals
 -----------------
 
-.. http:post:: ${BANK_API_BASE_URL}/accounts/${USERNAME}/withdrawals
+.. http:post:: /accounts/$USERNAME/withdrawals
 
   Create a withdrawal operation, resulting in a ``taler://withdraw`` URI.
 
@@ -604,9 +603,9 @@ Taler Withdrawals
       taler_withdraw_uri: string;
     }
 
-.. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/abort
+.. http:post:: /withdrawals/$WITHDRAWAL_ID/abort
 
-  Aborts ``withdrawal_id`` operation.  Has no effect on an already aborted
+  Aborts ``WITHDRAWAL_ID`` operation.  Has no effect on an already aborted
   operation.  Does not require further authentication as knowledge
   of the withdrawal ID serves as an authenticator.
 
@@ -619,9 +618,9 @@ Taler Withdrawals
   :http:statuscode:`409 Conflict`: 
     The withdrawal operation has been confirmed previously and can't be 
aborted.
 
-.. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/confirm
+.. http:post:: /withdrawals/$WITHDRAWAL_ID/confirm
 
-  Confirms ``withdrawal_id`` operation.  Has no effect on an already confirmed
+  Confirms ``WITHDRAWAL_ID`` operation.  Has no effect on an already confirmed
   withdrawal operation.  This call is responsible for wiring the funds to the
   exchange.  Does not require further authentication as knowledge of the
   withdrawal ID serves as an authenticator.
@@ -637,7 +636,7 @@ Taler Withdrawals
     * ``TALER_EC_BANK_CONFIRM_INCOMPLETE`` : the withdraw operation cannot be 
confirmed because no exchange and reserve public key selection happened before.
     * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient 
funds.
 
-.. http:get:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}
+.. http:get:: /withdrawals/$WITHDRAWAL_ID
 
   Query the status of a withdrawal operation. Does not require further
   authentication as knowledge of the withdrawal ID serves as an authenticator.
@@ -761,10 +760,9 @@ Cashouts
     * ``TALER_EC_BANK_BAD_CONVERSION`` : exchange rate was calculated 
incorrectly by the client.
     * ``TALER_EC_BANK_MISSING_TAN_INFO`` : the user did not share any contact 
data where to send the TAN via ``tan_channel``.
     * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient 
funds.
+    * ``TALER_EC_BANK_TAN_CHANNEL_SCRIPT_FAILED``: TAN transmition via 
``tan_channel`` failed.
   :http:statuscode:`501 Not Implemented`:
     This server does not support conversion or the chosen ``tan_channel`` is 
not currently supported.
-  :http:statuscode:`502 Bad Gateway`:
-    TAN transmition via ``tan_channel`` failed.
 
   **Details:**
 
@@ -1189,7 +1187,7 @@ 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/*
 

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.