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

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

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

Чтобы настроить функционал REST API, перейдите в раздел «Настройки» на вкладку «API».

«Настройки» - «API»

На странице располагаются ссылки на документацию по REST API:

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

Работа с документацией elements

Документация elements для вашей организации расположена здесь:

URL сервера, на который будут идти API запросы для вашей организации, прописан в документации.

Отправка запросов из документации elements

Чтобы отправить запрос из документации elements, введите токен в области с кнопкой «Send API Request». Данное окно есть на каждой странице, где можно выполнить запрос.

Работа с документацией swagger-ui

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

Отправка запросов из документации swagger-ui

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

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

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

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

Создание токена доступа

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

Токен доступа может быть создан только владельцем организации. Для этого необходимо нажать «Создать токен доступа»:

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

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

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

Токен отобразится в списке:

После удаления токен доступа становится неактивным.

Подключение внешнего приложения с помощью OAuth2 к Admin24

REST API Admin24, помимо простого токена, поддерживает работу по протоколу Oauth2.0 «Authorization Code Flow». Общее описание этого метода авторизации вы можете найти по ссылке: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow

Порядок создания интеграции с Admin24

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

Шаг 1.

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

Шаг 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 должны быть подставлены значения:

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

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

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

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

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

CODE – будет использоваться для получения токена доступа.
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'
}

где:

expires_in – количество секунд до истечения токена access_token;
access_token – токен доступа, который позволяет делать API запроса от имени пользователя, который был авторизован;
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'
}

Примеры запросов к API Admin24:

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

Описание и формат вызовов поддерживаемых методов API приведены в документации в формате swagger-ui по ссылке https://[поддомен портала].admin24.app/api-documentation/swagger-ui/index.html, которая доступна зарегистрированным сотрудникам организации.

Выполнение запроса к API
«Send API Request»

Для выполнения запроса к 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;
получение списка комментариев к заявке;
получение комментария к заявке, создание заявки;
удаление заявки (в корзину или полностью).

Что делать, если возникли сложности?

Позвоните нам по телефону: 8 (800) 333-66-24, напишите на электронную почту: admin24@infoservice.ru или в Telegram. Принимаем звонки в любое время с 09:30 до 18:00 с понедельника по пятницу.

Мы поможем и расскажем, как настроить Admin24 под ваши нужды.

← Вернуться в Справочный центр

Справочный центр Admin24