kuantaz-api-client

 

KzCaptcha - Python API Client

This library offers the API client to communicate with kuantaz to verify a submission.

Description

This Python library lets you connect to a kuantaz installation and verify the submitted data.

Installation

Install using pip

Install this library by using pip:

pip install kuantaz-api-client

Usage

• Create a project in your kuantaz installation
• Include the kuantaz script in your form

<div id="kuantaz-box"></div>

<script src="https://[URL]/build/kuantaz-frontend.js" defer></script>
<script>
  var kz;
  window.onload = function () {
    kz = new kzCaptcha("kuantaz-box", "https://[URL]", "[UUID]", "[PUBLIC_KEY]");
  };
</script>

• Include the library in your project

pip install kuantaz-api-client

• After the form is submitted, verify the data before processing it

from kuantaz_api_client import Client

api_client = Client(host, public_key, private_key)

your_post_data = {}  # This needs to be filled with the post data

kuantaz_submit_token = your_post_data['_kuantaz_submitToken']
kuantaz_validation_token = your_post_data['_kuantaz_validationToken']

result = api_client.verify_submission(your_post_data, kuantaz_submit_token, kuantaz_validation_token)

if result.is_submittable():
    # Send the email or process the data
    pass
else:
    # Show error message
    pass

API Documentation

Client

Client initialization

Create a new client object to use the API client.

from kuantaz_api_client import Client

api_client = Client(host, public_key, private_key, verify_ssl)

Parameter	Type	Description
host	str	The host of the kuantaz installation
public_key	str	The public key of the kuantaz project
private_key	str	The private key of the kuantaz project
verify_ssl	bool	Set to False if the SSL certificate should not be verified.

Verify form data

To verify the form data, call verify_submission with the form data in an array and the submit and validation tokens, which kuantaz generated on the form initialization and the form data validation. The method will return a VerificationResult object.

result = api_client.verify_submission(form_data, kuantaz_submit_token, kuantaz_validation_token)

Parameter	Type	Description
form_data	dict	The dictionary with all the submitted form data.
kuantaz_submit_token	str	The submit token which was generated by kuantaz and submitted with the form data
kuantaz_validation_token	str	The validation token which kuantaz generated after the validation and which was submitted with the form data

VerificationResult

Constants

• FIELD_NOT_VERIFIED: 'not-verified'
• FIELD_VALID: 'valid'
• FIELD_INVALID: 'invalid'

is_submittable(): bool

Returns True if the form is submittable. This means that the verification was successful and the form data are valid.

is_valid(): bool

Returns True if kuantaz determined the form as valid. The difference to is_submittable() is, that this is the original result from kuantaz, while is_submittable() also checks if the verification was done correctly.

get_verified_fields(): list (see Constants)

Returns an array with all verified field keys.

get_verified_field(key): string (see Constants)

Returns the verification status of one field.

has_issues(): bool

Returns True if there were verification issues.

get_issues(): list

Returns an array with all verification issues.

Get the statistic data by date

To get the statistic data grouped by date, call get_statistic_by_date. The method accepts a time range in seconds for which the data should be returned (last x seconds). The method will return a StatisticResult object.

result = api_client.get_statistic_by_date(range)

Parameter	Type	Description
range	int	The time range in seconds for which the statistic should be returned (last X seconds)

StatisticResult

get_number_of_valid_submissions(): int

Return the number of valid submissions in the requested time range.

get_number_of_spam_submissions(): int

Return the number of spam submissions in the requested time range.

get_numbers_by_date(): dict

Return the numbers grouped by date.