API для ваших агентов

Для кого

Для компаний, которые хотят, чтобы ассистент делал рутину: отвечал «что предложить начальнику смены склада», перечислял слишком долго ждущих кандидатов, публиковал вакансию по краткому описанию, утверждал расчёт после того, как человек прочитал проверки. API — тот же сервисный слой, которым пользуются страницы, так что всё, что делает система, будет доступно, с теми же правилами и теми же ограничениями ролей.

Это и честный ответ на «можно ли это автоматизировать»: эндпоинты чтения работают уже сейчас; эндпоинты записи перечислены со статусом «planned» и отвечают 501, пока не запущены, так что агент никогда не гадает.

Создание ключа

1. Откройте Настройки › Ключи API. Создавать может только владелец компании; сначала попросят свежий второй замок.
2. Назовите ключ по назначению («агент Claude», «скрипт зарплаты»), выберите самые узкие права, которых хватает для задачи, и срок действия.
3. Прочитайте риски и отметьте подтверждение. Ключ показывается один раз; скопируйте его в хранилище секретов агента и никуда больше.
4. Отзовите его на той же странице, как только он больше не нужен. Отзыв мгновенный.

В демо любой может создать демо-ключ (fjhr_demo_…). Он действует только на вашу демо-компанию и исчезает вместе с ней.

Риски, прямо

• Ключ — это пароль от компании. Любой, у кого он есть, может всё, что разрешают его права, без второго замка.
• Агент действует от вашего имени. Неверная инструкция может закрыть вакансию, отклонить кандидата или изменить карточку. Начните с прав чтения; добавьте запись, когда агент её заслужит.
• Никогда не вставляйте ключ в публичный чат, репозиторий или промпт, который может прочитать кто-то ещё. Сомневаетесь — замените.
• Каждый вызов записывается с ключом, маршрутом, статусом и временем. Владелец читает журнал на той же странице.

Права

• market:read: диапазоны зарплат и сложность найма.
• company:read: компания, Главная и счётчики.
• jobs:read и jobs:write: чтение, публикация, правка, закрытие и поднятие вакансий.
• applications:read и applications:write: чтение откликов и оценок; смена этапов, ответы, назначение собеседований.
• people:read и people:write: карточки сотрудников без личных данных; добавление и изменение людей, решения по отпускам.
• money:read и money:write: расчёты и правила; утверждение расчёта (файлы готовятся; деньги не движутся).
• settings:write: вебхуки и настройки. Сами ключи никогда не могут быть созданы или изменены ключом.
• all: всё перечисленное.

Вызов

Базовый адрес https://hr.findjobs.ge/hr/api/v1. Отправляйте ключ как Authorization: Bearer fjhr_live_… в каждом запросе. Ответы в JSON. Добавьте ?hl=ka, ru или tr, чтобы получать описания на этом языке там, где API говорит.

Лимиты: 60 вызовов в минуту и 20 записей в минуту на ключ. 429 содержит Retry-After в секундах.

Ошибки — JSON со стабильным кодом и предложением: missing_key, invalid_key, scope, rate_limited, not_yet (спроектировано, не запущено), not_found, server_error, и ссылка на документацию.

Для LLM-агента

1. Дайте агенту https://hr.findjobs.ge/hr/api/v1/llms.txt: он описывает API, лимиты и правила простым текстом.
2. Дайте ему документ OpenAPI по адресу https://hr.findjobs.ge/hr/api/v1/openapi.json для генерации инструментов.
3. Храните ключ в хранилище секретов агента, никогда в промпте.
4. Скажите ему, какие права у ключа, чтобы он не пытался делать то, чего не может.

Пример: curl -H "Authorization: Bearer $KEY" "https://hr.findjobs.ge/hr/api/v1/market/pay-check?city=tbilisi&family=sales&offer=1200"

Чего ключ никогда не может

• Читать данные другой компании или личные данные соискателей сверх того, что компания уже видит на findjobs.ge.
• Перемещать деньги, входить в банк или подавать в Службу доходов.
• Создавать или менять ключи, ослаблять второй замок.
• Узнавать, есть ли у сотрудника профиль на findjobs и откликается ли он где-то.

Эндпоинты

Таблица ниже генерируется из того же списка, по которому маршрутизирует API, поэтому расходиться они не могут. Статус «live» отвечает сегодня; «planned» спроектирован и отвечает 501, пока не запущен.