# Подключение OAuth
***
### ✅ Что вам нужно подготовить перед началом
Пожалуйста, убедитесь, что у вас есть всё необходимое, прежде чем приступать к дальнейшим шагам:
* [ ] **HTTPS-адрес `redirect_uri`**\
Это адрес, на который вы будете перенаправлены после выбора проекта для подключения.\
Подойдёт даже просто пустая страница на вашем домене.
* [ ] **Отправить этот адрес нам**\
Мы получим его и сгенерируем для вас персональные ключи.
* [ ] **Получить от нас `client_id` и `secret_key`**\
Без них подключение не получится завершить.
* [ ] **Иметь доступ к проекту в** [**dashboard.fstrk.io**](https://dashboard.fstrk.io)\
Вы должны быть авторизованы на платформе и иметь права на подключение интеграций.
***
### 📋 Подготовительный этап
| Шаг | Действие | Кто выполняет |
| --- | ---------------------------------------- | ------------- |
| 0 | Вы присылаете нам ваш `redirect_uri` | **вы** |
| 1 | Мы выдаём вам `client_id` и `secret_key` | **мы** |
***
### Шаг 0. Вы предоставляете redirect\_uri
Пожалуйста, подготовьте и пришлите нам адрес, на который вы будете перенаправлены после успешного выбора проекта для подключения.
**Что нужно знать о redirect\_uri:**
* Рекомендуем использовать **ваш собственный домен**
* Сама страница может быть **пустой** - нам важен только сам факт, что в URL попадёт параметр `code`
**Пример redirect\_uri:**
```
https://ваш-домен.ru/fstrk/oauth/callback
```
> 💡 **Важный момент:**\
> Вам не нужно программно обрабатывать этот URL. Достаточно, чтобы по нему открывалась любая страница (хоть просто `200 OK`).\
> Главное - после редиректа вы сможете вручную скопировать `?code=...` из адресной строки браузера.
***
### Шаг 1. Мы выдаём вам client\_id и secret\_key
На основе полученного от вас `redirect_uri` мы генерируем для вашей интеграции:
* **`client_id`** - публичный идентификатор вашего подключения
* **`secret_key`** - секретный ключ (понадобится для обмена временного кода на токены)
Мы пришлём вам эти данные, после чего вы сможете самостоятельно пройти дальнейшие шаги.
***
### Шаг 2. Вы получаете временный код (делается вручную один раз)
1. Авторизуйтесь на платформе через домен [**https://dashboard.fstrk.io/bots/detail/**](https://dashboard.fstrk.io/bots/detail/) и войдите в нужный проект.
2. Сформируйте ссылку для подключения, используя **ваш redirect\_uri** и **выданный client\_id**:
```
https://dashboard.fstrk.io/integrations/oauth/?client_id=XXX&redirect_uri=https://ваш-домен.ru/fstrk/oauth/callback
```
3. Перейдите по этой ссылке → выберите проект → нажмите кнопку **«Подключить»**.
3. Система автоматически перенаправит вас на ваш `redirect_uri`. Адресная строка будет выглядеть примерно так:
```
https://ваш-домен.ru/fstrk/oauth/callback?code=ВРЕМЕННЫЙ_КОД&state=None
```
5. **Скопируйте временный код** из URL.\
\&#xNAN;*(код действителен всего 5 минут, так что лучше сделать это сразу)*
***
### Шаг 3. Обмениваем код на токены
Теперь нужно обменять временный код на полноценные `access_token` и `refresh_token`.\
Вы можете сделать это вручную через [Swagger ](https://dashboard.fstrk.io/api/partners/docs/#/01.%20%D0%9C%D0%B5%D1%82%D0%BE%D0%B4%D1%8B%20%D0%B4%D0%BB%D1%8F%20%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8/oauth_create)или настроить автоматический вызов API.
**POST** `https://dashboard.fstrk.io/api/partners/oauth/`
**Параметры запроса (JSON):**
```json
{
"client_id": "ваш_client_id",
"client_secret": "ваш_secret_key",
"grant_type": "code",
"code": "ВРЕМЕННЫЙ_КОД"
}
```
**Что вы получите в ответ:**
```json
{
"access_token": "eyJ...",
"refresh_token": "hdL...",
"expires_in": 3600,
"token_type": "Bearer"
}
```
> 💡 **Подсказка:**\
> Если хотите попробовать вручную — откройте [Swagger](https://dashboard.fstrk.io/api/partners/docs/#/01.%20%D0%9C%D0%B5%D1%82%D0%BE%D0%B4%D1%8B%20%D0%B4%D0%BB%D1%8F%20%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8/oauth_create) и вставьте код там.
***
### Шаг 4. Подписываемся на вебхуки (один раз, после получения токенов)
После того как вы получили первую пару токенов, пожалуйста, не забудьте подписаться на нужные типы вебхуков и платформы.
**PUT**\
`https://dashboard.fstrk.io/api/partners/integrations/credentials/update/`
> ℹ️ Полное описание этого метода можно найти в [Swagger](https://dashboard.fstrk.io/api/partners/docs/#/01.%20%D0%9C%D0%B5%D1%82%D0%BE%D0%B4%D1%8B%20%D0%B4%D0%BB%D1%8F%20%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8/integrations_credentials_update).
***
### Шаг 5. Используем и обновляем токены
#### Как использовать access\_token
Добавляйте его в заголовок каждого запроса:
```
Authorization: Bearer
```
**Срок жизни** — 60 минут, после этого потребуется обновление.
#### Как обновить токены через refresh\_token
Когда access\_token подходит к концу, отправьте запрос:
**POST** `https://dashboard.fstrk.io/api/partners/oauth/`
**Параметры:**
```json
{
"client_id": "ваш_client_id",
"client_secret": "ваш_secret_key",
"grant_type": "refresh_token",
"refresh_token": "ваш_текущий_refresh_token"
}
```
В ответ вы получите **новую пару** токенов.
> ⚠️ **Обратите внимание:**\
> Refresh\_token живёт **24 часа**. Если за это время вы не обновите токены, процедуру придётся начать заново с ручного шага №2.
***
### 🔁 Рекомендуемая схема автоматизации
```
1. Вы присылаете нам redirect_uri
2. Мы выдаём вам client_id + secret_key
3. Вы вручную (один раз):
- переходите по ссылке с client_id и redirect_uri
- нажимаете "Подключить"
- копируете временный код
4. Ваш скрипт:
- обменивает code на токены
- подписывается на вебхуки
- каждые 50–55 минут обновляет токены через refresh_token
5. Если прошло больше 24 часов без активности - повторяете шаг 3
```
