taler-docs

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

post-kyc-bulk-EXTERN_PUB.rst (4491B)

      1 .. http:post:: /kyc-bulk/$EXTERN_PUB
      2 
      3   The ``/kyc-import/$EXTERN_PUB`` POST endpoint allows third parties to
      4   upload **large** KYC/KYB attachments.
      5   The ``$EXTERN_PUB`` is the public EdDSA key
      6   identifying the 3rd party encoded using Crockford base32 encoding.
      7 
      8   Clients should repeat this request (with some backoff) until it
      9   succeeds. The request is idempotent, so repeating it is always safe.
     10   The request may also be performed repeatedly for the same customer
     11   data (payto:// and/or account public key) with the same or different
     12   bulk data, for example to provide additional bulk data.
     13 
     14   See `KycBulkUploadAttribute` for how to reference bulk data
     15   in KYC/KYB attributes.
     16 
     17   This endpoint was introduced in protocol **vIMPORT**.
     18 
     19   **Request:**
     20 
     21   The request body must be of one of the following file types:
     22 
     23   - application/pdf
     24   - audio/
     25   - image/
     26   - video/
     27   - application/zip, containing PDF, audio/, image/ or
     28     video/-files inside
     29 
     30 
     31   The following HTTP headers must be provided:
     32 
     33   *Taler-Extern-Signature*:
     34     $EXTERN_SIG`` where ``$EXTERN_SIG`` is the Crockford base32-encoded EdDSA
     35     signature of purpose ``TALER_SIGNATURE_EXTERN_BULK_UPLOAD``
     36     and be made over the purpose header and the
     37     SHA512 hash over the body and the SHA512 hash of the payto URI.
     38     While the data will be timestamped server-side the client signature
     39     does not include the timestamp.
     40     See :ref:`ExternKycDataBulkBindingsPS <TALER_ExternKycDataBulkBindingPS>` for details.
     41 
     42   *Taler-Customer-Payto*:
     43     payto:// URL of the bank account (or wallet) of the customer the bulk
     44     data is about.
     45 
     46   *If-Not-Match*:
     47     Crockford base32-encoded SHA-512 hash over the body to be uploaded.
     48     Used by the server to prevent the upload if the data is already known.
     49 
     50   *Content-Length*:
     51     Standard HTTP header with number of bytes in the body of the upload.
     52     Required so that the server can perform sanity-checking early on.
     53 
     54   *Content-Type*:
     55     Mime-type of the body.
     56     Required so that the server can remember it for future use.
     57 
     58 
     59   **Response:**
     60 
     61   :http:statuscode:`204 No Content`:
     62     The information was successfully uploaded.
     63   :http:statuscode:`400 Bad Request`:
     64     The request body is malformed or a parameter is invalid.
     65     This response comes with a standard `ErrorDetail` response with
     66     a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     67     The client should not repeat the request until its has been
     68     restarted (presumably with a fixed implementation).
     69   :http:statuscode:`403 Forbidden`:
     70     The provided signature is invalid for the request.
     71     This response comes with a standard `ErrorDetail` response with
     72     a code of ``TALER_EC_KYC_BULK_SIGNATURE_INVALID``.
     73     The client should not repeat the request until its has been
     74     restarted (presumably with a fixed implementation).
     75   :http:statuscode:`404 Not Found`:
     76     The ``$EXTERN_PUB`` is unknown to the exchange.
     77     This response comes with a standard `ErrorDetail` response.
     78     Possible error codes include
     79     ``TALER_EC_EXCHANGE_KYC_IMPORT_3RD_PARTY_UNKNOWN`` or
     80     ``TALER_EC_GENERIC_ENDPOINT_UNKNOWN``.
     81     The client should not repeat the request until its has been
     82     restarted (presumably with a new configuration).
     83   :http:statuscode:`411 Length required`:
     84     The client must specify the ``Content-length`` header before
     85     attempting upload.  While technically optional by the
     86     HTTP specification, the service may require
     87     the client to provide the length upfront.
     88   :http:statuscode:`412 Precondition failed`:
     89     The information was already present server-side (If-Not-Match
     90     condition failed).  The client should not try again.
     91   :http:statuscode:`413 Request Entity Too Large`:
     92     The body is too large. This failure should be logged on both
     93     ends. The request should not be repeated. If the uploaded
     94     resource is a ZIP file with multiple files in it
     95     the client MAY try to break up the upload into
     96     multiple smaller POST requests.
     97   :http:statuscode:`500 Internal Server Error`:
     98     The server experienced an internal error.
     99     This response comes with a standard `ErrorDetail` response.
    100     Possible error codes include
    101     ``TALER_EC_GENERIC_DB_STORE_FAILED``,
    102     ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``,
    103     ``TALER_EC_GENERIC_DB_SETUP_FAILED``, or
    104     ``TALER_EC_EXCHANGE_KYC_GENERIC_AML_LOGIC_BUG``.
    105     The request should be repeated with some exponential back-off,
    106     giving the server operator to address its internal issues.