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

Для работы с данными конкретной активности внешней системе обычно недостаточно только общего токена авторизации пользователя. Нужен еще provider token — специальный токен, который дает доступ к данным выбранной активности.

Если говорить проще:

• auth token подтверждает, кто вы;
• provider token подтверждает, с какой именно активностью вы работаете.

Без provider token многие методы, связанные с данными активности, работать не будут.

Когда это нужно

Provider token нужен, если внешняя система:

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

Это типичный сценарий для:

• отчетности;
• интеграции с внутренними сервисами;
• обмена заявками;
• чтения структуры компании;
• работы со встроенными процессами активности.

Что потребуется заранее

Перед тем как получать provider token, у вас уже должны быть:

• auth token пользователя;
• provider_id активности, с которой нужно работать.

Где взять provider_id

provider_id — это идентификатор активности.

Его можно:

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

Если вы работаете с несколькими активностями, важно не перепутать provider_id, иначе provider token будет получен для другой компании.

Какой метод использовать

Для получения данных активности и provider token используется запрос:

GET /api/v1/providers/user/params/{provider_id}

Где:

• {provider_id} — идентификатор нужной активности.

Что передать в запросе

В запрос нужно передать auth token пользователя в заголовке авторизации.

Проще всего воспринимать это так:

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

Пример запроса

curl --request GET \
  --url https://getway.synchra24.com/api/v1/providers/user/params/123 \
  --header 'Authorization: Bearer <AUTH_TOKEN>'

Где:

• 123 — это provider_id;
• <AUTH_TOKEN> — токен авторизации пользователя.

Что приходит в ответе

В ответе возвращаются параметры активности. Среди них есть поле:

token

Именно это значение и нужно использовать как provider token.

То есть общий принцип такой:

1. отправили auth token и provider_id;
2. получили ответ с параметрами активности;
3. взяли из ответа поле token;
4. используете его в следующих запросах как X-Provider-Token.

Как это выглядит на практике

Типовой сценарий такой:

Шаг 1. Получите auth token

Сначала пользователь авторизуется в системе, и у вас появляется auth token.

Шаг 2. Определите нужную активность

Вы понимаете, с какой именно активностью будет работать интеграция, и получаете ее provider_id.

Шаг 3. Запросите параметры активности

Выполните запрос:

GET /api/v1/providers/user/params/{provider_id}

с auth token пользователя.

Шаг 4. Возьмите provider token из ответа

В ответе найдите поле token.

Это и есть provider token, который нужен для дальнейших запросов.

Шаг 5. Используйте provider token в следующих методах

В дальнейших запросах к данным активности передавайте этот токен в заголовке:

X-Provider-Token: <PROVIDER_TOKEN>

Почему нельзя использовать только auth token

Потому что auth token относится к пользователю в целом, а не к одной конкретной активности.

У одного пользователя может быть доступ:

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

Provider token как раз и закрепляет запрос за нужной активностью.

Что важно помнить

1. Provider token нужно получать для каждой активности отдельно

Если у пользователя есть доступ к нескольким активностям, provider token для каждой из них будет своим.

2. Не подставляйте случайный provider_id

Если передать неверный provider_id, вы получите данные не той активности или не получите доступ вовсе.

3. Храните provider token аккуратно

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

В каком порядке обычно строят интеграцию

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

1. получить auth token пользователя;
2. определить provider_id;
3. запросить provider token;
4. сохранить его в безопасном контексте интеграции;
5. использовать в рабочих методах API.

Что дальше

После получения provider token можно переходить к методам, которые работают уже с данными активности:

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

Если вы строите интеграцию впервые, удобно сначала проверить этот сценарий вручную: получить provider token по одному provider_id, а затем выполнить с ним простой тестовый запрос к данным активности.