Metadata-Version: 2.4
Name: hh-applicant-tool
Version: 1.1.2
Summary: HH-Applicant-Tool: An automation utility for HeadHunter (hh.ru) designed to streamline the job search process by auto-applying to relevant vacancies and periodically refreshing resumes to stay at the top of recruiter searches.
Author: Senior YAML Developer
Author-email: yamldeveloper@proton.me
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: playwright (>=1.57.0,<2.0.0)
Requires-Dist: prettytable (>=3.6.0,<4.0.0)
Requires-Dist: requests[socks] (>=2.32.3,<3.0.0)
Project-URL: Homepage, https://github.com/s3rgeym/hh-applicant-tool
Project-URL: Repository, https://github.com/s3rgeym/hh-applicant-tool
Description-Content-Type: text/markdown

## HH Applicant Tool

![Publish to PyPI](https://github.com/s3rgeym/hh-applicant-tool/actions/workflows/publish.yml/badge.svg)
[![PyPi Version](https://img.shields.io/pypi/v/hh-applicant-tool)]()
[![Python Versions](https://img.shields.io/pypi/pyversions/hh-applicant-tool.svg)]()
[![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/s3rgeym/hh-applicant-tool)]()
[![PyPI - Downloads](https://img.shields.io/pypi/dm/hh-applicant-tool)]()
[![Total Downloads](https://static.pepy.tech/badge/hh-applicant-tool)]()

<div align="center">
  <img src="https://github.com/user-attachments/assets/29d91490-2c83-4e3f-a573-c7a6182a4044" width="500">
</div>

### ✨ Ключевые преимущества

- 💸 **Бесплатно.** В то время как сервисы в интернете или Telegram с аналогичным функционалом просят за свои услуги от 5.000 до 12.000 рублей в месяц.

- 🔒 **Безопасность личных данных.** Ваши email, телефон, пароль и другие личные данные никуда не передаются в отличии от сторонних сервисов. В этом можно убедиться, изучив [открытый исходный код](https://github.com/s3rgeym/hh-applicant-tool/tree/main/applicant_tool). Владельцы сторонних сервисов никогда вам не покажут исходники. Они знают о вас все и эти данные спокойно продадут каким-нибудь жуликам, либо те утекут в результате взлома.

- 🛡️ **Гарантия от блокировок.** Утилита выполняет запросы с вашего устройства, имитируя обычного пользователя. Сервисы рассылают запросы для сотен аккаунтов с одного сервера, что повышает вероятность блокировки вашего аккаунта до 100%.

- 😎 **Простота в использовании.** С утилитой разберется любой начинающий пользователь компьютера. Настолько, что херки в своем чате уже жалуются на массовые отклики от подростков 14-17 лет, которые успешно освоили данный инструмент.

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

- 🖥️ **Полноценный CLI и работа на серверах.** Утилита имеет чистый консольный интерфейс. Несмотря на то, что для обхода защиты при авторизации используется браузер, он работает в фоновом (headless) режиме. Для `hh-applicant-tool` не нужна видеокарта или графическая оболочка (X-сервер), что позволяет авторизоваться даже с сервера или из докер-контейнера. Благодаря этому вы можете ее интегрировать, например, в Telegram-бота.

- 🤖 **Борьба с автоотказами.** Компании уже массово внедрили ATS-системы с нейронными сетями, которые отклоняют ваш отклик в течение 30 секунд. Отказ может прийти из-за отсутствия одного ключевого слова в резюме, это уже неговоря о давно существующих фильтрах по полу, возрасту и даже региону происхождения (безопасники в банках отказывают даже русским, рожденным в Дагестане). Это обесценивает ваши усилия на написание сопроводительных писем и чтение бесконечных портянок бреда, сгенерированных нейронками по запросу каких-то дур. Утилита избавляет вас от этой рутины, превращающей поиск работы в полноценную работу. Сейчас доля отказов составляет 98-99%, включая "молчунов", и единственный способ увеличить шансы просто попасть на собеседование — это автоматическая рассылка откликов на все подходящие вакансии.

### Содержание

- [HH Applicant Tool](#hh-applicant-tool)
  - [✨ Ключевые преимущества](#-ключевые-преимущества)
  - [Содержание](#содержание)
  - [Описание](#описание)
  - [Внимание!!!](#внимание)
  - [Предыстория](#предыстория)
  - [Установка](#установка)
    - [Установка утилиты](#установка-утилиты)
    - [Установка зависимостей](#установка-зависимостей)
  - [Авторизация](#авторизация)
  - [Конфигурация](#конфигурация)
  - [Описание команд](#описание-команд)
  - [Формат текста сообщений](#формат-текста-сообщений)
  - [Использование AI для генерации сопроводительного письма](#использование-ai-для-генерации-сопроводительного-письма)
    - [OpenAI/ChatGPT](#openaichatgpt)
  - [Добавление своих команд](#добавление-своих-команд)

---

### Описание

> Данной утилите похуй на "запрет" доступа к API HH сторонним приложениям, так как она прикидывается официальным приложением под Android

> Утилита для генерации сопроводительного письма может использовать AI в тч ChatGPT. Подробное описание ниже

Утилита для успешных волчат и старых волков с опытом, служащая для автоматизации действий на HH.RU таких как рассылка откликов на подходящие вакансии и обновление всех резюме (бесплатный аналог услуги на HH). Утилита локально хранит информацию об откликах в тч полученные контакты. Это удобно, так как контакт сохранится даже, если вышлют отказ в дальнейшем. Мой совет: скрывайте свой номер от работодателя, если рассылаете отклики через утилиту, а то количество жуликов на красном сайте мягко говоря зашкаливает. У утилиты есть канал в дуровграме: [HH Applicant Tool](https://t.me/applicant_tool). Старый <s>[HH Resume Automate](https://t.me/hh_resume_automate)</s> был выпилен какими-то долбоебами, углядевшими во флаге Японии с двумя буквами h нарушение авторских прав...

Работает с Python >= 3.10. Нужную версию Python можно поставить через
asdf/pyenv/conda и что-то еще. В школотронской Manjaro и даже в последних Ubuntu
версия Python новее.

Данная утилита кроссплатформенна. Она гарантировано работает на Linux, Mac и Windows в тч WSL. При наличии рутованного телефона можно вытащить `access` и `refresh` токены из официального приложения и добавить их в конфиг.

Пример работы:

![image](https://github.com/user-attachments/assets/a0cce1aa-884b-4d84-905a-3bb207eba4a3)

> Если в веб-интерфейсе выставить фильтры, то они будут применяться в скрипте при отклике на подходящие

> Утилита автоматически подхватывает прокси из переменных окружения типа http_proxy или HTTPS_PROXY

### Внимание!!!

Если для Вас проблема установить данную утилиту, лень разбираться с ее настройкой, то Вы можете установить мое приложение под **Android** [HH Resume Automate](https://github.com/s3rgeym/hh-resume-automate/). Оно обладает минимальным функционалом: обновление резюме (одного) и рассылка откликов (чистить их и тп нельзя).

### Предыстория

Долгое время я делал массовые заявки с помощью консоли браузера:

```js
$$('[data-qa="vacancy-serp__vacancy_response"]').forEach((el) => el.click());
```

Оно работает, хоть и не идеально. Я даже пробовал автоматизировать рассылки через `p[yu]ppeeter`, пока не прочитал [документацию](https://github.com/hhru/api). И не обнаружил, что **API** (интерфейс) содержит все необходимые мне методы. Headhunter позволяет создать свое приложение, но там ручная модерация, и наврядли кто-то разрешит мне создать приложение для спама заявками. Я [декомпилировал](https://gist.github.com/s3rgeym/eee96bbf91b04f7eb46b7449f8884a00) официальное приложение для **Android** и получил **CLIENT_ID** и **CLIENT_SECRET**, необходимые для работы через **API**.

### Установка

#### Установка утилиты

Универсальный с использованием pipx (требует пакета `python-pipx` в Arch):

```bash
$ pipx install 'hh-applicant-tool'

# Если хочется использовать самую последнюю версию, то можно установить ее через git
$ pipx install git+https://github.com/s3rgeym/hh-applicant-tool

# Для обновления до новой версии
$ pipx upgrade hh-applicant-tool
```

pipx добавляет исполняемый файл `hh-appplicant-tool` в `~/.local/bin`, делая эту команду доступной. Путь до `~/.local/bin` должен быть в `$PATH` (в большинстве дистрибутивов он добавлен).

Традиционный способ для Linux/Mac:

```sh
mkdir -p ~/.venvs
python -m venv ~/.venvs/hh-applicant-tool
# Это придется делать постоянно, чтобы команда hh-applicant-tool стала доступна
.  ~/.venvs/hh-applicant-tool/bin/activate
pip install hh-applicant-tool
```

Отдельно я распишу процесс установки в **Windows** в подробностях:

- Для начала поставьте последнюю версию **Python 3** любым удобным способом.
- Запустите **Terminal** или **PowerShell** от Администратора и выполните:
  ```ps
  Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted
  ```
  Данная политика разрешает текущему пользователю (от которого зашли) запускать скрипты. Без нее не будут работать виртуальные окружения.
- Создайте и активируйте виртуальное окружение:

  ```ps
  PS> python -m venv hh-applicant-venv
  PS> .\hh-applicant-venv\Scripts\activate
  ```

- Поставьте все пакеты в виртуальное окружение `hh-applicant-venv`:
  ```ps
  (hh-applicant-venv) PS> pip install hh-applicant-tool
  ```
- Проверьте работает ли оно:
  ```ps
  (hh-applicant-venv) PS> hh-applicant-tool -h
  ```
- В случае неудачи вернитесь к первому шагу.
- Для последующих запусков сначала активируйте виртуальное окружение.

#### Установка зависимостей

После вышеописанного нужно установить зависимости в виде Chromium и других средств отладки:

```sh
$ hh-applicant-tool install
```

Этот шаг необязателен. Все это нужно только для авторизации.

### Авторизация

Прямая авторизация:

```bash
$ hh-applicant-tool authorize '<ваш телефон или email>' -p '<пароль>'
```

Если вы пропустили пункт про установку зависимостей, то увидите такую ошибку:

```sh
[E] BrowserType.launch: Executable doesn't exist at...
```

Если не помните пароль или др. причины, то можно авторизоваться с помощью одноразового кода:

```bash
$ hh-applicant-tool authorize '<ваш телефон или email>'
📨 Код был отправлен. Проверьте почту или SMS.
📩 Введите полученный код: 1387
🔓 Авторизация прошла успешно!
```

- Если вы ввели телефон, то код придет через SMS
- Если был введен Email, то проверьте почту

Если же при вводе правильных данных возникает ошибка авторизации, то скорее всего требуется ввод капчи:

```sh
hh-applicant-tool authorize --no-headless
```

Проверка авторизации:

```bash
$ hh-applicant-tool whoami
🆔 27405918 Кузнецов Андрей Владимирович [ 📄 1 | 👁️ +115 | ✉️ +28 ]
```

В случае успешной авторизации токены будут сохранены в `config.json`.

Токен доступа выдается на две недели. Он обновляется автоматически. Для его ручного обновления нужно выполнить:

```bash
$ hh-applicant-tool refresh-token
```

Помните, что у `refresh_token` тоже есть время жизни, поэтому может потребоваться полная авторизация.

### Конфигурация

Конфигурации хранятся по следующим путям:

| OS          | Путь                                                     |
| ----------- | -------------------------------------------------------- |
| **Windows** | `C:\Users\%username%\AppData\Roaming\hh-applicant-tool\` |
| **macOS**   | `~/Library/Application Support/hh-applicant-tool/`       |
| **Linux**   | `~/.config/hh-applicant-tool/`                           |

По этому пути находятся каталоги с профилями. В каталоге с профилем лежит главный конфиг `config.json`.

Полный путь до конфигурационного файла можно вывести с помощью команды:

```bash
hh-applicant-tool config -s
```

Для переноса конфига на новое устройство скопируйте директорию профиля либо файлы из нее, если надо создав директорию профиля по умолчанию `default`.

Через конфиг можно задать дополнительные настройки:

| Имя атрибута    | Описание                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------ |
| `proxy_url`     | Прокси, используемый для всех запросов, например, `socks5h://127.0.0.1:9050`               |
| `reply_message` | Сообщение для ответа работодателю при отклике на вакансии, см. формат сообщений            |
| `user_agent`    | Кастомный юзерагент, передаваемый при каждом запросе. По умолчанию используется от Android |
| `client_id`     | Идентификатор клиента, используемый для авторизации. По умолчанию используется от Android  |
| `client_secret` | Секретный ключ клиента, используемый для авторизации. По умолчанию используется от Android |

В `log.txt` всегда можно посмотреть подробную информацию об ошибках.

Данные о работодателях и их вакансиях хранятся в файле `data`. Это обычная база `sqlite3` вы ее можете просматривать через `DB Browser` и тп.

### Описание команд

Глобальные флаги:

- `-v` используется для вывода отладочной информации. Два таких флага, например, выводят запросы к **API**.
- `-c <path>` путь до каталога, где хранятся конфигурации.
- `--profile <profile-id>` имя текущего профиля, подкаталога в каталоге с конфигурациями.

| Операция           | Описание                                                                                                                                                                     |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **authorize**      | Открывает сайт hh.ru для авторизации                                                                                                                                         |
| **whoami**         | Выводит информацию об авторизованном пользователе                                                                                                                            |
| **list-resumes**   | Список резюме                                                                                                                                                                |
| **update-resumes** | Обновить все резюме. Аналогично нажатию кнопки «Обновить дату».                                                                                                              |
| **apply-similar**  | Откликнуться на все подходящие вакансии. Лимит = 200 в день. На HH есть спам-фильтры, так что лучше не рассылайте отклики со ссылками, иначе рискуете попасть в теневой бан. |
| **reply-chats**    | Ответить во все чаты с работодателями, где нет ответа либо не прочитали ваш предыдущий ответ                                                                                 |
| **negotiations**   | Проверятет отклики и выводит приглашения, а так же опционально может отменять отклики                                                                                        |
| **call-api**       | Вызов произвольного метода API с выводом результата.                                                                                                                         |
| **refresh-token**  | Обновляет access_token.                                                                                                                                                      |
| **config**         | Показывает содержимое конфига. С флагом -e открывает его для редактирования.                                                                                                 |
| **install**        | Устанавливает зависимости, такие как браузер Chromium, необходимые для авторизации.                                                                                          |
| **uninstall**      | Удаляет браузер Chromium, используемый для авторизации.                                                                                                                      |
| **check-proxy**    | Проверяет используемые прокси                                                                                                                                                |
| **log**            | Просмотр файла-лога. С флагом -f будет следить за изменениями.                                                                                                               |

Данные имена команд равнозначны: `call-api = callApi = callapi`. Можно использовать `kebab-case`, `camelCase` и `flatcase`.

Примеры команд:

```bash
$ hh-applicant-tool [ GLOBAL_FLAGS ] [ OPERATION [ OPERATION_FLAGS  ] ]

# Справка по глобальным флагам и список операций
$ hh-applicant-tool -h

# Справка по операции
$ hh-applicant-tool apply-similar -h

# Авторизуемся
$ hh-applicant-tool authorize

# Авторизация с использованием другого профиля
$ hh-applicant-tool --profile fake authorize

# Рассылаем заявки
$ hh-applicant-tool apply-similar

# Для тестирования поисковой строки и других параметров, используйте --dry-run.
# С ним отклики не отправляются, а лишь выводятся сообщения
$ hh-applicant-tool -vv apply-similar --search "Python программист" --per-page 10 --total-pages 1 --dry-run

# Поднимаем резюме
$ hh-applicant-tool update-resumes

# Проверяем отклики и сохраняем отчет о приглпшениях
$ hh-applicant-tool negotiations -r report.csv

# Чистим заявки и баним за отказы говноконторы
$ hh-applicant-tool negotiations --clean --blacklist-discard

# Просмотр лога в реальном времени
$ hh-applicant-tool log -f

# Посмотреть содержимое конфига
$ hh-applicant-tool config

# Редактировать конфиг в стандартном редакторе
$ hh-applicant-tool config -e

# Вывести значение из конфига
$ hh-applicant-tool config -k token.access_token

# Установить значение в конфиге
$ hh-applicant-tool config -s openai.model gpt-4o

# Удалить значение из конфига
$ hh-applicant-tool config -u proxy_url
```

Для тестирования запросов к API используйте команду `call-api` совместно с `jq` для обработки JSON.

Примеры поиска работодателей:

```bash
$ hh-applicant-tool call-api /employers text="IT" only_with_vacancies=true | jq -r '.items[].alternate_url'
https://hh.ru/employer/1966364
https://hh.ru/employer/4679771
https://hh.ru/employer/8932785
https://hh.ru/employer/9451699
https://hh.ru/employer/766478
https://hh.ru/employer/4168187
https://hh.ru/employer/9274777
https://hh.ru/employer/1763330
https://hh.ru/employer/5926815
https://hh.ru/employer/1592535
https://hh.ru/employer/9627641
https://hh.ru/employer/4073857
https://hh.ru/employer/2667859
https://hh.ru/employer/4053700
https://hh.ru/employer/5190600
https://hh.ru/employer/607484
https://hh.ru/employer/9386615
https://hh.ru/employer/80660
https://hh.ru/employer/6078902
https://hh.ru/employer/1918903
```

Синтаксис `call-api` немного похож на `httpie` или `curlie`:

```sh
hh-applicant-tool call-api [ -m {GET|POST|PUT|DELETE} ] [/]path/to/endpoint [ key1=value1  [ ... keyN=valueN ] ]
```

Если используется метод `GET` или `DELETE` (или ничего не указано), то параметры будут переданы как query string. Во всех остальных случаях парметры передаются как `application/x-www-form-urlencoded` в теле запроса.

Данная возможность полезна для написания Bash-скриптов.

Документация для работы с API соискателей была удалена с ха-ха и его копропротивного репозитория. Можете не искать, они затерли даже историю репозитория. Но я через веб-архив выкачал документацию. Чтобы ее посмотреть, клонируйте этот репозиторий и выполните:

```sh
npx @redocly/cli preview -d docs/hhapi
```

Далее нужно в браузере открыть [http://localhost:4000](http://localhost:4000).

<img width="2560" height="1440" alt="image" src="https://github.com/user-attachments/assets/a963b405-b872-4865-abed-fd704532cd80" />

> Отдельные замечания у меня к API HH. Оно пиздец какое кривое. Например, при создании заявки возвращается пустой ответ либо редирект, хотя по логике должен возвраться созданный объект. Так же в ответах сервера нет `Content-Length`. Из-за этого нельзя узнать есть тело у ответа сервера нужно его пробовать прочитать. Я так понял там какой-то прокси оборачивает все запросы и отдает всегда `Transfer-Encoding: Chunked`. А еще он возвращает 502 ошибку, когда бекенд на Java падает либо долго отвечает (таймаут)? А вот [язык запросов](https://hh.ru/article/1175) мне понравился. Можно что-то типа этого использовать `NOT (!ID:123 OR !ID:456 OR !ID:789)` что бы отсеить какие-то вакансии.



По-сути, никакие дополнительные команды кроме имеющихся не нужны. Вы можете сделать что угодно с помощью `call-api`, но если хочется чего-то особенно, можно добавить свои команды.

### Формат текста сообщений

Команда `apply-similar` поддерживает специальный формат сообщений.

Так же в сообщении можно использовать плейсхолдеры:

- **`%(vacancy_name)s`**: Название вакансии.
- **`%(employer_name)s`**: Название работодателя.
- **`%(first_name)s`**: Имя пользователя.
- **`%(last_name)s`**: Фамилия пользователя.
- **`%(email)s`**: Email пользователя.
- **`%(phone)s`**: Телефон пользователя.

Эти плейсхолдеры могут быть использованы в сообщениях для отклика на вакансии, чтобы динамически подставлять соответствующие данные в текст сообщения. Например:

```
Меня заинтересовала ваша вакансия %(vacancy_name)s. Прошу рассмотреть мою кандидатуру. С уважением, %(first_name)s %(last_name)s.
```

Так же можно делать текст уникальным с помощью `{}`. Внутри них через `|` перечисляются варианты, один из которых будет случайно выбран:

```
{Здоров|Привет}, {как {ты|сам}|что делаешь}?
```

В итоге получится что-то типа:

```
Привет, как ты?
```

### Использование AI для генерации сопроводительного письма

Пример рассылки откликов с генерированным письмом:

```sh
hh-applicant-tool apply-similar -f --ai
```

#### OpenAI/ChatGPT

Отредактируйте конфиг:

```sh
hh-applicant-tool config -e
```

Добавьте в него эти строки:

```json
{
  // ...
  "openai": {
    "token": "ВАШ_API_КЛЮЧ_OPENAI",
    "model": "gpt-4o",
    "system_prompt": "Вы опытный HR-специалист. Напишите идеальное сопроводительное письмо..."
  }
}
```

### Добавление своих команд

Утилита использует систему плагинов. Все они лежат в [operations](https://github.com/s3rgeym/hh-applicant-tool/tree/main/applicant_tool/operations). Модули расположенные там автоматически добавляются как доступные команды. За основу для своего плагина можно взять [whoami.py](https://github.com/s3rgeym/hh-applicant-tool/tree/main/applicant_tool/operations/whoami.py).

