taler-docs

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

get-private-statistics-report-NAME.rst (4148B)

      1 .. http:get:: [/instances/$INSTANCE]/private/statistics-report/$NAME
      2 .. http:get:: /management/instances/$INSTANCE/statistics-report/$NAME
      3 
      4   This request generates a specific report based on ``$NAME``. The backend
      5   **MAY** support generating the report in various formats.  The currently
      6   implemented value is:
      7 
      8     * "transactions" (total revenue, total refunds, fees
      9       as well as number of transactions), since **v25**
     10 
     11   Reserved names for upcoming report implementations are:
     12 
     13     * "money-pots" (changes to totals in money pots),
     14     * "taxes" (amount of taxes withheld by tax class), planned for
     15       **vTAXES**,
     16     * "sales-funnel" (number and volume of orders
     17       created, claimed, paid, refunded and settled).
     18 
     19   The overall endpoint family exists since protocol **v25**.
     20 
     21   **Required permission:** ``statistics-read`` (see :ref:`Scopes <merchant-api-scopes>`)
     22 
     23   **Request:**
     24 
     25   *Accept*:
     26     The client may specify the desired MIME-type for the result.
     27     Supported are the usual "application/json", but also
     28     "application/pdf".
     29 
     30     :query granularity: *Optional*. Determines the bucket granularity
     31                         to return. Accepted are "hour", "day", "week",
     32                         "month", "quarter" and "year". Defaults to "month".
     33     :query count: *Optional*. Number of buckets to return. Defaults depends
     34                         on the granularity.
     35 
     36   **Response:**
     37 
     38   :http:statuscode:`200 Ok`:
     39     If JSON is requested, the body will be
     40     a `MerchantStatisticsReportResponse`, otherwise a PDF.
     41   :http:statuscode:`400 Bad request`:
     42     The request is malformed.
     43   :http:statuscode:`401 Unauthorized`:
     44     The request is unauthorized.
     45   :http:statuscode:`404 Not found`:
     46     The instance is unknown to the backend.
     47   :http:statuscode:`500 Internal Server Error`:
     48     The server experienced an internal failure.
     49     Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
     50   :http:statuscode:`406 Not acceptable`:
     51     The requested data format is not supported by the backend.
     52     Not returned with any error code.
     53   :http:statuscode:`410 Gone`:
     54     The requested statistical data is unavailable because
     55     it is not kept at the requested granularity for this long.
     56     Returned with an error code of
     57     ``TALER_EC_MERCHANT_PRIVATE_GET_STATISTICS_REPORT_GRANULARITY_UNAVAILABLE``.
     58   :http:statuscode:`501 Not implemented`:
     59     The requested functionality is not implemented.
     60     Usually returned if the PDF generator is not available
     61     at this backend and the requested format was application/pdf.
     62     Returned with an error code of
     63     ``TALER_EC_MERCHANT_GENERIC_NO_TYPST_OR_PDFTK``.
     64 
     65   **Details:**
     66 
     67   .. ts:def:: MerchantStatisticsReportResponse
     68 
     69     interface MerchantStatisticsReportResponse {
     70 
     71       // Name of the business for which the report is generated.
     72       business_name: string;
     73 
     74       // Starting date for the report.
     75       start_date: Timestamp;
     76 
     77       // End date for the report.
     78       end_date: Timestamp;
     79 
     80       // Period of time covered by each bucket (aka granularity).
     81       bucket_period: RelativeTime;
     82 
     83       // Charts to include in the report.
     84       charts: MerchantReportChart[];
     85 
     86     }
     87 
     88   .. ts:def:: MerchantReportChart
     89 
     90     interface MerchantReportChart {
     91 
     92       // Name of the chart.
     93       chart_name: string;
     94 
     95       // Label to use for the y-axis of the chart.
     96       // (x-axis is always time).
     97       y_label: string;
     98 
     99       // Statistical values for the respective time windows,
    100       // one entry per ``bucket_period`` in between ``start_date``
    101       // and ``end_date``.
    102       data_groups: BucketDataGroup[];
    103 
    104       // Human-readable labels for the ``values`` in each of the
    105       // ``data_groups``. Length of the array must match the
    106       // length of the ``values`` arrays.
    107       labels: string[];
    108 
    109       // Should the ``values`` in each of the ``data_groups``
    110       // be rendered cumulatively or using a grouped representation?
    111       cumulative: boolean;
    112 
    113     }
    114 
    115   .. ts:def:: BucketDataGroup
    116 
    117     interface BucketDataGroup {
    118 
    119       // Starting data for this group
    120       start_date: Timestamp;
    121 
    122       // Values in the data group.
    123       values: Float[];
    124 
    125     }