much-data/kwork-api
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
bc951cc763
kwork-api/api_reference.md
root bc951cc763 docs: полная документация всех API классов 
Добавлены подробные docstrings для:

UserAPI:
- get_info(), get_reviews(), get_favorite_kworks()

ReferenceAPI:
- get_cities(), get_countries(), get_timezones()
- get_features(), get_public_features(), get_badges_info()

NotificationsAPI:
- get_list(), fetch(), get_dialogs(), get_blocked_dialogs()

OtherAPI:
- get_wants(), get_wants_status(), get_kworks_status()
- get_offers(), get_exchange_info(), get_channel()
- get_in_app_notification(), get_security_user_data()
- is_dialog_allow(), get_viewed_kworks()
- get_favorite_categories(), update_settings()
- go_offline(), get_actor()

API property accessor'ы:
- catalog, projects, user, reference, notifications, other

Все методы задокументированы на русском с примерами.
2026-03-23 04:27:27 +00:00

49 KiB
Raw Blame History

Table of Contents

Module kwork_api

Kwork.ru API Client

Unofficial Python client for Kwork.ru API.

Example:

from kwork_api import KworkClient

Login with credentials

client = await KworkClient.login("username", "password")

Or restore from token

client = KworkClient(token="your_web_auth_token")

Get catalog

catalog = await client.catalog.get_list(page=1)

KworkClient

KworkError

KworkAuthError

KworkApiError

__version__

__all__

Module kwork_api.client

Kwork API Client.

Main client class with authentication and all API endpoints.

logging

Any

Optional

httpx

HttpUrl

KworkApiError

KworkAuthError

KworkError

KworkNetworkError

KworkNotFoundError

KworkRateLimitError

KworkValidationError

APIErrorResponse

AuthResponse

Badge

CatalogResponse

City

Country

DataResponse

Dialog

Feature

Kwork

KworkDetails

NotificationsResponse

Project

ProjectsResponse

Review

ReviewsResponse

TimeZone

logger

KworkClient

class KworkClient()

Асинхронный клиент для Kwork.ru API.

Предоставляет доступ ко всем основным эндпоинтам Kwork API:

  • Каталог кворков и поиск
  • Биржа проектов (фриланс заказы)
  • Пользовательские данные и отзывы
  • Уведомления и сообщения
  • Справочные данные (города, страны, категории)

Аутентификация: Клиент использует двухэтапную аутентификацию Kwork:

  1. POST /signIn — получение session cookies
  2. POST /getWebAuthToken — получение web_auth_token

Примеры использования:

Вход по логину/паролю

async with await KworkClient.login("username", "password") as client: catalog = await client.catalog.get_list(page=1)

Восстановление сессии по токену

client = KworkClient(token="saved_web_auth_token") user_info = await client.user.get_info()

Работа с проектами

projects = await client.projects.get_list(page=1) my_orders = await client.projects.get_payer_orders()

Attributes:

  • catalog - Доступ к каталогу кворков
  • projects - Доступ к бирже проектов
  • user - Пользовательские эндпоинты
  • reference - Справочные данные
  • notifications - Уведомления и сообщения
  • other - Прочие эндпоинты

Notes:

Клиент поддерживает context manager для автоматического закрытия соединения. Рекомендуется использовать async with для корректного освобождения ресурсов.

BASE_URL

LOGIN_URL

TOKEN_URL

KworkClient.__init__

def __init__(token: Optional[str] = None,
             cookies: Optional[dict[str, str]] = None,
             timeout: float = 30.0,
             base_url: Optional[str] = None)

Инициализация клиента.

Создаёт неаутентифицированный клиент или восстанавливает сессию по ранее полученному токену.

Arguments:

  • token - Web auth token, полученный через getWebAuthToken или login(). Если указан, автоматически добавляется в cookies.
  • cookies - Session cookies из предыдущей аутентификации. Обычно не требуется — устанавливаются автоматически из token.
  • timeout - Таймаут HTTP запросов в секундах. По умолчанию 30 секунд.
  • base_url - Кастомный базовый URL. Используется только для тестирования.

Example:

Новый клиент без аутентификации

client = KworkClient()

Восстановление сессии

client = KworkClient(token="eyJ0eXAiOiJKV1QiLCJhbGc...")

Клиент с кастомным таймаутом

client = KworkClient(timeout=60.0)

Notes:

Для полноценной работы API требуется аутентификация. Используйте login() или передайте сохранённый token.

KworkClient.login

@classmethod
async def login(cls,
                username: str,
                password: str,
                timeout: float = 30.0) -> "KworkClient"

Аутентификация по логину и паролю.

Выполняет двухэтапный процесс аутентификации Kwork:

  1. POST /signIn — проверка учётных данных, получение session cookies
  2. POST /getWebAuthToken — обмен cookies на web_auth_token

Полученный токен и cookies сохраняются в клиенте для последующих запросов.

Arguments:

  • username - Логин или email аккаунта Kwork.
  • password - Пароль аккаунта Kwork.
  • timeout - Таймаут запросов в секундах. Применяется к каждому этапу.

Returns:

Полностью аутентифицированный экземпляр KworkClient, готовый к работе с API.

Raises:

  • KworkAuthError - Если логин/пароль неверны или токен не получен.
  • KworkNetworkError - Если произошла ошибка сети.

Example:

Базовое использование

client = await KworkClient.login("myuser", "mypassword")

С кастомным таймаутом

client = await KworkClient.login("user", "pass", timeout=60.0)

Сохранение токена для повторного использования

token = client._token

Позже: client = KworkClient(token=token)

Security: Пароль не сохраняется в клиенте. Только token и cookies. Рекомендуется сохранять token для повторного использования вместо хранения пароля.

Notes:

Токен имеет ограниченное время жизни. При получении 401 ошибки необходимо выполнить повторный login().

KworkClient.close

async def close() -> None

Close HTTP client.

KworkClient.__aenter__

async def __aenter__() -> "KworkClient"

KworkClient.__aexit__

async def __aexit__(*args: Any) -> None

CatalogAPI

class CatalogAPI()

API каталога кворков.

Предоставляет доступ к каталогу услуг Kwork:

  • Поиск и фильтрация кворков
  • Получение детальной информации
  • Категории и сортировка

Example:

Получить первую страницу каталога

catalog = await client.catalog.get_list(page=1)

Фильтрация по категории

catalog = await client.catalog.get_list(category_id=5)

Детали конкретного кворка

details = await client.catalog.get_details(kwork_id=12345)

CatalogAPI.__init__

def __init__(client: "KworkClient")

CatalogAPI.get_list

async def get_list(page: int = 1,
                   category_id: Optional[int] = None,
                   sort: str = "recommend") -> CatalogResponse

Получить список кворков из каталога.

Основной эндпоинт для поиска и просмотра кворков. Возвращает пагинированный список с возможностью фильтрации.

Arguments:

  • page - Номер страницы для пагинации (начиная с 1).
  • category_id - ID категории для фильтрации. Если None — все категории.
  • sort - Опция сортировки. Варианты:
    • "recommend" — по рекомендации (по умолчанию)
    • "price_asc" — по возрастанию цены
    • "price_desc" — по убыванию цены
    • "rating" — по рейтингу
    • "reviews" — по количеству отзывов
    • "newest" — по дате создания

Returns:

CatalogResponse содержащий:

  • kworks: список кворков на странице
  • pagination: информация о пагинации
  • filters: доступные фильтры
  • sort_options: доступные опции сортировки

Example:

Первая страница, сортировка по цене

response = await client.catalog.get_list( page=1, sort="price_asc" )

for kwork in response.kworks:

  • print(f"{kwork.title} - {kwork.price} RUB")

    Пагинация

    if response.pagination and response.pagination.has_next: next_page = await client.catalog.get_list(page=2)

CatalogAPI.get_details

async def get_details(kwork_id: int) -> KworkDetails

Получить полную информацию о кворке.

Возвращает расширенную информацию о кворке включая:

  • Полное описание и требования
  • Сроки выполнения и количество правок
  • Дополнительные опции (features)
  • FAQ от продавца

Arguments:

  • kwork_id - Уникальный идентификатор кворка.

Returns:

KworkDetails с полной информацией о кворке.

Raises:

  • KworkNotFoundError - Если кворк с таким ID не найден.

Example:

details = await client.catalog.get_details(12345)

  • print(f"Название - {details.title}")
  • print(f"Цена - {details.price} {details.currency}")
  • print(f"Срок - {details.delivery_time} дней")
  • print(f"Правки - {details.revisions}")

CatalogAPI.get_details_extra

async def get_details_extra(kwork_id: int) -> dict[str, Any]

Получить дополнительные детали кворка.

Возвращает расширенную информацию, которая не включена в основной ответ get_details(). Может содержать:

  • Дополнительные изображения
  • Видео обзоры
  • Детали пакетов услуг
  • Статистику продаж

Arguments:

  • kwork_id - Уникальный идентификатор кворка.

Returns:

Словарь с дополнительными данными. Структура зависит от конкретного кворка и не гарантируется стабильной.

Notes:

Этот эндпоинт возвращает "сырые" данные без валидации. Структура ответа может измениться без предупреждения.

ProjectsAPI

class ProjectsAPI()

API биржи проектов (фриланс заказы).

Предоставляет доступ к заказам на фриланс:

  • Просмотр открытых проектов
  • Заказы где вы заказчик (payer)
  • Заказы где вы исполнитель (worker)

Example:

Новые проекты

projects = await client.projects.get_list(page=1)

Мои заказы как заказчика

my_orders = await client.projects.get_payer_orders()

Мои заказы как исполнителя

my_work = await client.projects.get_worker_orders()

ProjectsAPI.__init__

def __init__(client: "KworkClient")

ProjectsAPI.get_list

async def get_list(page: int = 1,
                   category_id: Optional[int] = None) -> ProjectsResponse

Получить список проектов с биржи.

Основной эндпоинт для просмотра доступных заказов. Возвращает пагинированный список проектов.

Arguments:

  • page - Номер страницы (начиная с 1).
  • category_id - ID категории для фильтрации. Если None — все категории.

Returns:

ProjectsResponse содержащий:

  • projects: список проектов на странице
  • pagination: информация о пагинации

Example:

Все новые проекты

response = await client.projects.get_list(page=1)

for project in response.projects:

  • print(f"{project.title} - {project.budget} {project.budget_type}")

    Только категория "Разработка"

    dev_projects = await client.projects.get_list( page=1, category_id=5 )

ProjectsAPI.get_payer_orders

async def get_payer_orders() -> list[Project]

Получить заказы где вы являетесь заказчиком.

Возвращает все проекты, созданные текущим пользователем, независимо от их статуса (открыт, в работе, завершён).

Returns:

Список проектов где текущий пользователь — заказчик.

Example:

orders = await client.projects.get_payer_orders() for order in orders: print(f"Заказ #{order.id}: {order.status}")

ProjectsAPI.get_worker_orders

async def get_worker_orders() -> list[Project]

Получить заказы где вы являетесь исполнителем.

Возвращает все проекты, где текущий пользователь назначен исполнителем.

Returns:

Список проектов где текущий пользователь — исполнитель.

Example:

work = await client.projects.get_worker_orders() active = [p for p in work if p.status == "in_progress"] print(f"Активных заказов: {len(active)}")

UserAPI

class UserAPI()

User API endpoints.

UserAPI.__init__

def __init__(client: "KworkClient")

UserAPI.get_info

async def get_info() -> dict[str, Any]

Get current user info.

Returns:

User info dict

UserAPI.get_reviews

async def get_reviews(user_id: Optional[int] = None,
                      page: int = 1) -> ReviewsResponse

Get user reviews.

Arguments:

  • user_id - User ID (None for current user)
  • page - Page number

Returns:

ReviewsResponse

UserAPI.get_favorite_kworks

async def get_favorite_kworks() -> list[Kwork]

Get favorite kworks.

Returns:

List of kworks

ReferenceAPI

class ReferenceAPI()

Reference data (cities, countries, etc.) endpoints.

ReferenceAPI.__init__

def __init__(client: "KworkClient")

ReferenceAPI.get_cities

async def get_cities() -> list[City]

Get all cities.

ReferenceAPI.get_countries

async def get_countries() -> list[Country]

Get all countries.

ReferenceAPI.get_timezones

async def get_timezones() -> list[TimeZone]

Get all timezones.

ReferenceAPI.get_features

async def get_features() -> list[Feature]

Get available features.

ReferenceAPI.get_public_features

async def get_public_features() -> list[Feature]

Get public features.

ReferenceAPI.get_badges_info

async def get_badges_info() -> list[Badge]

Get badges info.

NotificationsAPI

class NotificationsAPI()

Notifications and messages endpoints.

NotificationsAPI.__init__

def __init__(client: "KworkClient")

NotificationsAPI.get_list

async def get_list() -> NotificationsResponse

Get notifications list.

NotificationsAPI.fetch

async def fetch() -> NotificationsResponse

Fetch new notifications.

NotificationsAPI.get_dialogs

async def get_dialogs() -> list[Dialog]

Get dialogs list.

NotificationsAPI.get_blocked_dialogs

async def get_blocked_dialogs() -> list[Dialog]

Get blocked dialogs.

OtherAPI

class OtherAPI()

Other API endpoints.

OtherAPI.__init__

def __init__(client: "KworkClient")

OtherAPI.get_wants

async def get_wants() -> dict[str, Any]

Get user wants.

OtherAPI.get_wants_status

async def get_wants_status() -> dict[str, Any]

Get wants status.

OtherAPI.get_kworks_status

async def get_kworks_status() -> dict[str, Any]

Get kworks status.

OtherAPI.get_offers

async def get_offers() -> dict[str, Any]

Get offers.

OtherAPI.get_exchange_info

async def get_exchange_info() -> dict[str, Any]

Get exchange info.

OtherAPI.get_channel

async def get_channel() -> dict[str, Any]

Get channel info.

OtherAPI.get_in_app_notification

async def get_in_app_notification() -> dict[str, Any]

Get in-app notification.

OtherAPI.get_security_user_data

async def get_security_user_data() -> dict[str, Any]

Get security user data.

OtherAPI.is_dialog_allow

async def is_dialog_allow(user_id: int) -> bool

Check if dialog is allowed.

OtherAPI.get_viewed_kworks

async def get_viewed_kworks() -> list[Kwork]

Get viewed kworks.

OtherAPI.get_favorite_categories

async def get_favorite_categories() -> list[int]

Get favorite categories.

OtherAPI.update_settings

async def update_settings(settings: dict[str, Any]) -> dict[str, Any]

Update user settings.

OtherAPI.go_offline

async def go_offline() -> dict[str, Any]

Set user status to offline.

OtherAPI.get_actor

async def get_actor() -> dict[str, Any]

Get actor info.

KworkClient.catalog

@property
def catalog() -> CatalogAPI

Catalog API.

KworkClient.projects

@property
def projects() -> ProjectsAPI

Projects API.

KworkClient.user

@property
def user() -> UserAPI

User API.

KworkClient.reference

@property
def reference() -> ReferenceAPI

Reference data API.

KworkClient.notifications

@property
def notifications() -> NotificationsAPI

Notifications API.

KworkClient.other

@property
def other() -> OtherAPI

Other endpoints.

Module kwork_api.models

Pydantic models for Kwork API responses.

All models follow the structure found in the HAR dump analysis.

datetime

Any

Optional

BaseModel

Field

KworkUser

class KworkUser(BaseModel)

User information.

id

username

avatar_url

is_online

rating

KworkCategory

class KworkCategory(BaseModel)

Category information.

id

name

slug

parent_id

Kwork

class Kwork(BaseModel)

Kwork (service) information.

id

title

description

price

currency

category_id

seller

images

rating

reviews_count

created_at

updated_at

KworkDetails

class KworkDetails(Kwork)

Extended kwork details.

full_description

requirements

delivery_time

in days

revisions

features

faq

PaginationInfo

class PaginationInfo(BaseModel)

Pagination metadata.

current_page

total_pages

total_items

items_per_page

has_next

has_prev

CatalogResponse

class CatalogResponse(BaseModel)

Catalog response with kworks and pagination.

kworks

pagination

filters

sort_options

Project

class Project(BaseModel)

Project (freelance order) information.

id

title

description

budget

budget_type

fixed, hourly

category_id

customer

status

open, in_progress, completed, cancelled

created_at

updated_at

bids_count

skills

ProjectsResponse

class ProjectsResponse(BaseModel)

Projects list response.

projects

pagination

Review

class Review(BaseModel)

Review information.

id

rating

comment

author

kwork_id

created_at

ReviewsResponse

class ReviewsResponse(BaseModel)

Reviews list response.

reviews

pagination

average_rating

Notification

class Notification(BaseModel)

Notification information.

id

type

message, order, system, etc.

title

message

is_read

created_at

link

NotificationsResponse

class NotificationsResponse(BaseModel)

Notifications list response.

notifications

unread_count

Dialog

class Dialog(BaseModel)

Dialog (chat) information.

id

participant

last_message

unread_count

updated_at

AuthResponse

class AuthResponse(BaseModel)

Authentication response.

success

user_id

username

web_auth_token

message

ErrorDetail

class ErrorDetail(BaseModel)

Error detail from API.

code

message

field

APIErrorResponse

class APIErrorResponse(BaseModel)

Standard API error response.

success

errors

message

City

class City(BaseModel)

City information.

id

name

country_id

Country

class Country(BaseModel)

Country information.

id

name

code

cities

TimeZone

class TimeZone(BaseModel)

Timezone information.

id

name

offset

e.g., "+03:00"

Feature

class Feature(BaseModel)

Feature/addon information.

id

name

description

price

type

extra, premium, etc.

Badge

class Badge(BaseModel)

User badge information.

id

name

description

icon_url

DataResponse

class DataResponse(BaseModel)

Generic data response wrapper.

success

data

message

Module kwork_api.errors

Kwork API exceptions.

All exceptions provide clear error messages for debugging.

Any

Optional

KworkError

class KworkError(Exception)

Base exception for all Kwork API errors.

KworkError.__init__

def __init__(message: str, response: Optional[Any] = None)

KworkError.__str__

def __str__() -> str

KworkAuthError

class KworkAuthError(KworkError)

Authentication/authorization error.

KworkAuthError.__init__

def __init__(message: str = "Authentication failed",
             response: Optional[Any] = None)

KworkAuthError.__str__

def __str__() -> str

KworkApiError

class KworkApiError(KworkError)

API request error (4xx, 5xx).

KworkApiError.__init__

def __init__(message: str,
             status_code: Optional[int] = None,
             response: Optional[Any] = None)

KworkApiError.__str__

def __str__() -> str

KworkNotFoundError

class KworkNotFoundError(KworkApiError)

Resource not found (404).

KworkNotFoundError.__init__

def __init__(resource: str, response: Optional[Any] = None)

KworkRateLimitError

class KworkRateLimitError(KworkApiError)

Rate limit exceeded (429).

KworkRateLimitError.__init__

def __init__(message: str = "Rate limit exceeded",
             response: Optional[Any] = None)

KworkValidationError

class KworkValidationError(KworkApiError)

Validation error (400).

KworkValidationError.__init__

def __init__(message: str = "Validation failed",
             fields: Optional[dict[str, list[str]]] = None,
             response: Optional[Any] = None)

KworkValidationError.__str__

def __str__() -> str

KworkNetworkError

class KworkNetworkError(KworkError)

Network/connection error.

KworkNetworkError.__init__

def __init__(message: str = "Network error", response: Optional[Any] = None)

KworkNetworkError.__str__

def __str__() -> str