REST API. Настройка REST API для создания заявок из любых веб-форм

Чтобы настроить функционал REST API для создания заявок из любых веб-форм, вы можете воспользоваться одним из предложенных способов:

1. Создание токена доступа.
2. Подключение внешнего приложения с помощью OAuth2.

Для отправки запросов из документации swagger-ui выполните ряд действий:

• нажмите кнопку «Authorize»;

• введите токен в модальном окне и нажмите «Authorize»;

• нажмите «Close», чтобы закрыть окно;
• у выбранного API нажмите кнопку «Try it out»;
• введите параметры запроса, если они есть;
• нажмите кнопку «Execute», чтобы выполнить запрос.

В появившемся окне:

• введите имя токена доступа;
• выберите права;
• введите пароль от аккаунта;
• нажмите «ПОДТВЕРДИТЬ».

Для интеграции необходим собственный домен (возможно использование любых доменов, в том числе третьего и большего уровней) и хостинг.

Шаг 1.

Перейдите на страницу «Настройки» на вкладку «API»→«Приложения».

Шаг 2.

Нажмите на кнопку «Добавить приложение»:

1. Название: Тестовое приложение.
2. URL Приложения: https://[домен вашей интеграции]/[ваш путь к обработчику] – это URL, по которому будет перенаправлен пользователь после успешной авторизации в Admin24.

Вместе с приложением также будет создан OAuth2 Client, который можно использовать для авторизации пользователя (получения токена доступа) в другом приложении.

Шаг 3.

После создания OAuth2 Client вам будут предоставлены Client ID и Client Secret, которые нужно скопировать и использовать во внешнем приложении.

Во внешнем приложении должна быть кнопка или ссылка, вроде «Войти через Admin24», «Подключить Admin24».

При нажатии на кнопку должен открываться URL:

https://subdomain.admin24.app/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URL&scope=SCOPE&state=STATE

где subdomain – это поддомен вашей организации в Admin24.

В этом URL должны быть подставлены значения:

1. CLIENT_ID – Client ID приложения, который был создан в разделе «Настройки» на вкладке «API».
2. REDIRECT_URL – URL приложения, который был создан в разделе «Настройки» на вкладке «API».
3. SCOPE – здесь должны быть указаны права, которые будут запрашиваться. Права следует указывать через пробел, например, если заявки – tickets, а пользователи – users, то правильно указанные права будут выглядеть так: «tickets users».
4. STATE – можно задать любое значение. Это значение придет в запросе на REDIRECT_URL. С помощью STATE происходит защита от CSRF-атак.

После перехода по данному URL в браузере откроется страница с авторизацией в Admin24:

При нажатии на кнопку «Авторизовать» пользователь будет перенаправлен на страницу внешнего приложения:

http://[домен вашей интеграции]/?code=CODE&state=STATE

в строке запроса будут

1. CODE – будет использоваться для получения токена доступа.
2. STATE – значение такое же, как и в запросе на URL: https://subdomain.admin24.app/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URL&scope=SCOPE&state=STATE

Далее можно получить токен доступа. Пример с axios:

await axios.post(
            'https://subdomain.admin24.app/oauth/token',
            {
                grant_type: 'authorization_code',
                client_id: CLIENT_ID,
                client_secret: CLIENT_SECRET,
                redirect_uri: REDIRECT_URL,
                code: CODE,
            },
        );

в котором:

• CLIENT_ID, CLIENT_SECRET, REDIRECT_URL – это параметры приложения на странице «Настройки» на вкладке «API»→«Приложения».
• CODE – полученное значение в строке запроса.

Пример ответа:

{
  token_type: 'Bearer',
  expires_in: 3600,
  access_token: 'eyJ0eXAi … azmxujJLY',
  refresh_token: 'def502008 … 9e461'
}

где:

1. expires_in – количество секунд до истечения токена access_token;
2. access_token – токен доступа, который позволяет делать API запроса от имени пользователя, который был авторизован;
3. refresh_token – токен, который можно использовать для того, чтобы получить новый access_token, когда он будет просрочен.

Пример использования refresh_token:

await axios.post(
    'https://subdomain.admin24.app/oauth/token',
    {
        grant_type: 'refresh_token',
        client_id: CLIENT_ID,
        client_secret: CLIENT_SECRET,
        refresh_token: REFRESH_TOKEN,
    },
);

{
  token_type: 'Bearer',
  expires_in: 3600,
  access_token: 'eyJ0eXAiOi … WotiudT8',
  refresh_token: 'def502 … 5126'
}

await axios.get(
        'https://subdomain.admin24.app/api/user',
        {
            headers: {
              Accept: 'application/json',
              Authorization: 'Bearer eyJ0eXAiOi … WotiudT8’
            }
        },
    );

Для выполнения запроса к API требуется указать два HTTP заголовка: Authorization: Bearer eyJ0eXAiOiJKV1QiJSVaR4MGLjCElXyug и Accept: application/json, где eyJ0eXAiOiJKV1QiJSVaR4MGLjCElXyug – ваш токен доступа, созданный на странице настроек API.

Пример запроса с использованием curl:

Полный код пагинации вы можете увидеть в документации по REST API в вашем аккаунте. В ней:

meta.per_page – максимальное количество элементов в data на страницу.

meta.total – общее количество элементов.

Текущую страницу с элементами можно выбрать с помощью параметра запроса ?page=3.

Для запроса всех данных достаточно запросить данные с первой по последнюю meta.last_page страницы.

Для запросов с постраничной выдачей данных размеры страниц установлены фиксированные. Их значения:

GET /api/users - 100;
POST /api/tickets - 10;
POST /api/comments - 100;
POST /api/active-forms - 100.

В REST API доступны следующие методы:

• получение текущего пользователя;
• получение списка пользователей организации;
• получение списка заявок;
• получение информации о заявке по ее UUID;
• получение информации о заявке по ее ID;
• получение списка комментариев к заявке;
• получение комментария к заявке, создание заявки;
• удаление заявки (в корзину или полностью).