<p align="center">
  <a href="https://fingerprint.com">
    <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://fingerprintjs.github.io/home/resources/logo_light.svg" />
     <source media="(prefers-color-scheme: light)" srcset="https://fingerprintjs.github.io/home/resources/logo_dark.svg" />
     <img src="https://fingerprintjs.github.io/home/resources/logo_dark.svg" alt="Fingerprint logo" width="312px" />
   </picture>
  </a>
</p>
<p align="center">
  <a href="https://pypi.org/project/fingerprint-pro-server-api-sdk/"><img alt="PyPI" src="https://img.shields.io/pypi/v/fingerprint-pro-server-api-sdk"></a>
  <a href="https://fingerprintjs.github.io/fingerprint-pro-server-api-python-sdk/"><img src="https://fingerprintjs.github.io/fingerprint-pro-server-api-python-sdk/badges.svg" alt="coverage"></a>
  <a href="https://github.com/fingerprintjs/fingerprint-pro-server-api-python-sdk/actions/workflows/release.yml"><img src="https://github.com/fingerprintjs/fingerprint-pro-server-api-python-sdk/actions/workflows/release.yml/badge.svg" alt="CI badge" /></a>
  <a href="https://github.com/fingerprintjs/fingerprint-pro-server-api-python-sdk/actions/workflows/test.yml"><img src="https://github.com/fingerprintjs/fingerprint-pro-server-api-python-sdk/actions/workflows/test.yml/badge.svg" alt="CI badge" /></a>
  <a href="https://github.com/fingerprintjs/fingerprint-pro-server-api-python-sdk/actions/workflows/functional_tests.yml"><img src="https://github.com/fingerprintjs/fingerprint-pro-server-api-python-sdk/actions/workflows/functional_tests.yml/badge.svg" alt="CI badge" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/:license-mit-blue.svg?style=flat"/></a>
  <a href="https://discord.gg/39EpE2neBg"><img src="https://img.shields.io/discord/852099967190433792?style=logo&label=Discord&logo=Discord&logoColor=white" alt="Discord server"></a>
</p>

# Fingerprint Server Python SDK

[Fingerprint](https://fingerprint.com) is a device intelligence platform offering industry-leading accuracy.
The Fingerprint Server Python SDK is an easy way to interact with the Fingerprint [Server API](https://dev.fingerprint.com/reference/pro-server-api) from your Python application. You can retrieve visitor history or individual identification events.


This Python package is automatically generated by the [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) project:

- API version: {{appVersion}}
- Package version: {{packageVersion}}
{{^hideGenerationTimestamp}}
- Build date: {{generatedDate}}
{{/hideGenerationTimestamp}}
- Build package: {{generatorClass}}
{{#infoUrl}}
For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
{{/infoUrl}}

## Requirements

The following Python versions are supported:

- Python >= 3.9

## Installation & Usage
### pip install

You can install the package directly from the Github

```sh
pip install git+https://github.com/{{{gitUserId}}}/{{{gitRepoId}}}.git
```

Or from the PyPI

```sh
pip install {{{packageName}}}
```

Then import the package:
```python
import {{{packageName}}}
```

### Setuptools

Install via [Setuptools](http://pypi.python.org/pypi/setuptools).

```sh
python setup.py install --user
```
(or `sudo python setup.py install` to install the package for all users)

Then import the package:
```python
import {{{packageName}}}
```

## Getting Started

Please follow the [installation procedure](#installation--usage) and then run the following:

```python
import {{packageName}}

# Configure API key authorization and region
configuration = {{packageName}}.Configuration(api_key="SECRET_API_KEY")
# configuration = {{packageName}}.Configuration(api_key="SECRET_API_KEY", region="eu")

# create an instance of the API class
api_instance = {{packageName}}.FingerprintApi(configuration)
```

## Examples

Fetching visits using visitorId:
```python
import {{packageName}}
from {{packageName}}.rest import ApiException, KnownApiException

configuration = {{packageName}}.Configuration(api_key="SECRET_API_KEY")
api_instance = {{packageName}}.FingerprintApi(configuration)

visitor_id = 'visitor_id_example'  # str | Unique [visitor identifier](https://dev.fingerprint.com/docs/js-agent#visitorid) issued by Fingerprint Pro.
#request_id = 'request_id_example'  # str | The unique event [identifier](https://dev.fingerprint.com/docs/js-agent#requestid).
#linked_id = 'linked_id_example'  # str | Filter visits by your custom identifier.   You can use [`linkedId`](https://dev.fingerprint.com/docs/js-agent#linkedid) to associate identification requests with your own identifier, for example: session ID, purchase ID, or transaction ID. You can then use this `linked_id` parameter to retrieve all events associated with your custom identifier.  (optional)
limit = 10  # int | Limit scanned results.   For performance reasons, the API first scans some number of events before filtering them. Use `limit` to specify how many events are scanned before they are filtered by `requestId` or `linkedId`. Results are always returned sorted by the timestamp (most recent first). By default, the most recent 100 visits are scanned, the maximum is 500.  (optional)
#pagination_key = 'pagination_key_example' # str | Use `paginationKey` to get the next page of results.   When more results are available (e.g., you requested 200 results using `limit` parameter, but a total of 600 results are available), the `paginationKey` top-level attribute is added to the response. The key corresponds to the `requestId` of the last returned event. In the following request, use that value in the `paginationKey` parameter to get the next page of results:  1. First request, returning most recent 200 events: `GET api-base-url/visitors/:visitorId?limit=200` 2. Use `response.paginationKey` to get the next page of results: `GET api-base-url/visitors/:visitorId?limit=200&paginationKey=1683900801733.Ogvu1j`  Pagination happens during scanning and before filtering, so you can get less visits than the `limit` you specified with more available on the next page. When there are no more results available for scanning, the `paginationKey` attribute is not returned.  (optional)

try:
    api_response = api_instance.get_visits(visitor_id, limit=2)
    print(api_response)
except KnownApiException as e:
    structured_error = e.structured_error
    print("Error: %s\n" % structured_error.error)
except ApiException as e:
    print("Exception when calling FingerprintApi->visitors_visitor_id_get: %s\n" % e)
```

Delete visits using visitorId:
```python
import {{packageName}}
from {{packageName}}.rest import ApiException, KnownApiException

configuration = {{packageName}}.Configuration(api_key="SECRET_API_KEY")
api_instance = {{packageName}}.FingerprintApi(configuration)

visitor_id = 'visitor_id_example'  # str | Unique [visitor identifier](https://dev.fingerprint.com/docs/js-agent#visitorid) issued by Fingerprint Pro.

try:
    api_instance.delete_visitor_data(visitor_id)
except KnownApiException as e:
    structured_error = e.structured_error
    print("Error: %s\n" % structured_error.error)
except ApiException as e:
    print("Exception when calling FingerprintApi->delete_visitor_data: %s\n" % e)
```

Fetching events for requestId:
```python
import {{packageName}}
from {{packageName}}.rest import ApiException, KnownApiException

configuration = {{packageName}}.Configuration(api_key="SECRET_API_KEY")
api_instance = {{packageName}}.FingerprintApi(configuration)

request_id = 'request_id_example'  # str | The unique event [identifier](https://dev.fingerprint.com/docs/js-agent#requestid).

try:
    events_response = api_instance.get_event(request_id)

except KnownApiException as e:
    structured_error = e.structured_error
    print("Error code: %s. Error message: %s\n" % (structured_error.error.code, structured_error.error.message))
except ApiException as e:
    print("Exception when calling FingerprintApi->get_event: %s\n" % e)
```

Search events with custom filters:
```python
import fingerprint_pro_server_api_sdk
from fingerprint_pro_server_api_sdk.rest import ApiException, KnownApiException

configuration = fingerprint_pro_server_api_sdk.Configuration(api_key="SECRET_API_KEY")
api_instance = fingerprint_pro_server_api_sdk.FingerprintApi(configuration)

limit = 20                      # int | Limit the number of events returned.
pagination_key = 'key_example'  # str | Use `pagination_key` to get the next page of results.   When more results are available (e.g., you requested up to 200 results for your search using `limit`, but there are more than 200 events total matching your request), the `paginationKey` top-level attribute is added to the response. The key corresponds to the `timestamp` of the last returned event. In the following request, use that value in the `pagination_key` parameter to get the next page of results:  1. First request, returning most recent 200 events: `GET api-base-url/events/search?limit=200` 2. Use `response.paginationKey` to get the next page of results: `GET api-base-url/events/search?limit=200&pagination_key=1740815825085`  (optional)
visitor_id = 'VISITOR_ID'       # str | Unique [visitor identifier](https://dev.fingerprint.com/reference/get-function#visitorid) issued by Fingerprint Pro. Filter for events matching this `visitor_id`.  (optional)
bot = 'good'                    # str | Filter events by the bot detection result, specifically: events where <'any'|'good'|'bad'|'none'> kind of bot was detected.  (optional)
ip_address = '192.168.0.1/32'   # str | Filter events by IP address range. The range can be as specific as a single IP (/32 for IPv4 or /128 for IPv6)  All ip_address filters must use CIDR notation, for example, 10.0.0.0/24, 192.168.0.1/32  (optional)
linked_id = 'linked_id_example' # str | Filter events by your custom identifier.   You can use [linked IDs](https://dev.fingerprint.com/reference/get-function#linkedid) to associate identification requests with your own identifier, for example, session ID, purchase ID, or transaction ID. You can then use this `linked_id` parameter to retrieve all events associated with your custom identifier.  (optional)
start = 1738687200000           # int | Filter events with a timestamp greater than the start time, in Unix time (milliseconds).  (optional)
end = 1738773600000             # int | Filter events with a timestamp smaller than the end time, in Unix time (milliseconds).  (optional)
reverse = True                 # bool | Sort events in reverse timestamp order.  (optional)
suspect = False                # bool | Filter events previously tagged as suspicious via the [Update API](https://dev.fingerprint.com/reference/updateevent).  (optional)

try:
    # Get events via search
    api_response = api_instance.search_events(limit, pagination_key=pagination_key, visitor_id=visitor_id, bot=bot, ip_address=ip_address, linked_id=linked_id, start=start, end=end, reverse=reverse, suspect=suspect)
    print(api_response)

except KnownApiException as e:
    structured_error = e.structured_error
    print("Error code: %s. Error message: %s\n" % (structured_error.error.code, structured_error.error.message))
except ApiException as e:
    print("Exception when calling FingerprintApi->get_event: %s\n" % e)
```

Update event for requestId:
```python
import {{packageName}}
from {{packageName}} import EventsUpdateRequest
from {{packageName}}.rest import ApiException, KnownApiException

configuration = {{packageName}}.Configuration(api_key="SECRET_API_KEY")
api_instance = {{packageName}}.FingerprintApi(configuration)

request_id = 'request_id_example'  # str | The unique event [identifier](https://dev.fingerprint.com/docs/js-agent#requestid).
body = EventsUpdateRequest(linked_id='foo')  # EventsUpdateRequest |
# body = EventsUpdateRequest(tag={'bar': 123})
# body = EventsUpdateRequest(suspect=True)
# body = EventsUpdateRequest(linked_id='foo', tag={'bar': 123}, suspect=False)

try:
    api_instance.update_event(body, request_id)
except KnownApiException as e:
    structured_error = e.structured_error
    print("Error code: %s. Error message: %s\n" % (structured_error.error.code, structured_error.error.message))
except ApiException as e:
    print("Exception when calling FingerprintApi->update_event: %s\n" % e)
```

## Sealed results

This SDK provides utility methods for decoding [sealed results](https://dev.fingerprint.com/docs/sealed-client-results).
```python
import base64
import os

from dotenv import load_dotenv

from fingerprint_pro_server_api_sdk import unseal_event_response, DecryptionKey, DecryptionAlgorithm

load_dotenv()

sealed_result = base64.b64decode(os.environ["BASE64_SEALED_RESULT"])
key = base64.b64decode(os.environ["BASE64_KEY"])

try:
    event_response = unseal_event_response(sealed_result, [DecryptionKey(key, DecryptionAlgorithm['Aes256Gcm'])])
    print("\n\n\nEvent response: \n", event_response.products)
except Exception as e:
    print("Exception when calling unsealing events response: %s\n" % e)
    exit(1)

print("Unseal successful!")

exit(0)
```
To learn more, refer to example located in [sealed_results_example.py](sealed_results_example.py).

## Webhook signature validation

This SDK provides utility method for verifying the HMAC signature of the incoming webhook request.
```python
import os
from flask import Flask, request, jsonify
from fingerprint_pro_server_api_sdk import WebhookValidation

app = Flask(__name__)

@app.route('/api/webhook', methods=['POST'])
def webhook_handler():
    try:
        # Retrieve the secret key from environment variables
        secret = os.getenv("WEBHOOK_SIGNATURE_SECRET")
        if not secret:
            return jsonify({"message": "Secret key is not configured."}), 400

        # Get the "fpjs-event-signature" header from the incoming request
        header = request.headers.get('fpjs-event-signature')
        if not header:
            return jsonify({"message": "Missing fpjs-event-signature header."}), 400

        # Read the raw body of the incoming request
        data = request.get_data()

        # Validate the webhook signature
        is_valid = WebhookValidation.is_valid_webhook_signature(header, data, secret)
        if not is_valid:
            return jsonify({"message": "Webhook signature is invalid."}), 403

        # Process the webhook data here
        return jsonify({"message": "Webhook received."}), 200

    except Exception as e:
        # Handle any unexpected errors
        return jsonify({"error": str(e)}), 500

if __name__ == '__main__':
    # Start the Flask application on the specified host and port
    app.run(host='0.0.0.0', port=5000)
```
To learn more, refer to example located in [webhook_signature_example.py](webhook_signature_example.py).

## Documentation for API Endpoints

All URIs are relative to *{{basePath}}*

Class | Method | HTTP request | Description
------------ | ------------- | ------------- | -------------
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}

## Documentation For Models

{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
{{/model}}{{/models}}

## Documentation For Authorization

{{^authMethods}} All endpoints do not require authorization.
{{/authMethods}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
{{#authMethods}}## {{{name}}}

{{#isApiKey}}- **Type**: API key
- **API key parameter name**: {{{keyParamName}}}
- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
{{/isApiKey}}
{{#isBasic}}- **Type**: HTTP basic authentication
{{/isBasic}}
{{#isOAuth}}- **Type**: OAuth
- **Flow**: {{{flow}}}
- **Authorization URL**: {{{authorizationUrl}}}
- **Scopes**: {{^scopes}}N/A{{/scopes}}
{{#scopes}} - **{{{scope}}}**: {{{description}}}
{{/scopes}}
{{/isOAuth}}

{{/authMethods}}

## Documentation for sealed results

- [SealedResults](docs/SealedResults.md)
- [DecryptionKey](docs/DecryptionKey.md)

## Support

To report problems, ask questions or provide feedback, please use [Issues](https://github.com/fingerprintjs/fingerprint-pro-server-api-python-sdk/issues).
If you need private support, you can email us at [oss-support@fingerprint.com](mailto:oss-support@fingerprint.com).

## License

This project is licensed under the [MIT License](https://github.com/fingerprintjs/fingerprint-pro-server-api-python-sdk/blob/main/LICENSE).