Admin24

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

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

  1. Создание токена доступа.
  2. Подключение внешнего приложения с помощью OAuth2.
    Чтобы настроить функционал REST API, перейдите в раздел «Настройки» на вкладку «API».
    вход в личный кабинет gupshup
    «Настройки» - «API»
    На странице располагаются ссылки на документацию по REST API:
    документация REST API
    Вы можете использовать ту документацию, с которой вам будет удобнее работать.

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

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

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

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

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

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

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

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

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

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

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

    • введите имя токена доступа;
    • выберите права;
    • введите пароль от аккаунта;
    • нажмите «ПОДТВЕРДИТЬ».
    создание токена доступа REST API
    Ниже отобразится сам токен доступа и его нужно будет сохранить, т.к. после закрытия окна он будет недоступен:
    токен доступа REST 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»→«Приложения».
    «API»→«Приложения»
    Шаг 2.

    Нажмите на кнопку «Добавить приложение»:
    добавить приложение rest api
    1. Название: Тестовое приложение.

    2. URL Приложения: https://[домен вашей интеграции]/[ваш путь к обработчику] – это URL, по которому будет перенаправлен пользователь после успешной авторизации в Admin24.
    пример создания приложения rest api
    Вместе с приложением также будет создан OAuth2 Client, который можно использовать для авторизации пользователя (получения токена доступа) в другом приложении.

    Шаг 3.


    После создания OAuth2 Client вам будут предоставлены Client ID и Client Secret, которые нужно скопировать и использовать во внешнем приложении.
    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'
    }
    
    
    Примеры запросов к 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:
    Пример запроса с использованием 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 под ваши нужды.