Documenting the /history API.

1 files changed, 39 insertions, 0 deletions

diff --git a/doc/taler-bank.texi b/doc/taler-bank.texi
index 0eea349..fca47b9 100644
--- a/doc/taler-bank.texi
+++ b/doc/taler-bank.texi
@@ -38,6 +38,7 @@ Texts.  A copy of the license is included in the section entitled
 @subtitle Version @value{VERSION}
 @subtitle @value{UPDATED}
 @author Florian Dold (@email{florian.dold@@inria.fr})
+@author Marcello Stanisci (@email{marcello.stanisci@@inria.fr})
 @page
 @vskip 0pt plus 1filll
 @insertcopying
@@ -203,6 +204,44 @@ However, the bank will define two additional values for this API: @code{executio
 (a operation's timestamp), and @code{transfer_details} (just a "seed" to make unique the
 operation).  See @url{https://docs.taler.net/api/api-exchange.html#administrative-api-bank-transactions}.
 
+The polling mechanism is possbile thanks to the @code{/history} API provided
+by the bank.  The exchange will periodically use this API to see if it has
+received new wire transfers; upon receiving a new wire transfer, the exchange
+will automatically create a reserve and allow the money sender to withdraw.
+
+@table @code
+
+@item GET /history
+Ask the bank to return a list of money transactions related to a caller's
+bank account.
+
+@itemize
+
+@item @code{auth} a string indicating the authentication method to use;
+only @code{"basic"} value is accepted so far. The username and password
+credentials have to be sent along the HTTP request headers.  Namely, the
+bank will look for the following two headers: @code{X-Taler-Bank-Username}
+and @code{X-Taler-Bank-Password}, which will contain those plain text credentials.
+
+@item @code{delta} returns the first @code{N} records younger (older) than @code{start}
+if @code{+N} (@code{-N}) is specified.
+
+@item @code{start} according to delta, only those records with row id
+strictly greater (lesser) than start will be returned. This argument is
+optional; if not given, delta youngest records will be returned.
+
+@item @code{direction} optional argument taking values debit or credit,
+according to the caller willing to receive both incoming and outgoing,
+only outgoing, or only incoming records
+
+@item @code{account_number} optional argument indicating the bank account
+number whose history is to be returned. If not given, then the history of
+the calling user will be returned
+
+@end itemize
+
+@end table
+
 
 @subsection Exchange pays merchant