commit f8cdd80a42209f37b031530148cec9f50629754a
parent 86c4ddf831b1274c3174c826b443df8f40f9db96
Author: Florian Dold <dold@taler.net>
Date: Mon, 31 Aug 2026 22:39:46 +0200
exchange API: document AML form PDF rendering
Diffstat:
2 files changed, 56 insertions(+), 2 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -30,11 +30,11 @@ defines all specific terms used in this section.
Version History
---------------
-The currently implemented protocol version is **v40**.
+The currently implemented protocol version is **v41**.
* Wallet-core is currently targeting **vXX**.
* The merchant is currently targeting **v34**.
-* The AML SPA is currently targeting **v40**.
+* The AML SPA is currently targeting **v41**.
* The KYC SPA is currently targeting **v30**.
**Version history:**
@@ -54,6 +54,8 @@ The currently implemented protocol version is **v40**.
:http:get:`/transfers/$WTID </transfers/$WTID>`
* ``v40``: adds :http:get:`/aml/$OFFICER_PUB </aml/$OFFICER_PUB>` to report
the authenticated AML officer's name and access level
+* ``v41``: adds :http:post:`/aml/$OFFICER_PUB/render-form </aml/$OFFICER_PUB/render-form>`
+ to preview filled AML/KYC forms as PDF
**Upcoming versions:**
@@ -571,6 +573,8 @@ and freeze or unfreeze accounts suspected of money laundering.
.. include:: exchange/get-aml-OFFICER_PUB-attributes-H_NORMALIZED_PAYTO.rst
+.. include:: exchange/post-aml-OFFICER_PUB-render-form.rst
+
.. include:: exchange/post-aml-OFFICER_PUB-decision.rst
.. include:: exchange/get-aml-OFFICER_PUB-transfers-credit.rst
diff --git a/core/exchange/post-aml-OFFICER_PUB-render-form.rst b/core/exchange/post-aml-OFFICER_PUB-render-form.rst
@@ -0,0 +1,50 @@
+.. http:post:: /aml/$OFFICER_PUB/render-form
+
+ Render a filled AML/KYC form as a PDF without storing it or associating it
+ with an account.
+
+ This endpoint was introduced in protocol **v41**. It is available to both
+ read-only and read-write AML officers.
+
+ **Request:**
+
+ *Taler-AML-Officer-Signature*:
+ The client must provide a Base-32 encoded EdDSA signature made with
+ ``$OFFICER_PRIV``, affirming the desire to access AML data. This is the
+ same query signature used by the other AML officer read endpoints; the
+ request body is not covered by the signature.
+
+ The request body must be a `CustomerKycAttributes` JSON object with a
+ string-valued ``FORM_ID``. ``FORM_VERSION`` describes the version of the
+ completed form, but does not select the installed Typst package version.
+
+ Before rendering, fields missing from the request are filled from the
+ exchange's ``GLOBAL_PDF_FORM_DATA`` configuration. Values explicitly sent
+ by the client take precedence. The endpoint renders only the selected form:
+ it does not add an account cover sheet or attachments from file-valued form
+ attributes.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The response body is the rendered document with content type
+ ``application/pdf``.
+ :http:statuscode:`400 Bad Request`:
+ The body is not a JSON object, ``FORM_ID`` is absent or not a string, or an
+ HTTP authentication header is malformed. Returned with an error code such
+ as ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` or
+ ``TALER_EC_GENERIC_HTTP_HEADERS_MALFORMED``.
+ :http:statuscode:`403 Forbidden`:
+ The signature is invalid, or the AML officer is unknown or disabled.
+ Returned with ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_GET_SIGNATURE_INVALID``
+ or ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_ACCESS_DENIED``.
+ :http:statuscode:`413 Request Entity Too Large`:
+ The request body exceeds the upload size limit. Returned with
+ ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
+ :http:statuscode:`500 Internal Server Error`:
+ Typst could not render the requested form, for example because the form
+ package is unknown or required data is missing. The response is a standard
+ `ErrorDetail` describing the rendering failure.
+ :http:statuscode:`501 Not Implemented`:
+ PDF rendering is unavailable at this exchange backend. Returned with
+ ``TALER_EC_EXCHANGE_GENERIC_NO_TYPST_OR_PDFTK``.
