taler-docs

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

report-deliveries.rst (6646B)


      1 .. http:post:: [/instances/$INSTANCE]/private/report-tests
      2 
      3   Queue one test delivery. Since **v45**. Requires ``reports-write``.
      4 
      5   Send a `ReportTestRequest` with ``type`` set to ``"draft"`` or ``"scheduled"``.
      6   Both forms require a ``target_address`` for this delivery.
      7   It must be a nonempty string of printable US-ASCII characters
      8   and must not begin with a hyphen (``-``). Testing a saved schedule leaves its
      9   destination and next transmission time unchanged.
     10 
     11   :http:statuscode:`202 Accepted`:
     12     The body is a `ReportTestAccepted`.
     13     Resolve the ``Location`` header against the request URL to get the status URL.
     14     Each accepted POST requests a separate send.
     15   :http:statuscode:`400 Bad Request`:
     16     Invalid report parameters, including a missing or unknown ``type``,
     17     a ``report_serial`` in a draft, or draft settings in a scheduled test.
     18   :http:statuscode:`404 Not Found`:
     19     Unknown schedule or instance.
     20   :http:statuscode:`501 Not Implemented`:
     21     The delivery program is unconfigured.
     22 
     23   .. ts:def:: ReportTestRequest
     24 
     25     type ReportTestRequest = DraftReportTestRequest | ScheduledReportTestRequest;
     26 
     27   .. ts:def:: DraftReportTestRequest
     28 
     29     interface DraftReportTestRequest {
     30       // Use the report settings supplied in this request.
     31       type: "draft";
     32 
     33       // Description of the report to generate.
     34       description: string;
     35 
     36       // Path to the report data under this instance. Must begin with "/".
     37       data_source: string;
     38 
     39       // Media type to request from the data source, e.g. "application/pdf".
     40       mime_type: string;
     41 
     42       // Delivery program name from report_generators in GET /config.
     43       program_section: string;
     44 
     45       // Destination passed to the delivery program for this test.
     46       target_address: string;
     47     }
     48 
     49   .. ts:def:: ScheduledReportTestRequest
     50 
     51     interface ScheduledReportTestRequest {
     52       // Use the description, data source, media type and delivery program
     53       // of the saved schedule identified by report_serial.
     54       type: "scheduled";
     55 
     56       // Positive ID of the saved schedule whose report settings to use.
     57       report_serial: Integer;
     58 
     59       // Destination passed to the schedule's delivery program for this test.
     60       target_address: string;
     61     }
     62 
     63   .. ts:def:: ReportTestAccepted
     64 
     65     interface ReportTestAccepted {
     66       // ID of the queued delivery in this merchant instance's history.
     67       delivery_id: Integer;
     68     }
     69 
     70 .. http:get:: [/instances/$INSTANCE]/private/report-deliveries
     71 
     72   List scheduled and test report deliveries created in the last 30 days for
     73   this merchant instance. Each entry describes one delivery attempt using the
     74   settings in effect when it was queued. Entries remain available after the
     75   schedule is edited or deleted. Internal account, signup and KYC notifications
     76   are excluded. Since **v45**. Requires ``reports-read``.
     77 
     78   :query limit: Page size from 1 to 1024 for ascending delivery IDs, or
     79     -1024 to -1 for descending IDs. Defaults to -20 (newest first).
     80   :query offset: Exclusive delivery ID cursor from 0 to 9223372036854775807,
     81     following :ref:`row ID pagination <row-id-pagination>`.
     82   :query report_serial: Optional schedule ID from 1 to 9223372036854775807.
     83     Includes scheduled deliveries and tests of that schedule. Omit to list
     84     deliveries across the instance, including draft tests.
     85 
     86   :http:statuscode:`200 OK`:
     87     An object with a ``deliveries`` array of
     88     `ReportDelivery` objects.
     89   :http:statuscode:`400 Bad Request`:
     90     A query parameter is malformed or outside its allowed range.
     91 
     92 .. http:get:: [/instances/$INSTANCE]/private/report-deliveries/$DELIVERY_ID
     93 
     94   Look up one delivery attempt by its ``delivery_id``, a positive signed
     95   64-bit integer. Since **v45**.
     96   Requires ``reports-read``.
     97 
     98   :http:statuscode:`200 OK`:
     99     A `ReportDelivery`.
    100   :http:statuscode:`400 Bad Request`:
    101     The delivery ID is malformed or outside the allowed range.
    102   :http:statuscode:`404 Not Found`:
    103     No delivery with this ID exists in this instance's 30-day history.
    104 
    105   .. ts:def:: ReportDelivery
    106 
    107     interface ReportDelivery {
    108       // ID of this attempt within the merchant instance. Use it as the
    109       // offset when requesting the next page of delivery history.
    110       delivery_id: Integer;
    111 
    112       // ID of the saved schedule that produced this delivery or was
    113       // selected for a test. Omitted for a test sent from a draft.
    114       report_serial?: Integer;
    115 
    116       // "scheduled" for a delivery triggered by a schedule, "test" for
    117       // a delivery requested via POST /private/report-tests.
    118       origin: "scheduled" | "test";
    119 
    120       // Report description supplied to the delivery program. For a test,
    121       // the backend prepends "[Test] " to the original description.
    122       description: string;
    123 
    124       // Name of the delivery program configuration selected for this
    125       // attempt, as listed in the report_generators field of GET /config.
    126       program_section: string;
    127 
    128       // Path to the report data under the merchant instance, including
    129       // any query string, e.g. "/private/statistics-report/transactions".
    130       data_source: string;
    131 
    132       // Destination passed to the delivery program, e.g. an email
    133       // address. For a test this is the address in the test request.
    134       target_address: string;
    135 
    136       // Media type requested from the data source, e.g. "application/pdf".
    137       mime_type: string;
    138 
    139       // Time the backend queued this delivery attempt.
    140       created_at: Timestamp;
    141 
    142       // Time processing began, before the backend fetched the report.
    143       // Omitted for queued attempts and tests that expired in the queue.
    144       started_at?: Timestamp;
    145 
    146       // Time the backend recorded success or failure. Omitted until then,
    147       // even if a queued test has already expired.
    148       finished_at?: Timestamp;
    149 
    150       // "queued" means the attempt is waiting to start.
    151       // "processing" means the backend is fetching or sending the report.
    152       // "succeeded" means the delivery program exited successfully.
    153       // "failed" means report generation or delivery failed, or a test
    154       // waited 24 hours from created_at without starting.
    155       // "unknown" means processing began, but the backend cannot tell
    156       // whether the report was sent. It does not retry this attempt.
    157       status: "queued" | "processing" | "succeeded" | "failed" | "unknown";
    158 
    159       // Numeric Taler `error code <error-codes>`, present when status is
    160       // "failed". A test that expires in the queue has TALER_EC_GENERIC_TIMEOUT.
    161       error_code?: Integer;
    162 
    163       // Human-readable explanation of the failure, when available.
    164       error_detail?: string;
    165     }