Методы API 1С: Кабинет сотрудника указаны в Swagger, который легко гуглится и довольно понятно описан.
Когда я только начинал работу с ним, мне казалось, что Swagger будет достаточно не только для знакомства с сервисом, но и для работы с моими приложениями. Но оказалось, что это не так. Даже получив bearer-токен, я так и не смог достучаться до своего приложения: в ответ на запросы Swagger отдавал 400-ые ответы. Техподдержка прокомментировала, что это нормально: Swagger демонстрирует методы, но запрос именно к своему приложению через Swagger не сделать.
Ниже я опишу, что нужно сделать, чтобы обратиться через API к своему приложению. Данные актуальны по состоянию на май 2024 г.
- Установка Postman
Можете использовать ваши собственные средства для создания запросов к API 1С: Кабинет сотрудника, - я же буду для наглядности использовать Postman.
Скачайте дистрибутив по ссылке, установите и зарегистрируйтесь. Нам будет достаточно возможностей бесплатной версии.
Создайте новое рабочее пространство (workspace). Оно потребуется нам для генерации bearer-токена. Со слов разработчиков, срок жизни токена - один час, поэтому при долгой работе нам потребуется делать генерацию регулярно, а значит, запрос должен быть под руками.
- Получение bearer-токена.
Для получения токена нам нужно знать данные аутентификации администратора 1С: Кабинет сотрудника. Получить их можно разными способами. Мы воспользуемся обработкой “Получение технических данных для интеграции с ДО 3”. Мы получили ее от технической поддержки, скачать можно здесь.
Обработка запускается через Файл - Открыть. Результат - уже известная информация (адрес приложения) и данные для авторизации (идентификатор и секрет).
Насколько я понимаю, эти данные остаются без изменений при использовании приложения.
Теперь мы можем генерировать bearer.
В созданном пространстве Postman создайте новый запрос:
- Тип запроса - post
- Текст запроса - https://vash_adres.1c-cabinet.ru/auth/oidc/token/, где vash_adres - это адрес вашего приложения, без идентификатор
- Тип данных - x-www-form-urlencoded
- в body укажите key: grant_type, value: client_credentials
- в Authorization выберите тип Basic Auth и укажите те самые данные авторизации: полученный идентификатор в поле Username, а полученный секрет в поле Password.
Пример - на скриншотах:
Если все правильно сделано, то в ответ придет код 200 и собственно токен Bearer:
Скопируйте все, что находится в значении id_token между кавычками. Это и есть bearer. Напомню, что срок жизни кода - всего час, поэтому запрос на его генерацию будет одним из ваших любимых.
Импорт методов Swagger
Теперь перейдем к самому интересному - к работе с методами API 1С: Кабинет сотрудника.
Мы можем копировать из Swagger те методы, которые нам интересны, - а можем сразу импортировать все в Postman.
И это не сложно. Импорт делается буквально в два клика. Создайте новое пространство и проведите импорт методов. Для этого нажмите Import и вставьте в качества источника адрес Swagger - https://api.1c-cabinet.ru/ess-api.yml, а затем нажмите Import:
В результате слева у вас отобразится список доступных методов.
Работа с запросами
И наконец, вот она - наша цель, запросы к сервису. Вы может прочитать документацию каждого метода (как в Swagger, так и в Postman):
Но самое главное - можете использовать метод. Для этого нужно выбрать метод, задать нужные параметры. Посмотрим, как это сделать, на примере метода /persons/active - он возвращает список ID активных физических лиц, - тех, на кого в сервисе заведен личный кабинет.
- В строке запроса укажем:
- актуальный адрес приложения, - вместе “applications” и идентификатором:
https://testkatya.1c-cabinet.ru/applications/053-460/
- параметр api + версия:
/api/v1.0/
- собственно метод:
/persons/active
Результат - запрос: https://testkatya.1c-cabinet.ru/applications/053-460/api/v1.0/persons/active
- В параметрах авторизации выберем Type = Bearer Token и значение = тот самый токен, который мы получили ранее.
- И наконец, в Headers добавим строку:
Key: formatVersion; Value: 1.0
Всё, наш запрос готов. Отправляем его большой синей кнопкой Send.
Результат запроса.
Если всё сделано верно, то сервис вернет вам 200-ый ответ и результат запроса. В случае с /persons/active мы получим список id активных физических лиц.
Дальше эту информацию можно использовать в других методах. Например, для деактивации физического лица из сервиса нужно обратиться к методу PUT /persons/inactive. В Headers указать formatVersion; Value: 1.0, в авторизации указать токен bearer, а в Body - один или несколько полученных id (в кавычках и через запятую).
Надеюсь, этот материал будет вам полезен.
