kwork-api/docs/usage.md

Usage Guide

Authentication

Login with credentials

from kwork_api import KworkClient

async with await KworkClient.login("username", "password") as client:
    # Your code here
    pass

Restore session from token

from kwork_api import KworkClient

# Save token after first login
client = await KworkClient.login("username", "password")
token = client.token  # Save this

# Later, restore session
client = KworkClient(token="saved_token")
user = await client.user.get_info()

API Groups

Catalog API

# Get catalog list
catalog = await client.catalog.get_list(page=1, category_id=1)

# Get kwork details
kwork = await client.catalog.get_details(kwork_id=123)

Projects API (Freelance)

# Get projects list
projects = await client.projects.get_list(page=1)

# Get your orders
my_orders = await client.projects.get_payer_orders()

User API

# Get user info
user = await client.user.get_info()

# Get reviews
reviews = await client.user.get_reviews(user_id=123)

Reference API

# Get cities
cities = await client.reference.get_cities()

# Get countries
countries = await client.reference.get_countries()

# Get categories
categories = await client.reference.get_categories()

Notifications API

# Get notifications
notifications = await client.notifications.get_list()

# Get dialogs
dialogs = await client.notifications.get_dialogs()

Error Handling

from kwork_api import KworkApiError, KworkAuthError

try:
    catalog = await client.catalog.get_list()
except KworkAuthError as e:
    print(f"Authentication failed: {e}")
except KworkApiError as e:
    print(f"API error: {e.status_code} - {e.message}")

Best Practices

Rate Limiting

Kwork doesn't have official rate limits, but be respectful:

import asyncio

for page in range(1, 11):
    catalog = await client.catalog.get_list(page=page)
    await asyncio.sleep(0.5)  # 500ms delay

Session Management

Always use context manager for automatic cleanup:

async with await KworkClient.login("user", "pass") as client:
    # Client automatically closed
    pass

Save Token

Save token after first login to avoid repeated authentication:

# First login
client = await KworkClient.login("user", "pass")
save_token(client.token)  # Save to secure storage

# Later
client = KworkClient(token=load_token())