taler-docs

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

post-aml-OFFICER_PUB-render-form.rst (2409B)

      1 .. http:post:: /aml/$OFFICER_PUB/render-form
      2 
      3   Render a filled AML/KYC form as a PDF without storing it or associating it
      4   with an account.
      5 
      6   This endpoint was introduced in protocol **v41**.  It is available to both
      7   read-only and read-write AML officers.
      8 
      9   **Request:**
     10 
     11   *Taler-AML-Officer-Signature*:
     12     The client must provide a Base-32 encoded EdDSA signature made with
     13     ``$OFFICER_PRIV``, affirming the desire to access AML data.  This is the
     14     same query signature used by the other AML officer read endpoints; the
     15     request body is not covered by the signature.
     16 
     17   The request body must be a `CustomerKycAttributes` JSON object with a
     18   string-valued ``FORM_ID``.  ``FORM_VERSION`` describes the version of the
     19   completed form, but does not select the installed Typst package version.
     20 
     21   Before rendering, fields missing from the request are filled from the
     22   exchange's ``GLOBAL_PDF_FORM_DATA`` configuration.  Values explicitly sent
     23   by the client take precedence.  The endpoint renders only the selected form:
     24   it does not add an account cover sheet or attachments from file-valued form
     25   attributes.
     26 
     27   **Response:**
     28 
     29   :http:statuscode:`200 OK`:
     30     The response body is the rendered document with content type
     31     ``application/pdf``.
     32   :http:statuscode:`400 Bad Request`:
     33     The body is not a JSON object, ``FORM_ID`` is absent or not a string, or an
     34     HTTP authentication header is malformed.  Returned with an error code such
     35     as ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` or
     36     ``TALER_EC_GENERIC_HTTP_HEADERS_MALFORMED``.
     37   :http:statuscode:`403 Forbidden`:
     38     The signature is invalid, or the AML officer is unknown or disabled.
     39     Returned with ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_GET_SIGNATURE_INVALID``
     40     or ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_ACCESS_DENIED``.
     41   :http:statuscode:`413 Request Entity Too Large`:
     42     The request body exceeds the upload size limit.  Returned with
     43     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     44   :http:statuscode:`500 Internal Server Error`:
     45     Typst could not render the requested form, for example because the form
     46     package is unknown or required data is missing.  The response is a standard
     47     `ErrorDetail` describing the rendering failure.
     48   :http:statuscode:`501 Not Implemented`:
     49     PDF rendering is unavailable at this exchange backend.  Returned with
     50     ``TALER_EC_EXCHANGE_GENERIC_NO_TYPST_OR_PDFTK``.