Download the PHP package kenny-mgn/profitbase-php-client without Composer

Profitbase API Client for PHP

Содержание

• Описание
• Требования
• Установка
• Быстрый старт
• Query-параметры
  • Передача множественных значений
• Конфигурация HTTP-клиента (Guzzle)
• Потоковый режим
• Ограничение частоты запросов (Rate Limit)
  • Асинхронность и многопоточность
• Методы доступа к Profitbase API
• Обратная связь
• Лицензия

Описание

Profitbase API Client for PHP – это обёртка над HTTP-клиентом Guzzle, предназначенная для взаимодействия с Profitbase API. Данный пакет реализует автоматическое управление токеном доступа (access token): его первоначальное получение, обновление по истечении срока действия и троттлинг запросов для соблюдения ограничений частоты обращений (rate limit) к Profitbase API.

Требования

• PHP >= 8.1
• PHP Extensions: curl, json

Установка

Быстрый старт

Методы запросов к Profitbase API возвращают ответ в виде ResponseInterface. Основные методы:

Query-параметры

Во всех методах обращения к Profitbase API можно передавать дополнительные query-параметры через массив $queryParams.

Если эндпоинт имеет стандартные параметры, они обычно уже вынесены в сигнатуру метода, например:

Параметры $isArchived и $isDiscounted — основные, определённые в методе.

Массив $queryParams позволяет добавлять любые другие query-параметры для гибкости, даже если эндпоинт сейчас их не принимает.

Передача множественных значений в query-параметрах

В Profitbase API для передачи нескольких значений одного параметра query string должен иметь вид:

В данном пакете это достигается созданием массива вида:

Библиотека автоматически преобразует такой массив в правильный формат query string для запроса к API.

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

Конфигурация HTTP-клиента (Guzzle)

При создании экземпляра клиента ProfitbaseClient можно передавать массив $httpClientConfig с дополнительными параметрами конфигурации Guzzle. Любые переданные параметры переопределяют стандартные настройки HTTP-клиента,
что позволяет гибко управлять поведением соединений, таймаутами, заголовками и другими опциями.

Пример создания клиента с кастомной конфигурацией:

Все доступные параметры Guzzle можно найти в официальной документации: Guzzle Request Options.

Потоковый режим

По умолчанию клиент работает в потоковом режиме, позволяющем обрабатывать данные по мере их поступления и использовать библиотеки вроде cerbero/json-parser для порционной обработки больших JSON-ответов.

Чтобы создать экземпляр клиента не в потоковом режиме, передайте параметр конфигурации stream => false:

Ограничение частоты запросов (Rate Limit)

Profitbase API ограничивает частоту обращений: не более одного запроса в секунду от одного клиента. Чтобы соблюдать это требование, класс ProfitbaseClient включает встроенный механизм ограничения количества запросов. По умолчанию между последовательными запросами выдерживается пауза в 1 секунду.

Интервал можно изменить методом:

Асинхронность и многопоточность

Класс ProfitbaseClient реализован синхронно — все запросы выполняются последовательно в одном потоке. Он не поддерживает асинхронные вызовы или параллельное выполнение запросов из коробки.

Если вы попытаетесь выполнять несколько запросов одновременно (например, из разных потоков или процессов), ограничение на уровне PHP-кода не сможет их синхронизировать — в этом случае ограничение частоты запросов нужно обеспечивать самостоятельно.

Методы доступа к Profitbase API

Раздел описывает публичные методы класса ProfitbaseClient, соответствующие эндпоинтам Profitbase API, с указанием HTTP-метода, пути и поддерживаемых параметров.

Структура данного раздела (группировка и наименования) повторяет структуру официальной документации Profitbase API. Это сделано для удобства навигации и быстрой сопоставимости методов клиента с эндпоинтами API.

Подробное описание параметров запросов (включая query string и body) и форматов ответов см. в официальной документации Profitbase: https://developer.profitbase.ru/.

Навигация по методам доступа к Profitbase API

auth

• Авторизация

houses

• Метод получения списка домов с возможностью фильтрации
• Метод получения количества этажей в конкретном доме
• Метод получения количества помещений в конкретном доме на конкретном этаже
• Устаревший метод v3 получения списка домов
• Метод создания дома в существующий ЖК
• Метод обновления данных в конкретном доме
• Метод для поиска домов по названию, адресу и названию ЖК

projects

• Метод получения списка ЖК
• Метод создания ЖК
• Метод обновления ЖК
• Метод для поиска ЖК по названию, адресу и названию дома, названию застройщика

properties

• Метод получения списка помещений с возможностью фильтрации
• Метод создания помещения в конкретный дом
• Метод обновления данных в конкретном помещении
• Метод получения списка типов помещений и их дополнительных полей
• Метод получения списка помещений привязанных к конкретной сделке
• Метод получения истории изменения статусов по конкретному помещению
• Устаревший метод v3 получения списка помещений в конкретном доме
• Метод получения списка сделок привязанных к конкретным помещениям
• Метод изменения статуса помещения
• Метод продления брони в конкретном помещении

board

• Метод получения шахматки дома

presets

• Метод получения планировок помещений с возможностью фильтрации
• Устаревший метод получения планировок помещений в доме

facade

• Метод получения списка фасадов дома

floor

• Метод получения планировок этажей дома

actions

• Метод получения списка активных акции со списком помещений по каждой акции

crm

• Метод получения списка сделок или конкретной сделки
• Метод получения списка сделок в которые добавлено конкретное помещение
• Метод добавления помещения в сделку
• Метод удаления помещений из сделки
• Метод обновления полей Proftibase в сделке по помещению
• Метод синхронизации статуса помещения с этапом сделки CRM согласно разметке статусов приложения CRM для Profitbase

order

• Метод создания заявки на помещение

history

• Метод получения истории изменения статусов помещений с возможностью фильтрации

statuses

• Метод получения списка статусов для crm, или конкретного статуса по id

filter

• Метод для получения списка отображаемых в виджете фильтров
• Метод для получения списка доступных отделок для отображения в фильтре по отделке
• Получить характеристики для фильтра

property-specification

• Метод получения списка характеристик для помещений с количеством аналогичных помещений в доме
• Получить список всех характеристик
• Получить характеристики по дому

queue-reserve

• Метод получения списка очереди бронирования по указанному помещению
• Метод для удаления сделки из очереди бронирования
• Метод для добавления сделки в очередь бронирования
• Метод для изменения порядка сделок в очереди бронирования

render

• Метод получения списка генпланов

users

• Метод для получения информации о пользователях
• Метод для изменения прав пользователей
• Инициализация сброса пароля для пользователя

stock-version

• Получить изменения по версиям

⚠️ Примечание о непроверенных методах

На реальном API была проверена работоспособность только идемпотентных методов (выполняющих безопасные операции не изменяющие состояние системы). Это связано с тем, что тестирование проводилось с доступом только на чтение.

Методы, выполнение которых изменяет состояние данных, не были проверены на реальном API. Такие методы в документации помечены специальным образом: ⚠️ Не проверено на реальном API.

auth

Авторизация

Метод для аутентификации. Возвращает access_token для доступа к API.

⚠️ Примечание: вызов auth() не обязателен — клиент автоматически обрабатывает получение, обновление и передачу access_token при каждом запросе.

Эндпоинт: POST /authentication

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

houses

Метод получения списка домов с возможностью фильтрации

Эндпоинт: GET /house

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод получения количества этажей в конкретном доме

Эндпоинт: GET /house/get-count-floors

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод получения количества помещений в конкретном доме на конкретном этаже

Эндпоинт: /house/get-count-properties-on-floor

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Устаревший метод v3 получения списка домов

Эндпоинт: /projects/{projectId}/houses

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод создания дома в существующий ЖК

⚠️ Не проверено на реальном API

Эндпоинт: POST /house

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод обновления данных в конкретном доме

⚠️ Не проверено на реальном API

Эндпоинт: PUT /houses/{id}

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод для поиска домов по названию, адресу и названию ЖК

Эндпоинт: GET /houses/search

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

projects

Метод получения списка ЖК

Эндпоинт: GET /projects

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод создания ЖК

⚠️ Не проверено на реальном API

Эндпоинт: POST /projects

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод обновления ЖК

⚠️ Не проверено на реальном API

Эндпоинт: PUT /projects/{id}

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод для поиска ЖК по названию, адресу и названию дома, названию застройщика

Эндпоинт: GET /projects/search

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

properties

Метод получения списка помещений с возможностью фильтрации

Эндпоинт: GET /property

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод создания помещения в конкретный дом

⚠️ Не проверено на реальном API

Эндпоинт: POST /properties

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод обновления данных в конкретном помещении

⚠️ Не проверено на реальном API

Эндпоинт: PATCH /properties/{propertyId}

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод получения списка типов помещений и их дополнительных полей

Эндпоинт: GET /property-types

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод получения списка помещений привязанных к конкретной сделке

Эндпоинт: GET /property/deal/{dealId}

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод получения истории изменения статусов по конкретному помещению

Эндпоинт: GET /property/history/{propertyId}

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Устаревший метод v3 получения списка помещений в конкретном доме

Эндпоинт: GET /projects/{projectId}/houses/{houseId}/properties/list

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод получения списка сделок привязанных к конкретным помещениям

Эндпоинт: GET /get-property-deals

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод изменения статуса помещения

⚠️ Не проверено на реальном API

Эндпоинт: POST /properties/{id}/status-change

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод продления брони в конкретном помещении

⚠️ Не проверено на реальном API

Эндпоинт: PATCH /reserve/prolong

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

board

Метод получения шахматки дома

Эндпоинт: GET /board

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

presets

Метод получения планировок помещений с возможностью фильтрации

Эндпоинт: GET /plan

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Устаревший метод получения планировок помещений в доме

Эндпоинт: GET /projects/{projectId}/houses/{houseId}/presets

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

facade

Метод получения списка фасадов дома

Эндпоинт: GET /facade

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

floor

Метод получения планировок этажей дома

Эндпоинт: GET /floor

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

actions

Метод получения списка активных акции со списком помещений по каждой акции

Эндпоинт: GET /special-offer

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

crm

Метод получения списка сделок или конкретной сделки

Эндпоинт: GET /crm/deals

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод получения списка сделок в которые добавлено конкретное помещение

Эндпоинт: GET /crm/deals/property/{propertyId}

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод добавления помещения в сделку

⚠️ Не проверено на реальном API

Эндпоинт: POST /crm/addPropertyDeal

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод удаления помещений из сделки

⚠️ Не проверено на реальном API

Эндпоинт: POST /crm/removePropertyDeal

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод обновления полей Proftibase в сделке по помещению

⚠️ Не проверено на реальном API

Эндпоинт: GET /crm/update/deal/{dealId}/property/{propertyId} Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод синхронизации статуса помещения с этапом сделки CRM согласно разметке статусов приложения CRM для Profitbase

⚠️ Не проверено на реальном API

Эндпоинт: GET /crm/syncPropertyStatus

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

order

Метод создания заявки на помещение

⚠️ Не проверено на реальном API

Эндпоинт: POST /orders

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

history

Метод получения истории изменения статусов помещений с возможностью фильтрации

Эндпоинт: POST /history

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

statuses

Метод получения списка статусов для crm, или конкретного статуса по id

Эндпоинт: GET /custom-status/list

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

filter

Метод для получения списка отображаемых в виджете фильтров

Эндпоинт: GET /filter

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод для получения списка доступных отделок для отображения в фильтре по отделке

Эндпоинт: GET /filter/facings

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Получить характеристики для фильтра

Эндпоинт: GET /filter/property-specifications

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

property-specification

Метод получения списка характеристик для помещений с количеством аналогичных помещений в доме

Эндпоинт: /property-specification

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Получить список всех характеристик

Эндпоинт: GET /property-specification/list

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Получить характеристики по дому

Эндпоинт: GET /property-specification/house

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

queue-reserve

Метод получения списка очереди бронирования по указанному помещению

Эндпоинт: GET /queue-reserve/list Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод для удаления сделки из очереди бронирования

⚠️ Не проверено на реальном API

Эндпоинт: POST /queue-reserve/delete

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод для добавления сделки в очередь бронирования

⚠️ Не проверено на реальном API

Эндпоинт: POST /queue-reserve

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод для изменения порядка сделок в очереди бронирования

⚠️ Не проверено на реальном API

Эндпоинт: POST /queue-reserve/change-position

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

render

Метод получения списка генпланов

Эндпоинт: GET /render

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

users

Метод для получения информации о пользователях

Эндпоинт: GET /user/info

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Метод для изменения прав пользователей

⚠️ Не проверено на реальном API

Эндпоинт: PATCH /user/{userId}/access

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Инициализация сброса пароля для пользователя

⚠️ Не проверено на реальном API

Эндпоинт: GET /user/{userId}/password/forgot

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

stock-version

Получить изменения по версиям

Эндпоинт: POST /versions/find

Сигнатура:

Пример вызова:

⤴ Вернуться к навигации по методам

Обратная связь

Если вы нашли ошибку или хотите предложить улучшение — создайте issue.

Лицензия

Проект распространяется под лицензией MIT.