Обзор

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

Базовый адрес — https://api.odamiai.kz/api/integration/v1 для компаний из Казахстана и https://api.odamiai.uz/api/integration/v1 для Узбекистана. Это один и тот же API: сервисный ключ работает на обоих. Версия стоит в пути, а не в заголовке: её можно прописать в конфиге и не зависеть от того, что мы считаем текущей. В пределах v1 поля только добавляются — переименование или удаление означало бы v2.

Три метода

Метод	Что делает	Область доступа
GET /vacancies	вакансии компании	vacancies:read
GET /candidates	отклики с резюме	candidates:read
POST /applications	принять отклик или реферала	applications:write

Область доступа выдаётся ключу при выпуске. Витрина вакансий, которой нужно только показывать открытые позиции и собирать отклики, не должна иметь возможности выкачать базу кандидатов — поэтому области разные и выдаются отдельно.

Модель данных

Вакансия — позиция, на которую идёт найм. У неё есть статус, город, адрес офиса, требование к опыту, формат работы и вилка. Часть вакансий приезжает в платформу с hh.ru, и тогда поля приходят в формулировках hh («От 1 года», «Гибрид») — мы их не переписываем, чтобы не терять смысл.

Кандидат — отклик конкретного человека на конкретную вакансию. Внутри — резюме целиком: опыт, образование, языки, сертификаты, навыки, портфолио. Один человек, откликнувшийся на две вакансии, приедет двумя кандидатами.

Реферал — тот же кандидат, но с заполненным блоком referral. Отдельного флага нет: реферал — это отклик, у которого есть рекомендатель.

Что дальше

Начните с аутентификации — без ключа ни один метод не ответит. Затем прочитайте про синхронизацию: постраничность здесь курсорная, а инкрементальность строится на отметке правки, и оба решения влияют на то, как писать клиента.