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 }