Категории

Инструкция по работе с приложением «API Profitbase»

После успешной активации приложения «API Profitbase», формирования API-ключа и добавления статичного IP адреса, с которого планируете отправлять API запросы в сторону аккаунта Profitbase, можете приступить к тестированию методов API Profitbase для написания основного кода интеграции по API.

Учитывайте, что можно отправлять не более 1 запроса в секунду. В противном случае сервер Profitbase будет расценивать частые запросы как угрозу, и в итоге заблокирует IP адрес отправителя.

Лишние символы или использование других символов в запросе (одинарные кавычки вместо двойных, лишние знаки «/» и т.п.) приведут к ошибкам запросов.
Для работы с API Profitbase у вас должен быть статичный IP адрес, или диапазон статичных IP адресов, от которых планируется отправка API запросов.
Соблюдайте общие требования документации API Profitbase. Документацию можно найти на сайте https://developer.profitbase.ru

В заголовках обязательно необходимо передавать Content_type запросов – application/json.

Дальнейшая инструкция будет строиться на основе работы с программой «Postman»


1. Авторизация (Authentication) и получение access_token для дальнейшей работы с «API Profitbase».
1.1 Без токена авторизации невозможно получить корректный ответ на API запрос.
Что бы получить его потребуется отправить отдельный запрос авторизации.
Следуя документации https://developer.profitbase.ru, укажите в настройках Postman корректный URL API Endpoint в формате https://pbXXX.profitbase.ru/api/v4/json. При этом вместо ХХХ требуется указать номер аккаунта Profitbase, в котором формировали API-ключ. Например, если ваш аккаунт https://pb12345.profitbase.ru , то вместо «ХХХ» необходимо указать «12345».


1.2 Так как основная цель – получение access_token с помощью метода авторизации, то дополнительно укажите в URL адресе API Endpoint путь (PATH), добавив его через «/», что бы получилась такая вот ссылка URL https://pbXXX.profitbase.ru/api/v4/json/authentication (вместо ХХХ укажите свой номер аккаунта)


В разделе «OPERATIONS» => «Auth» => «Авторизация» так же указывается, что запрос должен иметь content-type application/json, и метод POST, а справа есть пример кода, который должен быть добавлен в тело запроса (Request Body):


Сформируем итоговый запрос в программе Postman:

  • Указываем метод «POST»;
  • Указываем URL API Endpoint, с уточнением пути «/authentication» и корректным номером аккаунта Profitbase;
  • Отмечаем формат «RAW» и выбираем content_type «JSON»;
  • Выбираем раздел «BODY» и вставляем код из документации API Profitbase;
  • В коде указываем API ключ, сформированный нами ранее в приложении аккаунта Profitbase;
  • Нажимаем справа синюю кнопку «Send»;
  • Ниже видим статус запроса «200 OK»;
  • В результатах видим сформированный «access_token», именно он нам понадобится в будущем для работы с другими методами API.


2. Использование полученного значения access_token в дальнейшей работе с API методами.

После получения токена мы можем продолжить работу с API, и сформировать любой запрос на получение или изменение данных аккаунта Profitbase, используя методы POST, GET, DELETE и т.д..

Для примера сформируем запрос на получение списка всех домов во всех ЖК аккаунта Profitbase с указанием количества помещений в домах.

Данный метод находится в разделе документации API Profitbase «OPERATIONS» => «Houses» => «Метод получения списка домов с возможностью фильтрации».

Согласно документации, в отличие от запроса на получение access_token, теперь будем использовать метод «GET» и путь «/house», а также укажем полученный ранее access_token в параметрах нового запроса.

В результате мы получим данные о всех существующих ЖК, домах и количестве помещений аккаунта. В последующем мы можем использовать полученную информацию для уточнения API запроса с использованием дополнительного параметра фильтрации.


3. API запрос с параметрами фильтрации.

Если мы хотим получить данные только о 2-х определённых ЖК, то потребуется найти в полученных ранее данных о ЖК строку «projectId», которая содержит уникальный номер ЖК.

Затем, используя значения уникальных номеров ЖК, сформируем новый API запрос, который будет содержать дополнительный параметр фильтрации по ID ЖК «projectIds[]»:



Итоговый запрос в программе Postman будет выглядеть вот так:


Частые ошибки запросов API:
  • Ошибка 403 Not allowed - убедитесь, что IP, с которого вы отправляете запрос, есть в списке разрешенных адресов вашего аккаунта Profitbase. Если его нет в списке и необходимо добавить - напишите об этом в техническую поддержку Profitbase.
  • Ошибка 405 Method Not Allowed - убедитесь, что используете корректный метод запроса (GET, POST и т.д.).
  • "error": "Not allowed." - убедитесь, что передаете в заголовке Content-Type application/json.

По вопросам работы с документацией API Profitbase обращайтесь в тех.поддержку support@profitbase.ru