Client API

kwork_api.client.KworkClient

KworkClient(
    token=None, cookies=None, timeout=30.0, base_url=None
)

Асинхронный клиент для 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:

Name	Type	Description
catalog	CatalogAPI	Доступ к каталогу кворков
projects	ProjectsAPI	Доступ к бирже проектов
user	UserAPI	Пользовательские эндпоинты
reference	ReferenceAPI	Справочные данные
notifications	NotificationsAPI	Уведомления и сообщения
other	OtherAPI	Прочие эндпоинты

Note

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

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

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

Parameters:

Name	Type	Description	Default
token	Optional[str]	Web auth token, полученный через getWebAuthToken или login(). Если указан, автоматически добавляется в cookies.	None
cookies	Optional[dict[str, str]]	Session cookies из предыдущей аутентификации. Обычно не требуется — устанавливаются автоматически из token.	None
timeout	float	Таймаут HTTP запросов в секундах. По умолчанию 30 секунд.	30.0
base_url	Optional[str]	Кастомный базовый URL. Используется только для тестирования.	None

Example

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

client = KworkClient()

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

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

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

client = KworkClient(timeout=60.0)

Note

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

Source code in src/kwork_api/client.py

def __init__(
    self,
    token: Optional[str] = None,
    cookies: Optional[dict[str, str]] = None,
    timeout: float = 30.0,
    base_url: Optional[str] = None,
):
    """
    Инициализация клиента.

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

    Args:
        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)

    Note:
        Для полноценной работы API требуется аутентификация.
        Используйте `login()` или передайте сохранённый token.
    """
    self.base_url = base_url or self.BASE_URL
    self.timeout = timeout
    self._token = token
    self._cookies = cookies or {}

    # Initialize HTTP client
    self._client: Optional[httpx.AsyncClient] = None

Attributes

catalog property

catalog

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

cookies property

cookies

Session cookies.

Returns:

Type	Description
dict[str, str]	Словарь cookies включая web_auth_token.

Example

Сохранение полной сессии

client = await KworkClient.login("user", "pass") creds = client.credentials

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

client = KworkClient(**creds)

credentials property

credentials

Учётные данные для восстановления сессии.

Returns:

Type	Description
dict[str, Optional[str]]	Словарь с token и cookies для передачи в KworkClient().

Example

Сохранение

client = await KworkClient.login("user", "pass") import json with open("session.json", "w") as f: json.dump(client.credentials, f)

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

with open("session.json") as f: creds = json.load(f) client = KworkClient(**creds)

notifications property

notifications

API уведомлений.

other property

other

Прочее API.

projects property

projects

API биржи проектов.

reference property

reference

Справочное API.

token property

token

Web auth token для аутентификации.

Returns:

Type	Description
Optional[str]	Токен или None если клиент не аутентифицирован.

Example

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

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

Позже: восстановление сессии

client = KworkClient(token=token)

user property

user

Пользовательское API.

Classes

CatalogAPI

CatalogAPI(client)

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)

Source code in src/kwork_api/client.py

def __init__(self, client: "KworkClient"):
    self.client = client

Functions

get_details async

get_details(kwork_id)

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

Возвращает расширенную информацию о кворке включая: - Полное описание и требования - Сроки выполнения и количество правок - Дополнительные опции (features) - FAQ от продавца

Parameters:

Name	Type	Description	Default
kwork_id	int	Уникальный идентификатор кворка.	required

Returns:

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

Raises:

Type	Description
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}")

Source code in src/kwork_api/client.py

async def get_details(self, kwork_id: int) -> KworkDetails:
    """
    Получить полную информацию о кворке.

    Возвращает расширенную информацию о кворке включая:
    - Полное описание и требования
    - Сроки выполнения и количество правок
    - Дополнительные опции (features)
    - FAQ от продавца

    Args:
        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}")
    """
    data = await self.client._request(
        "POST",
        "/getKworkDetails",
        json={"kwork_id": kwork_id},
    )
    return KworkDetails.model_validate(data)

get_details_extra async

get_details_extra(kwork_id)

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

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

Parameters:

Name	Type	Description	Default
kwork_id	int	Уникальный идентификатор кворка.	required

Returns:

Type	Description
dict[str, Any]	Словарь с дополнительными данными. Структура зависит
dict[str, Any]	от конкретного кворка и не гарантируется стабильной.

Note

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

Source code in src/kwork_api/client.py

async def get_details_extra(self, kwork_id: int) -> dict[str, Any]:
    """
    Получить дополнительные детали кворка.

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

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

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

    Note:
        Этот эндпоинт возвращает "сырые" данные без валидации.
        Структура ответа может измениться без предупреждения.
    """
    return await self.client._request(
        "POST",
        "/getKworkDetailsExtra",
        json={"kwork_id": kwork_id},
    )

get_list async

get_list(page=1, category_id=None, sort='recommend')

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

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

Parameters:

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

Returns:

Type	Description
CatalogResponse	CatalogResponse содержащий:
CatalogResponse	kworks: список кворков на странице
CatalogResponse	pagination: информация о пагинации
CatalogResponse	filters: доступные фильтры
CatalogResponse	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)

Source code in src/kwork_api/client.py

async def get_list(
    self,
    page: int = 1,
    category_id: Optional[int] = None,
    sort: str = "recommend",
) -> CatalogResponse:
    """
    Получить список кворков из каталога.

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

    Args:
        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)
    """
    data = await self.client._request(
        "POST",
        "/catalogMainv2",
        json={
            "page": page,
            "category_id": category_id,
            "sort": sort,
        },
    )
    return CatalogResponse.model_validate(data)

NotificationsAPI

NotificationsAPI(client)

API уведомлений и сообщений.

Предоставляет доступ к системе уведомлений Kwork: - Список уведомлений - Получение новых уведомлений - Диалоги с пользователями - Заблокированные диалоги

Example

Все уведомления

notifications = await client.notifications.get_list()

Новые уведомления

new = await client.notifications.fetch()

Диалоги

dialogs = await client.notifications.get_dialogs()

Source code in src/kwork_api/client.py

def __init__(self, client: "KworkClient"):
    self.client = client

Functions

fetch async

fetch()

Получить новые уведомления.

Отличается от get_list() тем, что возвращает только уведомления, появившиеся с момента последнего запроса. Также может обновлять счётчик непрочитанных.

Returns:

Type	Description
NotificationsResponse	NotificationsResponse с новыми уведомлениями.

Example

new_notifs = await client.notifications.fetch() if new_notifs.unread_count > 0: print(f"У вас {new_notifs.unread_count} новых уведомлений!")

Source code in src/kwork_api/client.py

async def fetch(self) -> NotificationsResponse:
    """
    Получить новые уведомления.

    Отличается от get_list() тем, что возвращает только
    уведомления, появившиеся с момента последнего запроса.
    Также может обновлять счётчик непрочитанных.

    Returns:
        NotificationsResponse с новыми уведомлениями.

    Example:
        new_notifs = await client.notifications.fetch()
        if new_notifs.unread_count > 0:
            print(f"У вас {new_notifs.unread_count} новых уведомлений!")
    """
    data = await self.client._request("POST", "/notificationsFetch")
    return NotificationsResponse.model_validate(data)

get_blocked_dialogs async

get_blocked_dialogs()

Получить список заблокированных диалогов.

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

Returns:

Type	Description
list[Dialog]	Список заблокированных диалогов.

Example

blocked = await client.notifications.get_blocked_dialogs() print(f"Заблокировано: {len(blocked)} пользователей")

Source code in src/kwork_api/client.py

async def get_blocked_dialogs(self) -> list[Dialog]:
    """
    Получить список заблокированных диалогов.

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

    Returns:
        Список заблокированных диалогов.

    Example:
        blocked = await client.notifications.get_blocked_dialogs()
        print(f"Заблокировано: {len(blocked)} пользователей")
    """
    data = await self.client._request("POST", "/blockedDialogList")
    return [Dialog.model_validate(d) for d in data.get("dialogs", [])]

get_dialogs async

get_dialogs()

Получить список диалогов (чатов).

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

Returns:

Type	Description
list[Dialog]	Список диалогов с последней перепиской.

Example

dialogs = await client.notifications.get_dialogs() for d in dialogs: print(f"С {d.participant.username}: {d.last_message}")

Source code in src/kwork_api/client.py

async def get_dialogs(self) -> list[Dialog]:
    """
    Получить список диалогов (чатов).

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

    Returns:
        Список диалогов с последней перепиской.

    Example:
        dialogs = await client.notifications.get_dialogs()
        for d in dialogs:
            print(f"С {d.participant.username}: {d.last_message}")
    """
    data = await self.client._request("POST", "/dialogs")
    return [Dialog.model_validate(d) for d in data.get("dialogs", [])]

get_list async

get_list()

Получить список всех уведомлений.

Возвращает все уведомления пользователя с информацией о прочтении.

Returns:

Type	Description
NotificationsResponse	NotificationsResponse содержащий:
NotificationsResponse	notifications: список уведомлений
NotificationsResponse	unread_count: количество непрочитанных

Example

notifs = await client.notifications.get_list() print(f"Непрочитанных: {notifs.unread_count}")

for n in notifs.notifications: if not n.is_read: print(f"Новое: {n.title}")

Source code in src/kwork_api/client.py

async def get_list(self) -> NotificationsResponse:
    """
    Получить список всех уведомлений.

    Возвращает все уведомления пользователя с информацией
    о прочтении.

    Returns:
        NotificationsResponse содержащий:
        - notifications: список уведомлений
        - unread_count: количество непрочитанных

    Example:
        notifs = await client.notifications.get_list()
        print(f"Непрочитанных: {notifs.unread_count}")

        for n in notifs.notifications:
            if not n.is_read:
                print(f"Новое: {n.title}")
    """
    data = await self.client._request("POST", "/notifications")
    return NotificationsResponse.model_validate(data)

OtherAPI

OtherAPI(client)

Прочее API.

Вспомогательные эндпоинты которые не вошли в другие категории: - Пользовательские настройки и предпочтения (wants) - Статусы кворков и заказов - Персональные предложения (offers) - Настройки профиля - Статус онлайн/оффлайн

Example

Пользовательские предпочтения

wants = await client.other.get_wants()

Статус кворков

status = await client.other.get_kworks_status()

Установить статус оффлайн

await client.other.go_offline()

Source code in src/kwork_api/client.py

def __init__(self, client: "KworkClient"):
    self.client = client

Functions

get_actor async

get_actor()

Получить информацию об актёре (текущем пользователе).

Returns:

Type	Description
dict[str, Any]	Данные актёра/пользователя.

Source code in src/kwork_api/client.py

async def get_actor(self) -> dict[str, Any]:
    """
    Получить информацию об актёре (текущем пользователе).

    Returns:
        Данные актёра/пользователя.
    """
    return await self.client._request("POST", "/actor")

get_channel async

get_channel()

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

Returns:

Type	Description
dict[str, Any]	Данные канала (если есть).

Source code in src/kwork_api/client.py

async def get_channel(self) -> dict[str, Any]:
    """
    Получить информацию о канале пользователя.

    Returns:
        Данные канала (если есть).
    """
    return await self.client._request("POST", "/getChannel")

get_exchange_info async

get_exchange_info()

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

Returns:

Type	Description
dict[str, Any]	Информация о курсах валют и обмене.

Source code in src/kwork_api/client.py

async def get_exchange_info(self) -> dict[str, Any]:
    """
    Получить информацию об обмене валюты.

    Returns:
        Информация о курсах валют и обмене.
    """
    return await self.client._request("POST", "/exchangeInfo")

get_favorite_categories async

get_favorite_categories()

Получить ID избранных категорий.

Returns:

Type	Description
list[int]	Список ID категорий, добавленных в избранное.

Example

cats = await client.other.get_favorite_categories() print(f"Избранные категории: {cats}")

Source code in src/kwork_api/client.py

async def get_favorite_categories(self) -> list[int]:
    """
    Получить ID избранных категорий.

    Returns:
        Список ID категорий, добавленных в избранное.

    Example:
        cats = await client.other.get_favorite_categories()
        print(f"Избранные категории: {cats}")
    """
    data = await self.client._request("POST", "/favoriteCategories")
    return data.get("categories", [])

get_in_app_notification async

get_in_app_notification()

Получить внутриприложенное уведомление.

Returns:

Type	Description
dict[str, Any]	Данные in-app уведомления.

Source code in src/kwork_api/client.py

async def get_in_app_notification(self) -> dict[str, Any]:
    """
    Получить внутриприложенное уведомление.

    Returns:
        Данные in-app уведомления.
    """
    return await self.client._request("POST", "/getInAppNotification")

get_kworks_status async

get_kworks_status()

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

Возвращает информацию о статусах всех кворков текущего пользователя (активен, на модерации, и т.д.).

Returns:

Type	Description
dict[str, Any]	Словарь со статусами кворков.

Example

status = await client.other.get_kworks_status() print(status)

Source code in src/kwork_api/client.py

async def get_kworks_status(self) -> dict[str, Any]:
    """
    Получить статусы кворков пользователя.

    Возвращает информацию о статусах всех кворков
    текущего пользователя (активен, на модерации, и т.д.).

    Returns:
        Словарь со статусами кворков.

    Example:
        status = await client.other.get_kworks_status()
        print(status)
    """
    return await self.client._request("POST", "/kworksStatusList")

get_offers async

get_offers()

Получить персональные предложения.

Returns:

Type	Description
dict[str, Any]	Список персональных предложений от Kwork.

Source code in src/kwork_api/client.py

async def get_offers(self) -> dict[str, Any]:
    """
    Получить персональные предложения.

    Returns:
        Список персональных предложений от Kwork.
    """
    return await self.client._request("POST", "/offers")

get_security_user_data async

get_security_user_data()

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

Returns:

Type	Description
dict[str, Any]	Информация о безопасности аккаунта.

Source code in src/kwork_api/client.py

async def get_security_user_data(self) -> dict[str, Any]:
    """
    Получить данные безопасности пользователя.

    Returns:
        Информация о безопасности аккаунта.
    """
    return await self.client._request("POST", "/getSecurityUserData")

get_viewed_kworks async

get_viewed_kworks()

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

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

Returns:

Type	Description
list[Kwork]	Список просмотренных кворков.

Example

viewed = await client.other.get_viewed_kworks() print(f"Просмотрено: {len(viewed)} кворков")

Source code in src/kwork_api/client.py

async def get_viewed_kworks(self) -> list[Kwork]:
    """
    Получить просмотренные кворки.

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

    Returns:
        Список просмотренных кворков.

    Example:
        viewed = await client.other.get_viewed_kworks()
        print(f"Просмотрено: {len(viewed)} кворков")
    """
    data = await self.client._request("POST", "/viewedCatalogKworks")
    return [Kwork.model_validate(k) for k in data.get("kworks", [])]

get_wants async

get_wants()

Получить пользовательские предпочтения (wants).

Wants — это настройки интересов пользователя: - Предпочитаемые категории - Ключевые слова для мониторинга - Фильтры для поиска

Returns:

Type	Description
dict[str, Any]	Словарь с настройками предпочтений.

Example

wants = await client.other.get_wants() print(wants)

Source code in src/kwork_api/client.py

async def get_wants(self) -> dict[str, Any]:
    """
    Получить пользовательские предпочтения (wants).

    Wants — это настройки интересов пользователя:
    - Предпочитаемые категории
    - Ключевые слова для мониторинга
    - Фильтры для поиска

    Returns:
        Словарь с настройками предпочтений.

    Example:
        wants = await client.other.get_wants()
        print(wants)
    """
    return await self.client._request("POST", "/myWants")

get_wants_status async

get_wants_status()

Получить статус предпочтений.

Returns:

Type	Description
dict[str, Any]	Статус wants с метаданными.

Source code in src/kwork_api/client.py

async def get_wants_status(self) -> dict[str, Any]:
    """
    Получить статус предпочтений.

    Returns:
        Статус wants с метаданными.
    """
    return await self.client._request("POST", "/wantsStatusList")

go_offline async

go_offline()

Установить статус пользователя "оффлайн".

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

Returns:

Type	Description
dict[str, Any]	Подтверждение изменения статуса.

Example

await client.other.go_offline()

Source code in src/kwork_api/client.py

async def go_offline(self) -> dict[str, Any]:
    """
    Установить статус пользователя "оффлайн".

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

    Returns:
        Подтверждение изменения статуса.

    Example:
        await client.other.go_offline()
    """
    return await self.client._request("POST", "/offline")

is_dialog_allow async

is_dialog_allow(user_id)

Проверить возможность начала диалога с пользователем.

Parameters:

Name	Type	Description	Default
user_id	int	ID пользователя для проверки.	required

Returns:

Type	Description
bool	True если диалог разрешён, False иначе.

Example

allowed = await client.other.is_dialog_allow(12345) if allowed: print("Можно написать сообщение")

Source code in src/kwork_api/client.py

async def is_dialog_allow(self, user_id: int) -> bool:
    """
    Проверить возможность начала диалога с пользователем.

    Args:
        user_id: ID пользователя для проверки.

    Returns:
        True если диалог разрешён, False иначе.

    Example:
        allowed = await client.other.is_dialog_allow(12345)
        if allowed:
            print("Можно написать сообщение")
    """
    data = await self.client._request(
        "POST",
        "/isDialogAllow",
        json={"user_id": user_id},
    )
    return data.get("allowed", False)

update_settings async

update_settings(settings)

Обновить настройки пользователя.

Parameters:

Name	Type	Description	Default
settings	dict[str, Any]	Словарь с настройками для обновления. Структура зависит от конкретных настроек.	required

Returns:

Type	Description
dict[str, Any]	Ответ API с подтверждением обновления.

Example

await client.other.update_settings({ "email_notifications": True, "language": "ru" })

Source code in src/kwork_api/client.py

async def update_settings(self, settings: dict[str, Any]) -> dict[str, Any]:
    """
    Обновить настройки пользователя.

    Args:
        settings: Словарь с настройками для обновления.
                 Структура зависит от конкретных настроек.

    Returns:
        Ответ API с подтверждением обновления.

    Example:
        await client.other.update_settings({
            "email_notifications": True,
            "language": "ru"
        })
    """
    return await self.client._request("POST", "/updateSettings", json=settings)

validate_text async

validate_text(text, context=None)

Проверить текст на соответствие требованиям Kwork.

Эндпоинт валидации текста используется для проверки: - Описаний кворков - Текстов проектов - Сообщений и отзывов

Находит потенциальные проблемы: - Запрещённые слова и контакты - Нарушения правил площадки - Проблемы с форматированием

Parameters:

Name	Type	Description	Default
text	str	Текст для проверки.	required
context	Optional[str]	Контекст использования (опционально). Например: "kwork_description", "project_text", "message".	None

Returns:

Type	Description
ValidationResponse	ValidationResponse с результатами валидации.

Example

result = await client.other.validate_text( "Отличный сервис, звоните +7-999-000-00-00" ) if not result.is_valid: print("Текст не прошёл валидацию:") for issue in result.issues: print(f" - {issue.message}")

Source code in src/kwork_api/client.py

async def validate_text(self, text: str, context: Optional[str] = None) -> ValidationResponse:
    """
    Проверить текст на соответствие требованиям Kwork.

    Эндпоинт валидации текста используется для проверки:
    - Описаний кворков
    - Текстов проектов
    - Сообщений и отзывов

    Находит потенциальные проблемы:
    - Запрещённые слова и контакты
    - Нарушения правил площадки
    - Проблемы с форматированием

    Args:
        text: Текст для проверки.
        context: Контекст использования (опционально).
                Например: "kwork_description", "project_text", "message".

    Returns:
        ValidationResponse с результатами валидации.

    Example:
        result = await client.other.validate_text(
            "Отличный сервис, звоните +7-999-000-00-00"
        )
        if not result.is_valid:
            print("Текст не прошёл валидацию:")
            for issue in result.issues:
                print(f"  - {issue.message}")
    """
    payload = {"text": text}
    if context:
        payload["context"] = context

    data = await self.client._request(
        "POST",
        "/api/validation/checktext",
        json=payload,
    )
    return ValidationResponse.model_validate(data)

ProjectsAPI

ProjectsAPI(client)

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()

Source code in src/kwork_api/client.py

def __init__(self, client: "KworkClient"):
    self.client = client

Functions

get_list async

get_list(page=1, category_id=None)

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

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

Parameters:

Name	Type	Description	Default
page	int	Номер страницы (начиная с 1).	1
category_id	Optional[int]	ID категории для фильтрации. Если None — все категории.	None

Returns:

Type	Description
ProjectsResponse	ProjectsResponse содержащий:
ProjectsResponse	projects: список проектов на странице
ProjectsResponse	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 )

Source code in src/kwork_api/client.py

async def get_list(
    self,
    page: int = 1,
    category_id: Optional[int] = None,
) -> ProjectsResponse:
    """
    Получить список проектов с биржи.

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

    Args:
        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
        )
    """
    data = await self.client._request(
        "POST",
        "/projects",
        json={
            "page": page,
            "category_id": category_id,
        },
    )
    return ProjectsResponse.model_validate(data)

get_payer_orders async

get_payer_orders()

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

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

Returns:

Type	Description
list[Project]	Список проектов где текущий пользователь — заказчик.

Example

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

Source code in src/kwork_api/client.py

async def get_payer_orders(self) -> list[Project]:
    """
    Получить заказы где вы являетесь заказчиком.

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

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

    Example:
        orders = await client.projects.get_payer_orders()
        for order in orders:
            print(f"Заказ #{order.id}: {order.status}")
    """
    data = await self.client._request("POST", "/payerOrders")
    return [Project.model_validate(p) for p in data.get("orders", [])]

get_worker_orders async

get_worker_orders()

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

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

Returns:

Type	Description
list[Project]	Список проектов где текущий пользователь — исполнитель.

Example

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

Source code in src/kwork_api/client.py

async def get_worker_orders(self) -> 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)}")
    """
    data = await self.client._request("POST", "/workerOrders")
    return [Project.model_validate(p) for p in data.get("orders", [])]

ReferenceAPI

ReferenceAPI(client)

Справочное API.

Предоставляет доступ к справочным данным Kwork: - Города, страны, часовые пояса - Доступные функции и дополнения - Значки пользователей

Эти данные редко меняются и могут быть закэшированы.

Example

Все страны

countries = await client.reference.get_countries()

Все города

cities = await client.reference.get_cities()

Доступные фичи

features = await client.reference.get_features()

Source code in src/kwork_api/client.py

def __init__(self, client: "KworkClient"):
    self.client = client

Functions

get_badges_info async

get_badges_info()

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

Значки (badges) отображают достижения и статусы: - "Профессионал" - "Быстрый ответ" - "Надёжный продавец" - и т.д.

Returns:

Type	Description
list[Badge]	Список значков с описаниями и иконками.

Example

badges = await client.reference.get_badges_info() for badge in badges: print(f"{badge.name}: {badge.description}")

Source code in src/kwork_api/client.py

async def get_badges_info(self) -> list[Badge]:
    """
    Получить информацию о значках пользователей.

    Значки (badges) отображают достижения и статусы:
    - "Профессионал"
    - "Быстрый ответ"
    - "Надёжный продавец"
    - и т.д.

    Returns:
        Список значков с описаниями и иконками.

    Example:
        badges = await client.reference.get_badges_info()
        for badge in badges:
            print(f"{badge.name}: {badge.description}")
    """
    data = await self.client._request("POST", "/getBadgesInfo")
    return [Badge.model_validate(b) for b in data.get("badges", [])]

get_cities async

get_cities()

Получить список всех городов.

Returns:

Type	Description
list[City]	Список всех городов из справочника Kwork.

Example

cities = await client.reference.get_cities() moscow = next(c for c in cities if c.name == "Москва")

Source code in src/kwork_api/client.py

async def get_cities(self) -> list[City]:
    """
    Получить список всех городов.

    Returns:
        Список всех городов из справочника Kwork.

    Example:
        cities = await client.reference.get_cities()
        moscow = next(c for c in cities if c.name == "Москва")
    """
    data = await self.client._request("POST", "/cities")
    return [City.model_validate(c) for c in data.get("cities", [])]

get_countries async

get_countries()

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

Returns:

Type	Description
list[Country]	Список всех стран с кодами и городами.

Example

countries = await client.reference.get_countries() russia = next(c for c in countries if c.code == "RU")

Source code in src/kwork_api/client.py

async def get_countries(self) -> list[Country]:
    """
    Получить список всех стран.

    Returns:
        Список всех стран с кодами и городами.

    Example:
        countries = await client.reference.get_countries()
        russia = next(c for c in countries if c.code == "RU")
    """
    data = await self.client._request("POST", "/countries")
    return [Country.model_validate(c) for c in data.get("countries", [])]

get_features async

get_features()

Получить доступные дополнительные функции (features).

Features — это платные дополнения к кворкам: - Увеличенные сроки - Дополнительные правки - Приоритетная поддержка - и т.д.

Returns:

Type	Description
list[Feature]	Список доступных features с названиями и ценами.

Example

features = await client.reference.get_features() for f in features: print(f"{f.name}: {f.price} RUB")

Source code in src/kwork_api/client.py

async def get_features(self) -> list[Feature]:
    """
    Получить доступные дополнительные функции (features).

    Features — это платные дополнения к кворкам:
    - Увеличенные сроки
    - Дополнительные правки
    - Приоритетная поддержка
    - и т.д.

    Returns:
        Список доступных features с названиями и ценами.

    Example:
        features = await client.reference.get_features()
        for f in features:
            print(f"{f.name}: {f.price} RUB")
    """
    data = await self.client._request("POST", "/getAvailableFeatures")
    return [Feature.model_validate(f) for f in data.get("features", [])]

get_public_features async

get_public_features()

Получить публичные функции.

Аналогично get_features(), но возвращает только публично доступные опции.

Returns:

Type	Description
list[Feature]	Список публичных features.

Source code in src/kwork_api/client.py

async def get_public_features(self) -> list[Feature]:
    """
    Получить публичные функции.

    Аналогично get_features(), но возвращает только
    публично доступные опции.

    Returns:
        Список публичных features.
    """
    data = await self.client._request("POST", "/getPublicFeatures")
    return [Feature.model_validate(f) for f in data.get("features", [])]

get_timezones async

get_timezones()

Получить список всех часовых поясов.

Returns:

Type	Description
list[TimeZone]	Список часовых поясов с названиями и смещениями.

Example

timezones = await client.reference.get_timezones() msks = next(tz for tz in timezones if "Moscow" in tz.name)

Source code in src/kwork_api/client.py

async def get_timezones(self) -> list[TimeZone]:
    """
    Получить список всех часовых поясов.

    Returns:
        Список часовых поясов с названиями и смещениями.

    Example:
        timezones = await client.reference.get_timezones()
        msks = next(tz for tz in timezones if "Moscow" in tz.name)
    """
    data = await self.client._request("POST", "/timezones")
    return [TimeZone.model_validate(t) for t in data.get("timezones", [])]

UserAPI

UserAPI(client)

Пользовательское API.

Предоставляет доступ к данным текущего пользователя: - Профиль и информация об аккаунте - Отзывы (полученные и оставленные) - Избранные кворки

Example

Информация о пользователе

info = await client.user.get_info()

Мои отзывы

reviews = await client.user.get_reviews()

Избранные кворки

favorites = await client.user.get_favorite_kworks()

Source code in src/kwork_api/client.py

def __init__(self, client: "KworkClient"):
    self.client = client

Functions

get_favorite_kworks async

get_favorite_kworks()

Получить список избранных кворков.

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

Returns:

Type	Description
list[Kwork]	Список избранных кворков.

Example

favorites = await client.user.get_favorite_kworks() for kwork in favorites: print(f"{kwork.title}: {kwork.price} RUB")

Source code in src/kwork_api/client.py

async def get_favorite_kworks(self) -> list[Kwork]:
    """
    Получить список избранных кворков.

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

    Returns:
        Список избранных кворков.

    Example:
        favorites = await client.user.get_favorite_kworks()
        for kwork in favorites:
            print(f"{kwork.title}: {kwork.price} RUB")
    """
    data = await self.client._request("POST", "/favoriteKworks")
    return [Kwork.model_validate(k) for k in data.get("kworks", [])]

get_info async

get_info()

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

Возвращает основные данные аккаунта: - ID, username, email - Баланс, рейтинг - Статус верификации - Настройки профиля

Returns:

Type	Description
dict[str, Any]	Словарь с информацией о пользователе.
dict[str, Any]	Структура зависит от ответа API.

Example

info = await client.user.get_info() print(f"User: {info.get('username')}") print(f"Balance: {info.get('balance')} RUB")

Source code in src/kwork_api/client.py

async def get_info(self) -> dict[str, Any]:
    """
    Получить информацию о текущем пользователе.

    Возвращает основные данные аккаунта:
    - ID, username, email
    - Баланс, рейтинг
    - Статус верификации
    - Настройки профиля

    Returns:
        Словарь с информацией о пользователе.
        Структура зависит от ответа API.

    Example:
        info = await client.user.get_info()
        print(f"User: {info.get('username')}")
        print(f"Balance: {info.get('balance')} RUB")
    """
    return await self.client._request("POST", "/user")

get_reviews async

get_reviews(user_id=None, page=1)

Получить отзывы пользователя.

Если user_id не указан — возвращает отзывы текущего пользователя. Если указан — отзывы другого пользователя по ID.

Parameters:

Name	Type	Description	Default
user_id	Optional[int]	ID пользователя. Если None — текущий пользователь.	None
page	int	Номер страницы для пагинации (начиная с 1).	1

Returns:

Type	Description
ReviewsResponse	ReviewsResponse содержащий:
ReviewsResponse	reviews: список отзывов на странице
ReviewsResponse	pagination: информация о пагинации
ReviewsResponse	average_rating: средний рейтинг

Example

Мои отзывы

my_reviews = await client.user.get_reviews()

Отзывы другого пользователя

user_reviews = await client.user.get_reviews(user_id=12345)

С пагинацией

page2 = await client.user.get_reviews(page=2)

Source code in src/kwork_api/client.py

async def get_reviews(
    self,
    user_id: Optional[int] = None,
    page: int = 1,
) -> ReviewsResponse:
    """
    Получить отзывы пользователя.

    Если user_id не указан — возвращает отзывы текущего пользователя.
    Если указан — отзывы другого пользователя по ID.

    Args:
        user_id: ID пользователя. Если None — текущий пользователь.
        page: Номер страницы для пагинации (начиная с 1).

    Returns:
        ReviewsResponse содержащий:
        - reviews: список отзывов на странице
        - pagination: информация о пагинации
        - average_rating: средний рейтинг

    Example:
        # Мои отзывы
        my_reviews = await client.user.get_reviews()

        # Отзывы другого пользователя
        user_reviews = await client.user.get_reviews(user_id=12345)

        # С пагинацией
        page2 = await client.user.get_reviews(page=2)
    """
    data = await self.client._request(
        "POST",
        "/userReviews",
        json={"user_id": user_id, "page": page},
    )
    return ReviewsResponse.model_validate(data)

Functions

close async

close()

Close HTTP client.

Source code in src/kwork_api/client.py

async def close(self) -> None:
    """Close HTTP client."""
    if self._client and not self._client.is_closed:
        await self._client.aclose()

login async classmethod

login(username, password, timeout=30.0)

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

Выполняет двухэтапный процесс аутентификации Kwork: 1. POST /signIn — проверка учётных данных, получение session cookies 2. POST /getWebAuthToken — обмен cookies на web_auth_token

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

Parameters:

Name	Type	Description	Default
username	str	Логин или email аккаунта Kwork.	required
password	str	Пароль аккаунта Kwork.	required
timeout	float	Таймаут запросов в секундах. Применяется к каждому этапу.	30.0

Returns:

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

Raises:

Type	Description
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 для повторного использования вместо хранения пароля.

Note

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

Source code in src/kwork_api/client.py

@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 сохраняются в клиенте для последующих запросов.

    Args:
        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 для повторного использования
        вместо хранения пароля.

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

    try:
        async with client._get_httpx_client() as http_client:
            # Step 1: Login to get session cookies
            login_data = {
                "login_or_email": username,
                "password": password,
            }

            response = await http_client.post(
                cls.LOGIN_URL,
                data=login_data,
                headers={"Referer": "https://kwork.ru/"},
            )

            if response.status_code != 200:
                raise KworkAuthError(f"Login failed: {response.status_code}")

            # Extract cookies
            cookies = dict(response.cookies)

            if "userId" not in cookies:
                raise KworkAuthError("Login failed: no userId in cookies")

            # Step 2: Get web auth token
            token_response = await http_client.post(
                cls.TOKEN_URL,
                json={},
            )

            if token_response.status_code != 200:
                raise KworkAuthError(f"Token request failed: {token_response.status_code}")

            token_data = token_response.json()
            web_token = token_data.get("web_auth_token")

            if not web_token:
                raise KworkAuthError("No web_auth_token in response")

            # Create new client with token
            return cls(token=web_token, cookies=cookies, timeout=timeout)

    except httpx.RequestError as e:
        raise KworkNetworkError(f"Login request failed: {e}")