hh-api-client 0.1.4

Typed, safe HeadHunter (hh.ru / hh.uz) API client with optional Django integration.

hh-api-client

Typed, safe HeadHunter (hh.ru / hh.uz) API client with optional Django integration.

Installation

pip install hh-api-client

From a Git repository (for example, the main GitHub repo):

pip install git+https://github.com/your-username/hh-api-client.git

For local development:

pip install -e .

Quick start

from hh_api_client import HHAPIClient

client = HHAPIClient(access_token="YOUR_HH_ACCESS_TOKEN")

employer = client.get_employer_info()
print(employer["id"], employer["name"])

With a token provider (recommended)

You can pass any object that implements:

• get_valid_access_token() -> str
• refresh_access_token() -> str

This matches your existing OrganizationHHAccount pattern.

from hh_api_client import HHAPIClient

client = HHAPIClient(organization_hh_account=my_hh_account_instance)

# Example: create vacancy
vacancy_data = {
    "name": "Python Developer",
    "description": "<p>We are looking for a Python developer...</p>",
    "area": {"id": "2759"},  # e.g. Tashkent
    "employment": {"id": "full"},
    "schedule": {"id": "fullDay"},
}

response = client.create_vacancy(vacancy_data)
print(response["id"])

Django integration example

Assuming you have a model like OrganizationHHAccount with methods:

• get_valid_access_token()
• refresh_access_token()

and you store it per organization:

from hh_api_client import HHAPIClient
from organization_app.models import OrganizationHHAccount


def get_hh_client_for_organization(organization) -> HHAPIClient:
    hh_account = OrganizationHHAccount.objects.get(organization=organization, archived=False)
    return HHAPIClient(organization_hh_account=hh_account)

Configuring base URL (hh.uz vs hh.ru)

By default this client uses the Uzbekistan API base URL https://api.hh.uz because that is a common production setup.

If you need to change it (for example to https://api.hh.ru), use HHAPIClientConfig:

from django.conf import settings
from hh_api_client import HHAPIClient, HHAPIClientConfig
from organization_app.models import OrganizationHHAccount


def get_hh_client_for_organization(organization) -> HHAPIClient:
    hh_account = OrganizationHHAccount.objects.get(organization=organization, archived=False)
    config = HHAPIClientConfig(base_url=getattr(settings, "HH_API_BASE_URL", "https://api.hh.uz"))
    return HHAPIClient(organization_hh_account=hh_account, config=config)

You can wire it to your existing settings:

# settings/base.py
HH_CLIENT_ID = env.str("HH_CLIENT_ID", default="")
HH_CLIENT_SECRET = env.str("HH_CLIENT_SECRET", default="")
HH_REDIRECT_URI = env.str("HH_REDIRECT_URI", default="")
HH_API_BASE_URL = "https://api.hh.uz"  # or api.hh.ru
HH_OAUTH_BASE_URL = "https://hh.uz"

Then your existing usage in signal handlers and DRF views can stay almost the same, just update the import:

from hh_api_client import HHAPIClient

Safety and error handling

• No secrets (tokens) are ever logged.
• Network errors raise requests.RequestException.
• API-level errors raise hh_api_client.HHAPIError with a sanitized message.
• Automatic token refresh is attempted once on 401 responses when a token provider is used.

Endpoints covered

High-level helpers currently implemented:

• get_user_info()
• get_employer_info()
• get_managers()
• get_default_manager_id()
• get_employer_services()
• get_publication_status()
• test_connection()

Vacancies:

• create_vacancy()
• update_vacancy()
• archive_vacancy()
• publish_vacancy()
• extend_vacancy()
• get_vacancy()
• get_vacancies()

Resumes:

• search_resumes()
• get_resume()

Negotiations:

• get_negotiations()
• get_vacancy_candidates()

Releasing (for maintainers)

This project is configured to publish using GitHub Actions and PyPI's OpenID Connect (OIDC) publisher.

• A GitHub Actions workflow lives at .github/workflows/workflow.yml.
• When you push a tag like v0.1.0 to the hh-api-client repository on GitHub, the workflow:
  • Builds the package with python -m build.
  • Publishes the distributions to TestPyPI (environment testpypi).
  • Then publishes the same build to PyPI (environment pypi).

To cut a new release:

1. Bump the version in pyproject.toml.

2. Commit and push to main.

3. Create and push a tag, e.g.:

   git tag v0.1.2
   git push origin v0.1.2
   

4. Wait for the GitHub Actions workflow to complete; the new version will appear on both TestPyPI and PyPI (assuming both publishers are configured).