commit 926532d8986adbc2bd69757781afb8b54d3946c7 parent 834b30278f265c2334099ad81d1ee51980d099be Author: Christian Grothoff <christian@grothoff.org> Date: Wed, 25 Mar 2026 22:08:28 +0100 rename for consistency Diffstat:
35 files changed, 215 insertions(+), 130 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst @@ -385,6 +385,8 @@ Setting up instances .. include:: merchant/post-management-instances-INSTANCE-auth.rst +Access control tokens +^^^^^^^^^^^^^^^^^^^^^ .. include:: merchant/post-private-token.rst @@ -866,13 +868,13 @@ Inspecting reporting schedules .. include:: merchant/get-private-reports.rst -.. include:: merchant/get-private-reports-REPORT_SERIAL.rst +.. include:: merchant/get-private-reports-REPORT_ID.rst Removing scheduled reports ^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include:: merchant/delete-private-reports-REPORT_SERIAL.rst +.. include:: merchant/delete-private-reports-REPORT_ID.rst diff --git a/core/merchant/delete-management-instances-INSTANCE.rst b/core/merchant/delete-management-instances-INSTANCE.rst @@ -37,7 +37,7 @@ the instance cannot be purged because it has successfully processed payments that have not passed the ``TAX_RECORD_EXPIRATION`` time. The latter case only applies if ``purge`` was set. - Returned with ``TALER_EC_MERCHANT_PRIVATE_DELETE_INSTANCES_PURGE_REQUIRED``. + Returned with ``TALER_EC_MERCHANT_PRIVATE_DELETE_INSTANCE_PURGE_REQUIRED``. :http:statuscode:`500 Internal Server Error`: The server experienced an internal failure. Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED`` or diff --git a/core/merchant/delete-private-groups-GROUP_ID.rst b/core/merchant/delete-private-groups-GROUP_ID.rst @@ -0,0 +1,19 @@ +.. http:delete:: [/instances/$INSTANCE]/private/groups/$GROUP_ID + + This is used to delete information about a group. + + **Required permission:** ``groups-write`` + + **Response:** + + :http:statuscode:`204 No content`: + The backend has successfully deleted the group. + :http:statuscode:`400 Bad Request`: + The group ID parameter is malformed. + Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. + :http:statuscode:`404 Not found`: + The group or the instance is unknown to the backend. + Returned with ``TALER_EC_MERCHANT_GENERIC_PRODUCT_GROUP_UNKNOWN``. + :http:statuscode:`500 Internal Server Error`: + The server experienced an internal failure. + Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``. diff --git a/core/merchant/delete-private-groups-GROUP_SERIAL.rst b/core/merchant/delete-private-groups-GROUP_SERIAL.rst @@ -1,19 +0,0 @@ -.. http:delete:: [/instances/$INSTANCES]/private/groups/$GROUP_SERIAL - - This is used to delete information about a group. - - **Required permission:** ``groups-write`` - - **Response:** - - :http:statuscode:`204 No content`: - The backend has successfully deleted the group. - :http:statuscode:`400 Bad Request`: - The group ID parameter is malformed. - Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. - :http:statuscode:`404 Not found`: - The group or the instance is unknown to the backend. - Returned with ``TALER_EC_MERCHANT_GENERIC_PRODUCT_GROUP_UNKNOWN``. - :http:statuscode:`500 Internal Server Error`: - The server experienced an internal failure. - Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``. diff --git a/core/merchant/delete-private-orders-ORDER_ID.rst b/core/merchant/delete-private-orders-ORDER_ID.rst @@ -4,6 +4,12 @@ last 10 years (or whatever ``TAX_RECORD_EXPIRATION`` is set to) or was claimed but is unpaid and thus still a valid offer. + **Request:** + + :query force: *Optional*. If set to YES, the order will be deleted + even if it was already claimed. Note that even with force, a + paid order cannot be deleted. + **Response:** :http:statuscode:`204 No content`: diff --git a/core/merchant/delete-private-pots-POT_SERIAL.rst b/core/merchant/delete-private-pots-POT_SERIAL.rst @@ -1,4 +1,4 @@ -.. http:delete:: [/instances/$INSTANCES]/private/pots/$POT_SERIAL +.. http:delete:: [/instances/$INSTANCE]/private/pots/$POT_SERIAL This is used to delete information about a pot. Existing references to the pot will simply be lost and treated as "no pot"; diff --git a/core/merchant/delete-private-reports-REPORT_ID.rst b/core/merchant/delete-private-reports-REPORT_ID.rst @@ -0,0 +1,19 @@ +.. http:delete:: [/instances/$INSTANCE]/private/reports/$REPORT_ID + + This is used to delete report generation from the schedule. + + **Required permission:** ``reports-write`` + + **Response:** + + :http:statuscode:`204 No content`: + The backend has successfully deleted the report. + :http:statuscode:`400 Bad Request`: + The report ID parameter is malformed. + Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. + :http:statuscode:`404 Not found`: + The report or the instance is unknown to the backend. + Returned with ``TALER_EC_MERCHANT_GENERIC_REPORT_UNKNOWN``. + :http:statuscode:`500 Internal Server Error`: + The server experienced an internal failure. + Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``. diff --git a/core/merchant/delete-private-reports-REPORT_SERIAL.rst b/core/merchant/delete-private-reports-REPORT_SERIAL.rst @@ -1,19 +0,0 @@ -.. http:delete:: [/instances/$INSTANCES]/private/reports/$REPORT_SERIAL - - This is used to delete report generation from the schedule. - - **Required permission:** ``reports-write`` - - **Response:** - - :http:statuscode:`204 No content`: - The backend has successfully deleted the report. - :http:statuscode:`400 Bad Request`: - The report ID parameter is malformed. - Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. - :http:statuscode:`404 Not found`: - The report or the instance is unknown to the backend. - Returned with ``TALER_EC_MERCHANT_GENERIC_REPORT_UNKNOWN``. - :http:statuscode:`500 Internal Server Error`: - The server experienced an internal failure. - Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``. diff --git a/core/merchant/delete-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst b/core/merchant/delete-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst @@ -1,4 +1,4 @@ -.. http:delete:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG +.. http:delete:: [/instances/$INSTANCE]/private/tokenfamilies/$TOKEN_FAMILY_SLUG This is used to delete a token family. Issued tokens of this family will not be spendable anymore. diff --git a/core/merchant/delete-private-webhooks-WEBHOOK_ID.rst b/core/merchant/delete-private-webhooks-WEBHOOK_ID.rst @@ -1,4 +1,4 @@ -.. http:delete:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID +.. http:delete:: [/instances/$INSTANCE]/private/webhooks/$WEBHOOK_ID This is used to delete information about a webhook. diff --git a/core/merchant/get-private-groups.rst b/core/merchant/get-private-groups.rst @@ -1,4 +1,4 @@ -.. http:get:: [/instances/$INSTANCES]/private/groups +.. http:get:: [/instances/$INSTANCE]/private/groups This is used to return all the groups that are present in our backend. diff --git a/core/merchant/get-private-pots-POT_SERIAL.rst b/core/merchant/get-private-pots-POT_SERIAL.rst @@ -1,4 +1,4 @@ -.. http:get:: [/instances/$INSTANCES]/private/pots/$POT_SERIAL +.. http:get:: [/instances/$INSTANCE]/private/pots/$POT_SERIAL This is used to obtain detailed information about specific pot. diff --git a/core/merchant/get-private-pots.rst b/core/merchant/get-private-pots.rst @@ -1,4 +1,4 @@ -.. http:get:: [/instances/$INSTANCES]/private/pots +.. http:get:: [/instances/$INSTANCE]/private/pots This is used to return all the pots that are present in our backend. diff --git a/core/merchant/get-private-reports-REPORT_ID.rst b/core/merchant/get-private-reports-REPORT_ID.rst @@ -0,0 +1,62 @@ +.. http:get:: [/instances/$INSTANCE]/private/reports/$REPORT_ID + + This is used to obtain detailed information about a specific + scheduled report. + + **Required permission:** ``reports-read`` + + **Response:** + + :http:statuscode:`200 OK`: + The backend has successfully returned the detailed information about a specific report. Returns a `ReportDetailResponse`. + :http:statuscode:`400 Bad Request`: + The report ID parameter is malformed. + Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. + :http:statuscode:`404 Not found`: + The report or instance is unknown to the backend. + :http:statuscode:`500 Internal Server Error`: + The server experienced an internal failure. + Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``. + + **Details:** + + .. ts:def:: ReportDetailResponse + + interface ReportDetailResponse { + + // Report identifier + report_serial: Integer; + + // Description of the report. Possibly included + // in the report message. + description: string; + + // Merchant backend configuration section specifying + // the program to use to transmit the report + program_section: string; + + // Mime-type to request from the data source. + mime_type: string; + + // Base URL to request the data from. + data_source: string; + + // Address where the report program should send + // the report. + target_address: string; + + // Report frequency + report_frequency: RelativeTime; + + // Report frequency shift + report_frequency_shift: RelativeTime; + + // Numeric `error code <error-codes>` unique to the + // error encountered in generating the latest report. + // Absent if there was no error. + last_error_code?: Integer; + + // Details about any error encountered + // in generating the latest report. + last_error_detail?: string; + } diff --git a/core/merchant/get-private-reports-REPORT_SERIAL.rst b/core/merchant/get-private-reports-REPORT_SERIAL.rst @@ -1,62 +0,0 @@ -.. http:get:: [/instances/$INSTANCES]/private/reports/$REPORT_SERIAL - - This is used to obtain detailed information about a specific - scheduled report. - - **Required permission:** ``reports-read`` - - **Response:** - - :http:statuscode:`200 OK`: - The backend has successfully returned the detailed information about a specific report. Returns a `ReportDetailResponse`. - :http:statuscode:`400 Bad Request`: - The report ID parameter is malformed. - Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. - :http:statuscode:`404 Not found`: - The report or instance is unknown to the backend. - :http:statuscode:`500 Internal Server Error`: - The server experienced an internal failure. - Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``. - - **Details:** - - .. ts:def:: ReportDetailResponse - - interface ReportDetailResponse { - - // Report identifier - report_serial: Integer; - - // Description of the report. Possibly included - // in the report message. - description: string; - - // Merchant backend configuration section specifying - // the program to use to transmit the report - program_section: string; - - // Mime-type to request from the data source. - mime_type: string; - - // Base URL to request the data from. - data_source: string; - - // Address where the report program should send - // the report. - target_address: string; - - // Report frequency - report_frequency: RelativeTime; - - // Report frequency shift - report_frequency_shift: RelativeTime; - - // Numeric `error code <error-codes>` unique to the - // error encountered in generating the latest report. - // Absent if there was no error. - last_error_code?: Integer; - - // Details about any error encountered - // in generating the latest report. - last_error_detail?: string; - } diff --git a/core/merchant/get-private-reports.rst b/core/merchant/get-private-reports.rst @@ -1,4 +1,4 @@ -.. http:get:: [/instances/$INSTANCES]/private/reports +.. http:get:: [/instances/$INSTANCE]/private/reports This is used to return all the scheduled reports that are present in our backend. diff --git a/core/merchant/get-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst b/core/merchant/get-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst @@ -1,4 +1,4 @@ -.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG +.. http:get:: [/instances/$INSTANCE]/private/tokenfamilies/$TOKEN_FAMILY_SLUG This is used to get detailed information about a specific token family. diff --git a/core/merchant/get-private-tokenfamilies.rst b/core/merchant/get-private-tokenfamilies.rst @@ -1,4 +1,4 @@ -.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies +.. http:get:: [/instances/$INSTANCE]/private/tokenfamilies This is used to list all configured token families for an instance. diff --git a/core/merchant/get-private-webhooks-WEBHOOK_ID.rst b/core/merchant/get-private-webhooks-WEBHOOK_ID.rst @@ -1,4 +1,4 @@ -.. http:get:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID +.. http:get:: [/instances/$INSTANCE]/private/webhooks/$WEBHOOK_ID This is used to obtain detailed information about a specific webhook. diff --git a/core/merchant/get-private-webhooks.rst b/core/merchant/get-private-webhooks.rst @@ -1,4 +1,4 @@ -.. http:get:: [/instances/$INSTANCES]/private/webhooks +.. http:get:: [/instances/$INSTANCE]/private/webhooks This is used to return all the webhooks that are present in our backend. diff --git a/core/merchant/patch-management-instances-INSTANCE.rst b/core/merchant/patch-management-instances-INSTANCE.rst @@ -26,7 +26,7 @@ This instance is unknown and thus cannot be reconfigured. :http:statuscode:`409 Conflict`: The instance configuration requires a purge before it can be changed. - Returned with ``TALER_EC_MERCHANT_PRIVATE_PATCH_INSTANCES_PURGE_REQUIRED``. + Returned with ``TALER_EC_MERCHANT_PRIVATE_PATCH_INSTANCE_PURGE_REQUIRED``. :http:statuscode:`500 Internal Server Error`: The server experienced an internal failure. Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``. diff --git a/core/merchant/patch-private-categories-CATEGORY_ID.rst b/core/merchant/patch-private-categories-CATEGORY_ID.rst @@ -7,7 +7,7 @@ **Request:** - The request is a `CategoryCreateRequest`. + The request is a `CategoryPatchRequest`. **Response:** @@ -23,3 +23,18 @@ The server experienced an internal failure. Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED`` or ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``. + + **Details:** + + .. ts:def:: CategoryPatchRequest + + interface CategoryPatchRequest { + + // Name of the category. + name: string; + + // Translations of the name into various + // languages. + name_i18n?: { [lang_tag: string]: string }; + + } diff --git a/core/merchant/patch-private-groups-GROUP_ID.rst b/core/merchant/patch-private-groups-GROUP_ID.rst @@ -1,4 +1,4 @@ -.. http:patch:: [/instances/$INSTANCES]/private/groups/$GROUP_ID +.. http:patch:: [/instances/$INSTANCE]/private/groups/$GROUP_ID This is used to update a group. @@ -6,7 +6,7 @@ **Request:** - The request body must be a `GroupAddRequest`. + The request body must be a `GroupPatchRequest`. **Response:** @@ -24,3 +24,17 @@ :http:statuscode:`500 Internal Server Error`: The server experienced an internal failure. Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``. + + **Details:** + + .. ts:def:: GroupPatchRequest + + interface GroupPatchRequest { + + // Unique name for the group (unique per instance). + group_name: string; + + // Description of the group. + description: string; + + } diff --git a/core/merchant/patch-private-orders-ORDER_ID-forget.rst b/core/merchant/patch-private-orders-ORDER_ID-forget.rst @@ -33,12 +33,16 @@ from the contract of order $ORDER_ID. :http:statuscode:`400 Bad request`: The request is malformed or one of the paths is invalid. + Returned with ``TALER_EC_MERCHANT_PRIVATE_PATCH_ORDERS_ID_FORGET_PATH_SYNTAX_INCORRECT``. :http:statuscode:`404 Not found`: The merchant backend could not find the order or the instance and thus cannot process the forget request. + Returned with ``TALER_EC_MERCHANT_GENERIC_ORDER_UNKNOWN`` + or ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``. :http:statuscode:`409 Conflict`: The request includes a field that was not marked as forgettable, so the merchant cannot delete that field. + Returned with ``TALER_EC_MERCHANT_PRIVATE_PATCH_ORDERS_ID_FORGET_PATH_NOT_FORGETTABLE``. :http:statuscode:`500 Internal Server Error`: The server experienced an internal failure. Returned with ``TALER_EC_GENERIC_DB_START_FAILED``, diff --git a/core/merchant/patch-private-pots-POT_ID.rst b/core/merchant/patch-private-pots-POT_ID.rst @@ -1,4 +1,4 @@ -.. http:patch:: [/instances/$INSTANCES]/private/pots/$POT_ID +.. http:patch:: [/instances/$INSTANCE]/private/pots/$POT_ID This is used to update a pot. diff --git a/core/merchant/patch-private-products-PRODUCT_ID.rst b/core/merchant/patch-private-products-PRODUCT_ID.rst @@ -35,11 +35,13 @@ :http:statuscode:`409 Conflict`: The provided information is inconsistent with the current state of the inventory. + Returned with ``TALER_EC_MERCHANT_PRIVATE_PATCH_PRODUCTS_TOTAL_LOST_REDUCED``, + ``TALER_EC_MERCHANT_PRIVATE_PATCH_PRODUCTS_TOTAL_SOLD_REDUCED``, or + ``TALER_EC_MERCHANT_PRIVATE_PATCH_PRODUCTS_TOTAL_STOCKED_REDUCED``. :http:statuscode:`500 Internal Server Error`: The server experienced an internal failure. Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``. - .. ts:def:: ProductPatchDetailRequest interface ProductPatchDetailRequest { diff --git a/core/merchant/patch-private-reports-REPORT_ID.rst b/core/merchant/patch-private-reports-REPORT_ID.rst @@ -1,4 +1,4 @@ -.. http:patch:: [/instances/$INSTANCES]/private/reports/$REPORT_ID +.. http:patch:: [/instances/$INSTANCE]/private/reports/$REPORT_ID This is used to update a scheduled report. @@ -6,7 +6,7 @@ **Request:** - The request body must be a `ReportAddRequest`. + The request body must be a `ReportPatchRequest`. **Response:** @@ -21,3 +21,38 @@ :http:statuscode:`500 Internal Server Error`: The server experienced an internal failure. Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``. + + + **Details:** + + .. ts:def:: ReportPatchRequest + + interface ReportPatchRequest { + + // Description of the report. Possibly included + // in the report message. + description: string; + + // Merchant backend configuration section specifying + // the program to use to transmit the report + program_section: string; + + // Mime-type to request from the data source. + mime_type: string; + + // URL under the instance to request the data from. + // Must start with '/'. The base URL and the instance + // prefix will be prefixed to the given data source. + data_source: string; + + // Address where the report program should send + // the report. + target_address: string; + + // Report frequency + report_frequency: RelativeTime; + + // Report frequency shift. Defaults to zero if missing. + report_frequency_shift?: RelativeTime; + + } diff --git a/core/merchant/patch-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst b/core/merchant/patch-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst @@ -1,4 +1,4 @@ -.. http:patch:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG +.. http:patch:: [/instances/$INSTANCE]/private/tokenfamilies/$TOKEN_FAMILY_SLUG This is used to update a token family. diff --git a/core/merchant/patch-private-webhooks-WEBHOOK_ID.rst b/core/merchant/patch-private-webhooks-WEBHOOK_ID.rst @@ -1,4 +1,4 @@ -.. http:patch:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID +.. http:patch:: [/instances/$INSTANCE]/private/webhooks/$WEBHOOK_ID This is used to update a webhook. diff --git a/core/merchant/post-private-groups.rst b/core/merchant/post-private-groups.rst @@ -1,4 +1,4 @@ -.. http:post:: [/instances/$INSTANCES]/private/groups +.. http:post:: [/instances/$INSTANCE]/private/groups This is used to create a group. diff --git a/core/merchant/post-private-pots.rst b/core/merchant/post-private-pots.rst @@ -1,4 +1,4 @@ -.. http:post:: [/instances/$INSTANCES]/private/pots +.. http:post:: [/instances/$INSTANCE]/private/pots This is used to create a pot. diff --git a/core/merchant/post-private-reports.rst b/core/merchant/post-private-reports.rst @@ -1,4 +1,4 @@ -.. http:post:: [/instances/$INSTANCES]/private/reports +.. http:post:: [/instances/$INSTANCE]/private/reports This is used to schedule the generation of periodic reports. @@ -13,10 +13,17 @@ :http:statuscode:`200 OK`: The backend has successfully added a new report. Returns a `ReportAddedResponse`. + :http:statuscode:`400 Bad request`: + Malformed JSON or missing fields. + Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. :http:statuscode:`404 Not found`: The merchant instance is unknown. + :http:statuscode:`500 Internal Server Error`: + The server experienced an internal failure. + Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``. :http:statuscode:`501 Not implemented`: The report generator specified in the ``program_section`` is not configured. + Returned with ``TALER_EC_MERCHANT_GENERIC_REPORT_GENERATOR_UNCONFIGURED``. **Details:** diff --git a/core/merchant/post-private-tokenfamilies.rst b/core/merchant/post-private-tokenfamilies.rst @@ -1,4 +1,4 @@ -.. http:post:: [/instances/$INSTANCES]/private/tokenfamilies +.. http:post:: [/instances/$INSTANCE]/private/tokenfamilies This is used to create a token family. diff --git a/core/merchant/post-private-webhooks.rst b/core/merchant/post-private-webhooks.rst @@ -1,4 +1,4 @@ -.. http:post:: [/instances/$INSTANCES]/private/webhooks +.. http:post:: [/instances/$INSTANCE]/private/webhooks This is used to create a webhook. diff --git a/core/merchant/post-templates-TEMPLATE_ID.rst b/core/merchant/post-templates-TEMPLATE_ID.rst @@ -1,4 +1,4 @@ -.. http:post:: [/instances/$INSTANCES]/templates/$TEMPLATE_ID +.. http:post:: [/instances/$INSTANCE]/templates/$TEMPLATE_ID This using template can be modified by everyone and will be used to create order.