Практические материалы по запуску и развитию

Токен нужен для того, чтобы внешняя система могла обращаться к Open API вашей активности. Если говорить проще, это специальный ключ доступа, который вы создаете через интерфейс и затем используете в интеграции.

Для чего нужен токен

Токен используется, когда вы хотите:

• подключить внешнюю систему к данным активности;
• строить отчеты во внешнем сервисе;
• забирать данные в свою BI-систему;
• запускать автоматические сценарии через Open API.

Без токена внешнее приложение не сможет работать от имени вашей активности.

Где создается токен

Токен создается в параметрах активности, во вкладке Интеграция API.

Если у вашей роли нет доступа к этой вкладке или она не отображается, чаще всего причина в правах роли или в лицензии активности.

Что важно знать заранее

Перед созданием токена полезно понимать две вещи:

1. Токен относится к интеграции

Обычно один токен создают под одну задачу. Например:

• отдельный токен для отчетности;
• отдельный токен для внутреннего сервиса;
• отдельный токен для обмена заявками.

Так проще поддерживать порядок и безопаснее отключать доступ при необходимости.

2. Токен показывается только один раз

После создания система показывает значение токена только в момент выдачи. Поэтому его нужно сразу сохранить в безопасном месте.

Как создать токен через интерфейс

Шаг 1. Откройте параметры активности

Перейдите в администраторский раздел и откройте Параметры активности.

Шаг 2. Перейдите на вкладку интеграции

Откройте вкладку Интеграция API.

На этом экране вы увидите:

• идентификатор активности;
• форму создания токена;
• список уже активных токенов.

Что такое ID активности

На экране также отображается ID активности. Он нужен для части сценариев интеграции, когда внешняя система должна понимать, с какой именно активностью она работает.

Этот идентификатор можно скопировать отдельно.

Как заполнить форму создания токена

Поле 1. Название токена

В этом поле укажите понятное имя. Лучше называть токен так, чтобы через месяц было ясно, зачем он был создан.

Хорошие примеры:

• BI-отчетность
• Интеграция с внутренним порталом
• Выгрузка рабочего времени
• Синхронизация заявок

Плохой пример:

• Тест
• Новый токен
• API 1

Чем понятнее название, тем проще потом управлять активными токенами.

Поле 2. Срок действия

Выберите, как долго токен должен работать.

Смысл здесь простой:

• если интеграция временная, лучше выбрать ограниченный срок;
• если это постоянный рабочий сценарий, можно выбрать более длинный период;
• если есть сомнения, лучше начинать с ограниченного срока и при необходимости создать новый токен позже.

Как завершить создание

После заполнения названия и срока действия нажмите кнопку Создать токен.

Если все прошло успешно:

• токен будет создан;
• значение токена сразу покажется на экране;
• система скопирует его в буфер обмена;
• новый токен появится в списке активных токенов.

Что сделать сразу после создания

После создания токена лучше сразу выполнить три действия:

1. сохранить токен в безопасное место;
2. передать его ответственному разработчику или системе, для которой он создан;
3. записать, для какого сценария он используется.

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

Как понять, что токен уже используется

В списке активных токенов можно увидеть:

• название токена;
• срок действия;
• дату последнего использования, если токен уже применялся.

Это удобно, если вы хотите понять:

• работает ли интеграция на самом деле;
• какой токен еще используется;
• какой токен можно отозвать без последствий.

Как отозвать токен

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

Отзыв полезен, если:

• интеграция завершена;
• сотрудник или подрядчик больше не работает с системой;
• токен был создан для теста;
• есть риск компрометации ключа.

После отзыва внешняя система больше не сможет использовать этот токен.

Как лучше организовать работу с токенами

Практически удобный подход такой:

• не использовать один токен для всех интеграций;
• давать каждому сценарию свое понятное название;
• периодически проверять список активных токенов;
• удалять неиспользуемые токены.

Так проще поддерживать порядок и безопасность.

Что еще потребуется для работы с API

Создание токена — это только первый шаг. Для полноценной интеграции обычно также нужно:

• понимать, какие методы API вы будете использовать;
• знать, какие данные хотите читать или отправлять;
• настроить внешнюю систему на работу с токеном;
• проверить, что запросы действительно выполняются в нужном контексте активности.

Если вы только начинаете знакомство с Open API, сначала удобно создать отдельный тестовый токен и проверить на нем базовый сценарий.