taler-docs

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

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:
Mcore/api-merchant.rst | 16+++++++++++++---
Acore/merchant/report-deliveries.rst | 165+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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; + }