exsited 1.0.13

Exsited SDK

Exsited Python SDK

The Exsited Python SDK provides an easy-to-use library for integrating Exsited services into your project. This includes Custom Integration, Onsite Integration and all APIs.

---

Table of Contents

• Requirements
• Installation
• Configuration
• Authentication
• Getting Started
• Testing
• API Documentation
• Usage charge_item_uuid Association

Requirements

Python 3.12 and Later

Installation

#Navigate to the project directory
cd exsited-python

# Install virtualenv
pip install virtualenv

# Create Virtual Environment
python -m venv venv

# Active virtual Environment from windows
venv\Scripts\activate

# Upgrade the pip
python -m pip install --upgrade pip


# Install setup tools
pip install setuptools

# Install app Dependency
pip install -e .

# Usage association Dependencies
pip install peewee
pip install mysql-connector-python

Configuration

To set up the Exsited SDK, you'll require your Client ID, Client Secret, and Redirect URL. If you have not received these details already, please reach out to your designated client contact to obtain them

Authentication

1. Locate common_data.py: Open the SKD project directory on an IDE and navigate to the common_data.py file which is located in the following path: tests/common/common_data.py.
2. Update get_request_token_dto function: Within the common_data.py class, locate the method named get_request_token_dto and update it with the credentials you were provided.

3. Provide Credential Values: Populate the mandatory fields (clientId, clientSecret, redirectUri, and ExsitedUrl) within the RequestTokenDTO object. However, replace the placeholder values in the following code block with your actual credentials:

Code Example:

def get_request_token_dto():
    return RequestTokenDTO(
        grantType="client_credentials",
        clientId="[YOUR_CLIENT_ID]",  # Replace with your actual Client ID
        clientSecret="[YOUR_CLIENT_SECRET]",  # Replace with your actual Client Secret
        redirectUri="[YOUR_REDIRECT_URI]",  # Replace with your actual Redirect URL
        ExsitedUrl="[YOUR_EXSITED_SERVER_URL]" # Replace with your Exsited server URL, 
    )

Credentials Table

Key	value
clientId	"[YOUR_CLIENT_ID]"
clientSecret	"[YOUR_CLIENT_SECRET]"
redirectUri	"[YOUR_REDIRECT_URI]"
ExsitedUrl	"[YOUR_EXSITED_SERVER_URL]"

Getting Started

Follow the common pattern to test the functions on the SDK. All the tests can be done on the test files located in the Tests directory.

Testing SDK Functions

Example Method 1: test_account_create_basic

---

Request Parameters

Parameter	Description	Type	Required
account	Contains the account details to be created.	AccountDataDTO	Yes
account.name	The name of the account.	str	Yes
account.emailAddress	The email address associated with the account.	str	Yes

Example Request Data (JSON Representation)

{
  "account": {
    "name": "Example Name",
    "emailAddress": "[e-mail]"
  }
}

Function Signature

def test_account_create_basic():
    SDKConfig.PRINT_REQUEST_DATA = False
    SDKConfig.PRINT_RAW_RESPONSE = False

    exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())

    try:
        # You will edit the following request_data
        request_data = AccountCreateDTO(account=AccountDataDTO(name="Example Name", emailAddress="[e-mail]"))
        
        response = exsited_sdk.account.create(request_data=request_data)
        print(response)
    except ABException as ab:
        print(ab)
        print(ab.get_errors())
        print(ab.raw_response)

Example Method 2: test_order_create_basic

---

Parameter	Description	Type	Required
accountId	The ID of the account associated with the order.	str	Yes
item_id	The ID of the item being ordered.	str	Yes
quantity	The quantity of the item being ordered.	str	Yes

{
  "order": {
    "accountId": "30PS79",
    "lines": [
      {
        "item_id": "ITEM-0055",
        "quantity": "1"
      }
    ]
  }
}

Function Signature

def test_order_create_basic():
    SDKConfig.PRINT_REQUEST_DATA = True
    SDKConfig.PRINT_RAW_RESPONSE = False

    exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())

    try:
        # You will edit the following request_data
        request_data = OrderCreateDTO(order=OrderDataDTO(accountId="30PS79").add_line(item_id="ITEM-0055", quantity="1"))
        response = exsited_sdk.order.create(request_data=request_data)
        print(response)
        
    except ABException as ab:
        print(ab)
        print(ab.get_errors())
        print(ab.raw_response)

---

Response

Field	Description
response	The response from the the method being called.
errors	Any errors encountered during the account creation process.

Error Handling

Field	Description
ab	The exception object.
ab.get_errors()	A list of errors that occurred during the account creation process.
ab.raw_response	The raw response data from the API call, useful for debugging.

Testing

Executing Functions

To test the SDK functions, adhere to the common pattern outlined below. All tests should be conducted using the provided test files located in the "Tests" directory.

1. Set up the environment: Ensure that the SDK configuration is appropriately initialized for testing purposes.

2. Customize request data: Adjust the request_data as needed for the specific function being tested.

3. Execute the function: Call the desired function from the SDK, updating the request_data inside the function body.

Required Fields

The following tables contain for the required fields for the test cases

Account

Function Name	Required Fields
test_account_create_basic	name, emailAddress
test_account_update_info	id (Account ID)
test_account_list_basic	n/a
test_account_details	id (Account ID)
test_account_delete	id (Account ID)
test_account_payment_methods_add	processorType, default, paymentProcessor, reference
test_account_payment_card_methods_add	processorType, default, paymentProcessor, reference, cardType, token, cardNumber, expiryMonth, expiryYear
test_list_payment_methods	account_id (Account ID)
test_delete_payment_methods	account_id (Account ID), reference
test_payment_method_details	account_id (Account ID), reference

Order

Function	Required Parameters
test_order_create_basic	accountId, item_id, quantity (Item Quantity)
test_order_list_basic	n/a
test_order_details	id (Order ID)
test_order_cancel	id (Order ID), effective_date
test_order_usage_add	chargeItemUuid, chargingPeriod, quantity, startTime, endTime, type

Invoice

Function	Required Parameters
test_invoice_list	n/a
test_invoice_details	id

API Documentation

API Documentation

Usage charge_item_uuid Association

The order_usage_db folder contains the functionality for handling database operations related to orders within the Exsited SDK. This module is responsible for connecting to the database, managing orders, processing order data, and saving the relevant information to the database.

Components of order_usage_db

1. connect_with_db.py

   • Manages the database connection setup, including functions for establishing and terminating connections

2. order_manager.py

   • Manages Order data, to create rows for the database where the relevant associations are made in order to create usages easily using charge_item_uuid

3. order_model.py

   • Contains the structure of the order association table

4. order_service.py

   • Contains the function to create the association records

5. save_to_db.py

   • Implements the logic to persist order association data to the database. It interacts with the connect_with_db.py module to perform save operations.

Adding Data To the Association Table

After configuring your database connection in connect_with_db.py, you can use the other scripts to manage orders and persist data to your database. For example, you can create and process an order using order_manager.py and then save it using save_to_db.py.

Example Workflow

1. Adding Database Details: In the SaveToDB class within the order_usage_db module, ensure that you update the OrderManager initialization with your specific database connection details, such as the database name, username, password, and host address.

2. class SaveToDB:
    def process_order_data(_order_id: str, _account_id: str, _item_id: str, _item_name: str, _charge_item_uuid: str):
        # Add your database details below
        order_manager = OrderManager('your_database_name', 'your_username', 'your_password', 'your_host_address')
        order_manager.connect_to_db()
        order_manager.process_order(
            account_id=_account_id,
            order_id=_order_id,
            item_id=_item_id,
            item_name=_item_name,
            charge_item_uuid=_charge_item_uuid
        )
        order_manager.disconnect_from_db()
   

3. Once the database details and other necessary configurations have been added, you can use the following example to add an order. This will automatically update the association tables, allowing you to retrieve the relevant details needed to update usage data.

   def test_order_create_basic():
    SDKConfig.PRINT_REQUEST_DATA = True
    SDKConfig.PRINT_RAW_RESPONSE = False
   
    exsited_sdk: ExsitedSDK = ExsitedSDK().init_sdk(request_token_dto=CommonData.get_request_token_dto())
   
    try:
        request_data = OrderCreateDTO(
            order=OrderDataDTO(accountId="AC01").add_line(item_id="ITEM-001", quantity="1"))
        response = exsited_sdk.order.create(request_data=request_data)
        
        if response.order:
            account_id = response.order.accountId
            order_id = response.order.id
            for line in response.order.lines:
                if line.itemChargeType == 'METERED':
                     #Note: The item must be of type "Metered" for the association data to be stored.
                    SaveToDB.process_order_data(_account_id=account_id, _order_id=order_id, _item_id=line.itemId,
                                     _item_name=line.itemName, _charge_item_uuid=line.chargeItemUuid)
    except ABException as ab:
        print(ab)
        print(ab.get_errors())
        print(ab.raw_response)
   

[1.0.13] - 2025-06-23

🛠️ Added

• Automatic Retry Mechanism
  Introduced a retry loop (MAX_RETRIES = 3) in ABRestProcessor.process_rest_request to handle transient HTTP failures for status codes [401, 500, 502, 503, 504].

• Token Renewal Improvement
  _renew_token now strictly reinitializes the token using _init_auth, making the fallback flow more robust.

• New Method: _renew_token
  Preserves the original refresh-token flow (now unused internally), offering flexibility for future use cases. Old token system has been renamed to renew_token_v1.