API Reference

Base Information

Base URL: https://your-domain.com/api/
Current Version: v1
Authentication: JWT Token-based
Content Type: application/json
Response Format: JSON

API Structure

/api/
├── auth/                       # Authentication endpoints
├── admin/v1/                   # Admin management APIs
├── business/v1/                # Business customer APIs
├── reseller/v1/                # Reseller management APIs
└── reseller/earnings/          # Reseller earnings APIs

Authentication Flow

The API uses JWT (JSON Web Tokens) for authentication. Users must obtain a token via login and include it in the Authorization header for protected endpoints.

Login Endpoint

Method	Endpoint	Description
POST	`/api/auth/login/`	Authenticate user and get JWT token

Request Example

POST /api/auth/login/
Content-Type: application/json

{
    "email": "user@example.com",
    "password": "your_password"
}

Response Example

{
    "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "user": {
        "id": 1,
        "email": "user@example.com",
        "role": "reseller"
    }
}

Using the Token

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

User Management

List Users

Method	GET
Endpoint	`/api/admin/v1/users/`
Description	Get paginated list of all platform users
Authentication	Required (Admin only)

Query Parameters

role - Filter by user role (admin, business_owner, reseller)
status - Filter by status (active, pending, suspended)
search - Search by email or name
page - Page number for pagination
page_size - Number of results per page

Response Example

{
    "count": 150,
    "next": "/api/admin/v1/users/?page=2",
    "previous": null,
    "results": [
        {
            "id": 1,
            "email": "user@example.com",
            "first_name": "John",
            "last_name": "Doe",
            "profile": {
                "role": "reseller",
                "phone": "+1234567890",
                "industry": "Technology"
            },
            "is_active": true,
            "date_joined": "2024-01-15T10:30:00Z"
        }
    ]
}

Approve User

Method	POST
Endpoint	`/api/admin/v1/users/{id}/approve/`
Description	Approve a pending user registration
Authentication	Required (Admin only)

Response Example

{
    "message": "User approved successfully",
    "user_id": 1,
    "status": "active"
}

Business Management

Method	GET
Endpoint	`/api/admin/v1/businesses/`
Description	Get list of all business customers
Authentication	Required (Admin only)

Query Parameters

industry - Filter by industry
country - Filter by country
company_size - Filter by company size

Profile Management

Get Profile

Method	GET
Endpoint	`/api/reseller/v1/profile/`
Description	Get current reseller's profile information
Authentication	Required (Reseller)

Response Example

{
    "id": 1,
    "user": {
        "id": 5,
        "email": "reseller@example.com",
        "first_name": "Jane",
        "last_name": "Smith"
    },
    "reseller_type": "individual",
    "company_name": null,
    "phone_number": "+1234567890",
    "address": "123 Main St",
    "city": "New York",
    "country": "United States",
    "referral_code": "LXN-U00005-A7B",
    "tier": "silver",
    "commission_rate": "15.00",
    "is_verified": true,
    "total_sales": "12500.00",
    "total_commission_earned": "1875.00",
    "pending_commission": "250.00"
}

Update Profile

Method	PUT/PATCH
Endpoint	`/api/reseller/v1/profile/`
Description	Update reseller profile information
Authentication	Required (Reseller)

Request Example

PATCH /api/reseller/v1/profile/
Content-Type: application/json

{
    "phone_number": "+1987654321",
    "address": "456 Oak Avenue",
    "city": "Los Angeles"
}

Get Referral Link

Method	GET
Endpoint	`/api/reseller/v1/referral-link/`
Description	Get personalized referral links
Authentication	Required (Reseller)

Query Parameters

product_id - Optional specific product to create link for

Response Example

{
    "referral_code": "LXN-U00005-A7B",
    "links": {
        "general": "https://platform.com/?ref=LXN-U00005-A7B",
        "erp_product": "https://platform.com/erp/?ref=LXN-U00005-A7B",
        "sacco_product": "https://platform.com/sacco/?ref=LXN-U00005-A7B"
    }
}

Commission Management

List Commissions

Method	GET
Endpoint	`/api/reseller/earnings/commissions/`
Description	Get list of reseller's commissions
Authentication	Required (Reseller)

Query Parameters

status - Filter by status (pending, approved, paid)
start_date - Start date for date range filter
end_date - End date for date range filter
page - Page number

Response Example

{
    "count": 25,
    "next": "/api/reseller/earnings/commissions/?page=2",
    "previous": null,
    "results": [
        {
            "id": 1,
            "transaction_reference": "TXN-001-2024",
            "client_name": "ABC Corp",
            "client_email": "contact@abccorp.com",
            "product_name": "ERP Professional",
            "sale_amount": "2500.00",
            "amount": "375.00",
            "commission_rate": "15.00",
            "tier_bonus": "0.00",
            "status": "approved",
            "calculation_date": "2024-01-20T14:30:00Z",
            "approval_date": "2024-01-22T10:15:00Z",
            "paid_date": null
        }
    ]
}

Earnings Dashboard

Method	GET
Endpoint	`/api/reseller/earnings/dashboard/`
Description	Get earnings dashboard summary
Authentication	Required (Reseller)

Response Example

{
    "summary": {
        "total_earnings": "1875.00",
        "pending_commission": "250.00",
        "this_month_earnings": "450.00",
        "last_month_earnings": "380.00"
    },
    "tier_info": {
        "current_tier": "silver",
        "commission_rate": "15.00",
        "next_tier": "gold",
        "sales_to_next_tier": "2500.00"
    },
    "recent_commissions": [...],
    "performance_chart": {
        "labels": ["Jan", "Feb", "Mar", "Apr"],
        "data": [300, 450, 380, 450]
    }
}

Request Payout

Method	POST
Endpoint	`/api/reseller/earnings/payout-request/`
Description	Request payout of pending commissions
Authentication	Required (Reseller)

Request Example

POST /api/reseller/earnings/payout-request/
Content-Type: application/json

{
    "amount": "250.00",
    "payment_method": "bank_transfer",
    "notes": "Monthly payout request"
}

Response Example

{
    "id": 15,
    "amount": "250.00",
    "payment_method": "bank_transfer",
    "status": "pending",
    "request_date": "2024-01-25T09:00:00Z",
    "estimated_processing": "2024-01-27T09:00:00Z",
    "message": "Payout request submitted successfully"
}

Business Profile

Get Business Profile

Method	GET
Endpoint	`/api/business/v1/profile/`
Description	Get current business profile
Authentication	Required (Business)

Response Example

{
    "id": 1,
    "business_name": "TechCorp Solutions",
    "business_email": "info@techcorp.com",
    "industry": "Information Technology",
    "company_size": "51-200",
    "country": "Kenya",
    "postal_code": "00100",
    "subscription_status": "active",
    "current_plan": {
        "name": "Professional",
        "price": "299.99",
        "features": ["Advanced Reporting", "API Access", "Priority Support"]
    }
}

Subscription Management

Method	GET
Endpoint	`/api/business/v1/subscription/`
Description	Get current subscription details
Authentication	Required (Business)

Available Plans

Method	GET
Endpoint	`/api/business/v1/plans/`
Description	Get list of available subscription plans
Authentication	Required (Business)

Response Example

{
    "plans": [
        {
            "id": 1,
            "name": "Basic",
            "price": "99.99",
            "yearly_price": "999.99",
            "description": "Perfect for small businesses",
            "features": [
                {"name": "Users", "value": "Up to 10"},
                {"name": "Storage", "value": "100GB"},
                {"name": "Support", "value": "Email"}
            ]
        },
        {
            "id": 2,
            "name": "Professional",
            "price": "299.99",
            "yearly_price": "2999.99",
            "description": "Advanced features for growing businesses",
            "features": [
                {"name": "Users", "value": "Up to 50"},
                {"name": "Storage", "value": "500GB"},
                {"name": "Support", "value": "Priority"}
            ]
        }
    ]
}

HTTP Status Codes

Code	Description	Usage
200	OK	Successful GET, PUT, PATCH requests
201	Created	Successful POST requests that create resources
400	Bad Request	Invalid request parameters or malformed JSON
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	User doesn't have permission for the requested action
404	Not Found	Requested resource doesn't exist
500	Internal Server Error	Unexpected server error

Error Response Format

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "The provided data is invalid",
        "details": {
            "email": ["This field is required"],
            "password": ["Password must be at least 8 characters"]
        }
    }
}

Common Error Codes

VALIDATION_ERROR - Invalid input data
AUTHENTICATION_FAILED - Invalid credentials
PERMISSION_DENIED - Insufficient permissions
RESOURCE_NOT_FOUND - Requested resource doesn't exist
RATE_LIMIT_EXCEEDED - Too many requests

Rate Limit Rules

User Type	Requests per Hour	Burst Limit
Unauthenticated	100	10 per minute
Authenticated User	1000	50 per minute
Admin	5000	200 per minute

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1643723400

Rate Limit Exceeded Response

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Rate limit exceeded. Try again in 3600 seconds.",
        "retry_after": 3600
    }
}

API Overview

Base Information

API Structure

Authentication

Authentication Flow

Login Endpoint

Request Example

Response Example

Using the Token

Admin APIs

User Management

List Users

Query Parameters

Response Example

Approve User

Response Example

Business Management

Query Parameters

Reseller APIs

Profile Management

Get Profile

Response Example

Update Profile

Request Example

Get Referral Link

Query Parameters

Response Example

Earnings APIs

Commission Management

List Commissions

Query Parameters

Response Example

Earnings Dashboard

Response Example

Request Payout

Request Example

Response Example

Business APIs

Business Profile

Get Business Profile

Response Example

Subscription Management

Available Plans

Response Example

Error Handling

HTTP Status Codes

Error Response Format

Common Error Codes

Rate Limiting

Rate Limit Rules

Rate Limit Headers

Rate Limit Exceeded Response