taler-docs

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

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

      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:`400 Bad request`:
     38     The request is malformed.
     39   :http:statuscode:`401 Unauthorized`:
     40     The request is unauthorized.
     41   :http:statuscode:`404 Not found`:
     42     The instance is unknown to the backend.
     43   :http:statuscode:`500 Internal Server Error`:
     44     The server experienced an internal failure.
     45     Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
     46   :http:statuscode:`406 Not acceptable`:
     47     The requested data format is not supported by the backend.
     48     Not returned with any error code.
     49   :http:statuscode:`410 Gone`:
     50     The requested statistical data is unavailable because
     51     it is not kept at the requested granularity for this long.
     52     Returned with an error code of
     53     ``TALER_EC_MERCHANT_PRIVATE_GET_STATISTICS_REPORT_GRANULARITY_UNAVAILABLE,``
     54   :http:statuscode:`501 Not implemented`:
     55     The requested functionality is not implemented.
     56     Usually returned if the PDF generator is not available
     57     at this backend and the requested format was application/pdf.
     58     Returned with an error code of
     59     ``TALER_EC_MERCHANT_GENERIC_NO_TYPST_OR_PDFTK``.
     60 
     61   **Details:**
     62 
     63   .. ts:def:: MerchantStatisticsReportResponse
     64 
     65     interface MerchantStatisticsReportResponse {
     66 
     67       // Name of the business for which the report is generated.
     68       business_name: string;
     69 
     70       // Starting date for the report.
     71       start_date: Timestamp;
     72 
     73       // End date for the report.
     74       end_date: Timestamp;
     75 
     76       // Period of time covered by each bucket (aka granularity).
     77       bucket_period: RelativeTime;
     78 
     79       // Charts to include in the report.
     80       charts: MerchantReportChart[];
     81 
     82     }
     83 
     84   .. ts:def:: MerchantReportChart
     85 
     86     interface MerchantReportChart {
     87 
     88       // Name of the chart.
     89       chart_name: string;
     90 
     91       // Label to use for the y-axis of the chart.
     92       // (x-axis is always time).
     93       y_label: string;
     94 
     95       // Statistical values for the respective time windows,
     96       // one entry per ``bucket_period`` in between ``start_date``
     97       // and ``end_date``.
     98       data_groups: BucketDataGroup[];
     99 
    100       // Human-readable labels for the ``values`` in each of the
    101       // ``data_groups``. Length of the array must match the
    102       // length of the ``values`` arrays.
    103       labels: string[];
    104 
    105       // Should the ``values`` in each of the ``data_groups``
    106       // be rendered cumulatively or using a grouped representation?
    107       cumulative: boolean;
    108 
    109     }
    110 
    111   .. ts:def:: BucketDataGroup
    112 
    113     interface BucketDataGroup {
    114 
    115       // Starting data for this group
    116       start_date: Timestamp;
    117 
    118       // Values in the data group.
    119       values: Float[];
    120 
    121     }