taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

get-history.rst (2759B)

      1 .. http:get:: /history
      2 
      3   Return a list of transactions made to an account.
      4 
      5   The bank account is determined via the base URL and/or the
      6   user name in the ``Authorization`` header.  In fact, the transaction history
      7   might come from a "virtual" account, where multiple real bank accounts are
      8   merged into one history.
      9 
     10   Transactions are identified by an opaque ``row_id`` numerical identifier. Its semantics (including its sorting order) are determined by the bank server and are completely opaque to the client.
     11 
     12   **Request:**
     13 
     14   :query limit: *Optional.*
     15     At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since protocol v1.
     16   :query offset: *Optional.*
     17     Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v1.
     18   :query timeout_ms: *Optional.*
     19     Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for at least one element to be shown. Only useful if *limit* is positive. Since protocol v1.
     20   :query delta: *Optional.*
     21     Deprecated in protocol **v1**. Use *limit* instead.
     22   :query start: *Optional.*
     23     Deprecated in protocol **v1**. Use *offset* instead.
     24   :query long_poll_ms: *Optional.*
     25     Deprecated in protocol **v1**. Use *timeout_ms* instead.
     26 
     27   **Response:**
     28 
     29   :http:statuscode:`200 OK`:
     30     JSON object of type `RevenueIncomingHistory`.
     31   :http:statuscode:`400 Bad request`:
     32     Request malformed. The bank replies with an `ErrorDetail` object.
     33   :http:statuscode:`401 Unauthorized`:
     34     Authentication failed, likely the credentials are wrong.
     35   :http:statuscode:`404 Not found`:
     36     The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
     37 
     38   **Details:**
     39 
     40   .. ts:def:: RevenueIncomingHistory
     41 
     42     interface RevenueIncomingHistory {
     43       // Array of incoming transactions.
     44       incoming_transactions : RevenueIncomingBankTransaction[];
     45 
     46       // Full payto URI to identify the receiver of funds.
     47       // Credit account is shared by all incoming transactions
     48       // as per the nature of the request.
     49       credit_account: string;
     50     }
     51 
     52   .. ts:def:: RevenueIncomingBankTransaction
     53 
     54     interface RevenueIncomingBankTransaction {
     55       // Opaque identifier of the returned record.
     56       row_id: SafeUint64;
     57 
     58       // Date of the transaction.
     59       date: Timestamp;
     60 
     61       // Amount received before credit_fee.
     62       amount: Amount;
     63 
     64       // Fee payed by the creditor.
     65       // If not null, creditor actually received amount - credit_fee
     66       // @since **v1**
     67       credit_fee?: Amount;
     68 
     69       // Full payto URI to identify the sender of funds.
     70       debit_account: string;
     71 
     72       // The wire transfer subject.
     73       subject: string;
     74     }