commit 79abb01f5c32af9ff3753ceb7e8b6da4b8180a43
parent e7d7657c5eabc47aeac23fd5f10553d27538fc59
Author: Florian Dold <dold@taler.net>
Date: Thu, 19 Nov 2026 23:22:23 +0100
merchant API: specify report test sends and delivery history
Diffstat:
2 files changed, 178 insertions(+), 3 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -29,7 +29,7 @@ Merchant Backend RESTful API
Version History
---------------
-The currently implemented protocol version is **v44**.
+The currently implemented protocol version is **v45**.
* The Android PoS app is currently targeting **v20**.
* The SPA is currently targeting **vXX**.
@@ -97,6 +97,8 @@ The currently implemented protocol version is **v44**.
:http:get:`[/instances/$INSTANCE]/private/fountains`, using the new
``fountain_serial`` response field as an exclusive cursor
+* ``v45``: adds report test sends and delivery history
+
**Upcoming versions:**
* ``vTAXES``: adds features to manage taxes
@@ -353,9 +355,11 @@ The following permissions exist:
- Locking products in the inventory
(:http:post:`[/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock`).
* - ``reports-read``
- - Listing and inspecting reports.
+ - Listing and inspecting report schedules and delivery attempts,
+ including tests sent from drafts or saved schedules.
* - ``reports-write``
- - Creating, modifying and deleting reports.
+ - Creating, modifying and deleting report schedules, and sending a test
+ report to a destination specified in the request.
* - ``statistics-read``
- Reading counter, amount and transaction statistics.
* - ``templates-read``
@@ -1221,6 +1225,12 @@ Removing scheduled reports
.. include:: merchant/delete-private-reports-REPORT_ID.rst
+Report test sends and delivery history
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. include:: merchant/report-deliveries.rst
+
+
--------------
Product groups
--------------
diff --git a/core/merchant/report-deliveries.rst b/core/merchant/report-deliveries.rst
@@ -0,0 +1,165 @@
+.. http:post:: [/instances/$INSTANCE]/private/report-tests
+
+ Queue one test delivery. Since **v45**. Requires ``reports-write``.
+
+ Send a `ReportTestRequest` with ``type`` set to ``"draft"`` or ``"scheduled"``.
+ Both forms require a ``target_address`` for this delivery.
+ It must be a nonempty string of printable US-ASCII characters
+ and must not begin with a hyphen (``-``). Testing a saved schedule leaves its
+ destination and next transmission time unchanged.
+
+ :http:statuscode:`202 Accepted`:
+ The body is a `ReportTestAccepted`.
+ Resolve the ``Location`` header against the request URL to get the status URL.
+ Each accepted POST requests a separate send.
+ :http:statuscode:`400 Bad Request`:
+ Invalid report parameters, including a missing or unknown ``type``,
+ a ``report_serial`` in a draft, or draft settings in a scheduled test.
+ :http:statuscode:`404 Not Found`:
+ Unknown schedule or instance.
+ :http:statuscode:`501 Not Implemented`:
+ The delivery program is unconfigured.
+
+ .. ts:def:: ReportTestRequest
+
+ type ReportTestRequest = DraftReportTestRequest | ScheduledReportTestRequest;
+
+ .. ts:def:: DraftReportTestRequest
+
+ interface DraftReportTestRequest {
+ // Use the report settings supplied in this request.
+ type: "draft";
+
+ // Description of the report to generate.
+ description: string;
+
+ // Path to the report data under this instance. Must begin with "/".
+ data_source: string;
+
+ // Media type to request from the data source, e.g. "application/pdf".
+ mime_type: string;
+
+ // Delivery program name from report_generators in GET /config.
+ program_section: string;
+
+ // Destination passed to the delivery program for this test.
+ target_address: string;
+ }
+
+ .. ts:def:: ScheduledReportTestRequest
+
+ interface ScheduledReportTestRequest {
+ // Use the description, data source, media type and delivery program
+ // of the saved schedule identified by report_serial.
+ type: "scheduled";
+
+ // Positive ID of the saved schedule whose report settings to use.
+ report_serial: Integer;
+
+ // Destination passed to the schedule's delivery program for this test.
+ target_address: string;
+ }
+
+ .. ts:def:: ReportTestAccepted
+
+ interface ReportTestAccepted {
+ // ID of the queued delivery in this merchant instance's history.
+ delivery_id: Integer;
+ }
+
+.. http:get:: [/instances/$INSTANCE]/private/report-deliveries
+
+ List scheduled and test report deliveries created in the last 30 days for
+ this merchant instance. Each entry describes one delivery attempt using the
+ settings in effect when it was queued. Entries remain available after the
+ schedule is edited or deleted. Internal account, signup and KYC notifications
+ are excluded. Since **v45**. Requires ``reports-read``.
+
+ :query limit: Page size from 1 to 1024 for ascending delivery IDs, or
+ -1024 to -1 for descending IDs. Defaults to -20 (newest first).
+ :query offset: Exclusive delivery ID cursor from 0 to 9223372036854775807,
+ following :ref:`row ID pagination <row-id-pagination>`.
+ :query report_serial: Optional schedule ID from 1 to 9223372036854775807.
+ Includes scheduled deliveries and tests of that schedule. Omit to list
+ deliveries across the instance, including draft tests.
+
+ :http:statuscode:`200 OK`:
+ An object with a ``deliveries`` array of
+ `ReportDelivery` objects.
+ :http:statuscode:`400 Bad Request`:
+ A query parameter is malformed or outside its allowed range.
+
+.. http:get:: [/instances/$INSTANCE]/private/report-deliveries/$DELIVERY_ID
+
+ Look up one delivery attempt by its ``delivery_id``, a positive signed
+ 64-bit integer. Since **v45**.
+ Requires ``reports-read``.
+
+ :http:statuscode:`200 OK`:
+ A `ReportDelivery`.
+ :http:statuscode:`400 Bad Request`:
+ The delivery ID is malformed or outside the allowed range.
+ :http:statuscode:`404 Not Found`:
+ No delivery with this ID exists in this instance's 30-day history.
+
+ .. ts:def:: ReportDelivery
+
+ interface ReportDelivery {
+ // ID of this attempt within the merchant instance. Use it as the
+ // offset when requesting the next page of delivery history.
+ delivery_id: Integer;
+
+ // ID of the saved schedule that produced this delivery or was
+ // selected for a test. Omitted for a test sent from a draft.
+ report_serial?: Integer;
+
+ // "scheduled" for a delivery triggered by a schedule, "test" for
+ // a delivery requested via POST /private/report-tests.
+ origin: "scheduled" | "test";
+
+ // Report description supplied to the delivery program. For a test,
+ // the backend prepends "[Test] " to the original description.
+ description: string;
+
+ // Name of the delivery program configuration selected for this
+ // attempt, as listed in the report_generators field of GET /config.
+ program_section: string;
+
+ // Path to the report data under the merchant instance, including
+ // any query string, e.g. "/private/statistics-report/transactions".
+ data_source: string;
+
+ // Destination passed to the delivery program, e.g. an email
+ // address. For a test this is the address in the test request.
+ target_address: string;
+
+ // Media type requested from the data source, e.g. "application/pdf".
+ mime_type: string;
+
+ // Time the backend queued this delivery attempt.
+ created_at: Timestamp;
+
+ // Time processing began, before the backend fetched the report.
+ // Omitted for queued attempts and tests that expired in the queue.
+ started_at?: Timestamp;
+
+ // Time the backend recorded success or failure. Omitted until then,
+ // even if a queued test has already expired.
+ finished_at?: Timestamp;
+
+ // "queued" means the attempt is waiting to start.
+ // "processing" means the backend is fetching or sending the report.
+ // "succeeded" means the delivery program exited successfully.
+ // "failed" means report generation or delivery failed, or a test
+ // waited 24 hours from created_at without starting.
+ // "unknown" means processing began, but the backend cannot tell
+ // whether the report was sent. It does not retry this attempt.
+ status: "queued" | "processing" | "succeeded" | "failed" | "unknown";
+
+ // Numeric Taler `error code <error-codes>`, present when status is
+ // "failed". A test that expires in the queue has TALER_EC_GENERIC_TIMEOUT.
+ error_code?: Integer;
+
+ // Human-readable explanation of the failure, when available.
+ error_detail?: string;
+ }