taler-docs

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

get-aml-OFFICER_PUB-attributes-H_NORMALIZED_PAYTO.rst (4469B)

      1 .. http:get:: /aml/$OFFICER_PUB/attributes/$H_NORMALIZED_PAYTO
      2 
      3   Obtain attributes obtained as part of AML/KYC processes for a
      4   given account.
      5 
      6   This endpoint was introduced in protocol **v20**.
      7 
      8   **Request:**
      9 
     10   *Accept*:
     11     The client may specify the desired MIME-type for the result.
     12     Supported are the usual "application/json", but also
     13     "application/pdf".
     14 
     15   *Taler-AML-Officer-Signature*:
     16     The client must provide Base-32 encoded EdDSA signature with
     17     ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that
     18     this is merely a simple authentication mechanism, the details of the
     19     request are not protected by the signature.
     20 
     21   :query limit:
     22     *Optional*. takes value of the form ``N (-N)``, so that at
     23     most ``N`` values strictly older (younger) than ``start`` are returned.
     24     Defaults to ``-20`` to return the last 20 entries (before ``start``).
     25   :query offset:
     26     *Optional*. Row number threshold, see ``delta`` for its
     27     interpretation.  Defaults to ``INT64_MAX``, namely the biggest row id
     28     possible in the database.
     29 
     30   **Response:**
     31 
     32   :http:statuscode:`200 OK`:
     33     The responds will be an `KycAttributesResponse` message.
     34   :http:statuscode:`204 No content`:
     35     There are no matching KYC attributes.
     36   :http:statuscode:`400 Bad Request`:
     37     The request is malformed. Cases include:
     38     - The ``$H_NORMALIZED_PAYTO`` or ``H_OFFICER_PUB`` path segment
     39       is malformed.
     40       This response comes with a standard `ErrorDetail` response with
     41       a code of ``TALER_EC_GENERIC_PATH_SEGMENT_MALFORMED``.
     42     - The required HTTP header with the signature is missing. Returned with
     43       ``TALER_EC_GENERIC_HTTP_HEADERS_MALFORMED``.
     44   :http:statuscode:`403 Forbidden`:
     45     Two cases:
     46     - The signature is invalid. Returned with a code of
     47       ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_GET_SIGNATURE_INVALID``.
     48     - The specific officer is unknown or disabled. Returned with a code of
     49       ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_ACCESS_DENIED``.
     50   :http:statuscode:`404 Not found`:
     51     The target account is unknown to the exchange.
     52     This response comes with a standard `ErrorDetail` response with
     53     a code of ``TALER_EC_EXCHANGE_GENERIC_TARGET_ACCOUNT_UNKNOWN``.
     54   :http:statuscode:`406 Not Acceptable`:
     55     The requested MIME type for the response is not supported.
     56     This response comes with a standard `ErrorDetail` response with
     57     a code of ``TALER_EC_GENERIC_REQUESTED_FORMAT_UNSUPPORTED``.
     58   :http:statuscode:`500 Internal server error`:
     59     The server had an internal problem handling the request.
     60     The error code is usually a ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
     61   :http:statuscode:`501 Not implemented`:
     62     The requested functionality is not implemented.
     63     Usually returned if the PDF generator is not available
     64     at this backend and the requested format was application/pdf.
     65     This response comes with a standard `ErrorDetail` response with
     66     a code of ``TALER_EC_EXCHANGE_GENERIC_NO_TYPST_OR_PDFTK``.
     67 
     68   .. ts:def:: KycAttributesResponse
     69 
     70     interface KycAttributesResponse {
     71 
     72       // Matching KYC attribute history of the account.
     73       details: KycAttributeCollectionEvent[];
     74 
     75     }
     76 
     77   .. ts:def:: KycAttributeCollectionEvent
     78 
     79     interface KycAttributeCollectionEvent {
     80 
     81       // Row ID of the record.  Used to filter by offset.
     82       rowid: Integer;
     83 
     84       // True if the attributes were filed by an AML officer,
     85       // otherwise they were provided directly by the customer.
     86       by_aml_officer: boolean;
     87 
     88       // The collected KYC data.  NULL if the attribute data could not
     89       // be decrypted (internal error of the exchange, likely the
     90       // attribute key was changed).
     91       attributes?: CustomerKycAttributes;
     92 
     93       // Time when the KYC data was collected
     94       collection_time: Timestamp;
     95 
     96     }
     97 
     98   .. ts:def:: CustomerKycAttributes
     99 
    100     interface CustomerKycAttributes {
    101 
    102       // ID of the Form that was used to submit the attributes and/or
    103       // that should be used to *render* the attributes.
    104       // Mandatory since **v31**.
    105       FORM_ID: string;
    106 
    107       // Version of the form completed by the user.
    108       FORM_VERSION?: Integer;
    109 
    110       // High entropy value used in forms where hash is going to be stored in
    111       // plain text.
    112       FORM?_SALT: string;
    113 
    114       // Attributes can have basically arbitrary additional
    115       // Key-value pairs. See the
    116       // gnu-taler-form-attributes registry in GANA
    117       // for possible keys!
    118 
    119     }