exsited 1.0.33

Exsited SDK

Exsited Python SDK

The Exsited Python SDK provides a comprehensive, easy-to-use library for integrating with the Exsited platform. Whether you're building custom integrations, onsite solutions, or leveraging the full API suite, this SDK offers a streamlined approach to interact with all Exsited services.

🚀 What is Exsited?

Exsited is a powerful business management platform that provides:

• Account Management: Complete customer lifecycle management
• Order Processing: End-to-end order management and fulfillment
• Billing & Invoicing: Automated billing with flexible pricing models
• Payment Processing: Integrated payment gateway solutions
• Usage Tracking: Metered billing and usage analytics
• Custom Objects: Flexible data modeling for your business needs
• Portal Management: Customer self-service portals

---

📋 Table of Contents

• 🔧 Requirements
• ⚡ Installation
  • PyPI Installation
  • Development Installation
• 🔑 Authentication & Configuration
• 🏁 Quick Start
• 📚 Available Modules
• 💡 Usage Examples
• 📖 Documentation
• 🆘 Support

---

🔧 Requirements

• Python 3.12+ (Recommended: Python 3.12 or later)
• Dependencies: requests, setuptools, peewee, mysql-connector-python, portalocker

---

⚡ Installation

PyPI Installation

Install the Exsited SDK directly from PyPI:

pip install exsited

Development Installation

For development or to access the latest features:

# Clone the repository
git clone https://github.com/exsited/exsited-python.git
cd exsited-python

# Create and activate virtual environment
python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

# Upgrade pip and install dependencies
python -m pip install --upgrade pip
pip install setuptools

# Install in development mode
pip install -e .

# Optional: Install additional dependencies for usage tracking
pip install peewee mysql-connector-python

---

🔑 Authentication & Configuration

Getting Credentials

To use the Exsited SDK, you'll need:

• Client ID
• Client Secret
• Redirect URI
• Exsited Server URL

Contact your Exsited representative to obtain these credentials.

Configuration Setup

Create a configuration file or set up your credentials:

from exsited.exsited.auth.dto.token_dto import RequestTokenDTO

def get_request_token_dto():
    return RequestTokenDTO(
        grantType="client_credentials",
        clientId="[YOUR_CLIENT_ID]",
        clientSecret="[YOUR_CLIENT_SECRET]", 
        redirectUri="[YOUR_REDIRECT_URI]",
        exsitedUrl="[YOUR_EXSITED_SERVER_URL]"
    )

Credentials Reference

Parameter	Description	Example
clientId	Your unique client identifier	"your-client-id-here"
clientSecret	Your client secret key	"your-secret-key-here"
redirectUri	Authorized redirect URL	"https://your-app.com/callback"
exsitedUrl	Exsited server endpoint	"https://api.exsited.com"

---

🏁 Quick Start

Basic Usage

from exsited.exsited.exsited_sdk import ExsitedSDK
from exsited.http.file_token_manager import FileTokenManager
from exsited.common.ab_exception import ABException

# Initialize token manager
token_file_path = "shared_token.json"
file_token_mgr = FileTokenManager(token_file_path)

# Initialize SDK
exsited_sdk = ExsitedSDK().init_sdk(
    request_token_dto=get_request_token_dto(),
    file_token_mgr=file_token_mgr
)

# Example: Create an account
try:
    from exsited.exsited.account.dto.account_dto import AccountCreateDTO, AccountDataDTO
    
    request_data = AccountCreateDTO(
        account=AccountDataDTO(
            name="John Doe",
            emailAddress="[e-mail]"
        )
    )
    
    response = exsited_sdk.account.create(request_data=request_data)
    print(f"Account created: {response.account.id}")
    
except ABException as e:
    print(f"Error: {e}")
    print(f"Details: {e.get_errors()}")

Alternative Initialization

# Direct initialization with credentials
exsited_sdk = ExsitedSDK(
    exsited_url="https://api.exsited.com",
    grant_type="client_credentials",
    client_id="your-client-id",
    client_secret="your-client-secret",
    redirect_uri="https://your-app.com/callback"
)

---

📚 Available Modules

The Exsited SDK provides comprehensive modules for all platform features:

Core Business Modules

Module	Description	Key Features
Account	Customer management	Create, update, delete accounts; manage payment methods
Order	Order processing	Create orders, manage order lines, cancel orders
Invoice	Billing management	Generate invoices, track payments
Payment	Payment processing	Process payments, manage payment methods

Advanced Modules

Module	Description	Key Features
Custom Objects	Flexible data modeling	Create custom business objects
Custom Attributes	Dynamic field management	Add custom fields to entities
Custom Components	Component management	Manage custom UI components
External Database	External data integration	Connect with external databases

Business Operations

Module	Description	Key Features
Purchase Order	Procurement management	Manage supplier orders
Purchase Invoice	Vendor billing	Handle supplier invoices
Purchase Payments	Vendor payments	Process supplier payments
Return Merchandise	Returns processing	Handle product returns

Additional Services

Module	Description	Key Features
Gift Certificates	Gift card management	Issue and redeem gift certificates
Credit Note	Credit management	Issue credits and refunds
Refund	Refund processing	Process customer refunds
Express	Quick operations	Streamlined workflows
Notes	Note management	Attach notes to entities
Portal	Customer portals	Manage customer self-service
Setting	Configuration management	System and user settings

---

💡 Usage Examples

Account Management

# Create an account
request_data = AccountCreateDTO(
    account=AccountDataDTO(
        name="ABC Company",
        emailAddress="[e-mail]",
        phoneNumber="[phone]"
    )
)
account_response = exsited_sdk.account.create(request_data=request_data)

# Get account details
account_details = exsited_sdk.account.details(id="ACCT-001")

# List accounts with pagination
accounts = exsited_sdk.account.list(limit=50, offset=0)

Order Processing

# Create an order
from exsited.exsited.order.dto.order_dto import OrderCreateDTO, OrderDataDTO

order_data = OrderCreateDTO(
    order=OrderDataDTO(accountId="ACCT-001")
        .add_line(item_id="ITEM-001", quantity="2")
        .add_line(item_id="ITEM-002", quantity="1")
)

order_response = exsited_sdk.order.create(request_data=order_data)
print(f"Order created: {order_response.order.id}")

# Get order details
order_details = exsited_sdk.order.details(id="ORDER-001")

# Cancel an order
cancel_response = exsited_sdk.order.cancel(
    id="ORDER-001",
    effective_date="2024-12-31"
)

Usage Tracking (Metered Billing)

# Add usage data for metered items
from exsited.exsited.order.dto.usage_dto import UsageCreateDTO

usage_data = UsageCreateDTO(
    chargeItemUuid="charge-uuid-here",
    chargingPeriod="2024-01",
    quantity=100,
    startTime="2024-01-01T00:00:00Z",
    endTime="2024-01-31T23:59:59Z",
    type="usage"
)

usage_response = exsited_sdk.order.usage_add(request_data=usage_data)

Custom Objects

# Work with custom objects
from exsited.exsited.custom_objects.dto.custom_objects_dto import CustomObjectsCreateDTO

custom_obj = CustomObjectsCreateDTO(
    name="Product Specification",
    type="specification",
    properties={
        "dimensions": "10x20x30",
        "weight": "5kg",
        "color": "blue"
    }
)

custom_response = exsited_sdk.custom_objects.create(request_data=custom_obj)

Payment Processing

# Add a payment method
from exsited.exsited.payment.dto.payment_dto import CardPaymentCreateDTO

payment_method = CardPaymentCreateDTO(
    processorType="stripe",
    cardType="visa",
    cardNumber="4111111111111111",
    expiryMonth="12",
    expiryYear="2025",
    cvv="123"
)

payment_response = exsited_sdk.payment.add_card_method(request_data=payment_method)

📖 Documentation

Official Documentation

• SDK Guide: https://developer.exsited.com/exsited-sdk-introduction

Error Handling

All SDK methods use the ABException class for error handling:

from exsited.common.ab_exception import ABException

try:
    # SDK operation
    response = exsited_sdk.account.create(request_data)
except ABException as e:
    # Handle specific errors
    errors = e.get_errors()  # List of error messages
    raw_response = e.raw_response  # Raw API response
    
    # Log error details
    print(f"Operation failed: {e}")
    for error in errors:
        print(f"- {error}")

🆘 Support

Getting Help

1. Documentation: Check the official documentation
2. GitHub Issues: Report bugs or request features on our GitHub repository
3. Contact Support: Reach out to your Exsited representative
4. Email: Technical support at [e-mail]

Common Issues

Issue	Solution
Authentication errors	Verify your credentials and server URL
Import errors	Ensure you're using the latest import paths
Token expiration	The SDK handles token refresh automatically
Connection timeouts	Check your network connection and server status

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🔗 Links

• PyPI: https://pypi.org/project/exsited/
• GitHub: https://github.com/exsited/exsited-python
• Documentation: https://developer.exsited.com
• Website: https://exsited.com

---

Built with ❤️ by the Exsited team