Synchra.24
menu_bookҚұжаттама
Практические материалы по запуску и развитию

Здесь собраны инструкции по запуску, разработке внутренних сценариев и встраиванию собственных инструментов в рабочий контур компании.

folderИнтеграция және API

Токен жасау

Компания интерфейсі арқылы open API таңбалауышын қалай құруға болады және оны сыртқы интеграцияларда қауіпсіз пайдалануға болады.

Аударма әзірге қолжетімсіз. Түпнұсқа көрсетілді.

Токен нужен для того, чтобы внешняя система могла обращаться к 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, сначала удобно создать отдельный тестовый токен и проверить на нем базовый сценарий.