taler-docs

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

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

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