API позволяет другой программе работать с вашим аккаунтом KEHR автоматически. Ключ показывает сервису, от чьего имени пришёл запрос. Если вы пользуетесь только кабинетом, создавать ключ не обязательно. Храните его как пароль: человек, получивший ключ, может обращаться к доступным вашему аккаунту функциям API.
Получить ключ#
- Войдите в кабинет и нажмите «API ключ» в верхней панели. На телефоне, если кнопка скрыта, сначала раскройте меню кабинета кнопкой ☰.
- Если в окне есть только «Сгенерировать ключ», нажмите эту кнопку и дождитесь появления значения. Если ключ уже показан, используйте его; повторная генерация для копирования не нужна.
Так выглядит окно до первого создания ключа.
Скопировать готовый ключ#
- Нажмите на строку с ключом или значок двух листов рядом с ней. Копируется значение ключа, а не ссылка на окно.
- Дождитесь сообщения «API ключ скопирован в буфер». Передайте значение в закрытое хранилище вашего приложения или своему разработчику по защищённому каналу.
- Не включайте ключ в адреса страниц, открытые репозитории, скриншоты и обращения в поддержку. Для обычной работы с кабинетом вводить его в формы не нужно.
На снимке стоит нерабочее учебное значение EXAMPLE_DO_NOT_USE_…; использовать его в запросах нельзя.
После нажатия появится короткое подтверждение копирования.
Если подтверждения нет, проверьте разрешение браузера на работу с буфером обмена. При необходимости выделите и скопируйте только само значение вручную, без значка, пробелов и переносов строки.
Открыть публичную документацию#
- Нажмите «Документация API» в окне ключа или откройте публичную документацию. Для чтения вход и ключ не нужны.
- Найдите группу нужной услуги и раскройте строку действия. Рядом с адресом указан способ запроса, например
GET. - В разделе Parameters прочитайте поля запроса, а в Responses — возможные ответы. Описания отдельных действий сейчас могут быть на русском; технические названия параметров нужно сохранять точно.
Разработчику нужен заголовок запроса X-Api-Key с вашим ключом. Это дополнительное поле, которое программа отправляет вместе с запросом; в адрес страницы ключ не добавляют. Кнопка Authorize в документации открывает сведения об авторизации: Name: X-Api-Key, In: header. На снимке поле пустое — для чтения документации заполнять его не требуется.
Запуск действия через Try it out / Execute обращается к вашему аккаунту. Сначала разберите конкретное действие с разработчиком, особенно если оно создаёт платный заказ или меняет настройки.
Заменить ключ#
- Если ключ мог попасть к посторонним, откройте «API ключ». В окне уже созданного ключа доступна кнопка «Сгенерировать новый ключ», показанная выше.
- Нажмите её и подтвердите замену в диалоге браузера. Если вы только хотели посмотреть или скопировать ключ, отмените замену.
- Скопируйте новое значение и обновите его во всех своих приложениях и скриптах. Старый ключ перестанет подходить для новых запросов.
- Проверьте нужное безопасное действие из каждого приложения. Замена ключа не исправляет неверные параметры и не продлевает оплачиваемые услуги.
Если запрос не работает#
- Ошибка авторизации, например 401: проверьте, что приложение передаёт актуальный ключ именно в
X-Api-Key, без пробелов, кавычек и переносов. После замены проверьте все места хранения старого значения. - Доступ запрещён, например 403: прочитайте сообщение ответа и проверьте доступность нужной услуги и статус её тарифа в кабинете.
- Ошибка параметров: сверяйте адрес, способ запроса, названия и значения полей с нужным действием в документации.
- Документация не загрузилась: обновите страницу и проверьте, не блокирует ли браузер её скрипты. Если ошибка повторяется, сохраните сообщение.
Для поддержки укажите адрес действия без ключа, способ запроса, время, код и текст ответа, а также ожидаемый результат. Перед отправкой удалите ключ из заголовков, примеров и снимков. Для получения User-Agent без программирования используйте генератор в кабинете.