Home Original page

GitHub - rumantic/sitebill_api_php_sdk

Документация Sitebill API PHP SDK

Оглавление

  1. Введение
  2. Установка
  3. Быстрый старт
  4. Аутентификация
  5. Методы SDK
  6. Работа с моделями (Model API)
  7. Работа с пользователями (User API)
  8. Работа с профилями (Profile API)
  9. Работа с загрузками файлов (Uploads API)
  10. Работа с комментариями (Comment API)
  11. Работа с бронированием (Reservation API)
  12. Работа с поиском (MySearch API)
  13. Работа со списками памяти (MemoryList API)
  14. Работа со слоями (Layers API)
  15. Работа с конфигурацией (Config API)
  16. Работа со статистикой (Stat API)
  17. Регистрация (Register API)
  18. Обработка ошибок
  19. Примеры использования

Введение

Sitebill API PHP SDK — это библиотека для взаимодействия с REST API системы управления контентом Sitebill. SDK предоставляет простой объектно-ориентированный интерфейс для выполнения операций CRUD (Create, Read, Update, Delete) над данными, управления пользователями, файлами и другими сущностями системы.

Основные возможности:

  • Аутентификация через OAuth
  • Работа с моделями данных (CRUD операции)
  • Управление пользователями и профилями
  • Загрузка файлов
  • Работа с комментариями
  • Система бронирования
  • Расширенный поиск
  • Работа с конфигурацией
  • Статистика

Установка

Требования

  • PHP 5.6 или выше
  • Расширение cURL
  • Доступ к серверу Sitebill с включенным API

Способ 1: Скачивание из репозитория

git clone https://github.com/rumantic/sitebill_api_php_sdk.git
cd sitebill_api_php_sdk

Способ 2: Прямое подключение

Скачайте файл sitebill_sdk.php и подключите его в вашем проекте:

require_once 'path/to/sitebill_sdk.php';

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

Инициализация и подключение

<?php
require_once 'sitebill_sdk.php';

// Инициализация SDK
$api = new Sitebill_SDK(
    'http://your-domain.com/apps/api/rest.php',  // URL API endpoint
    'admin',                                       // Логин
    'password'                                     // Пароль
);

// Подключение к API
if ($api->connect()) {
    echo "Успешное подключение!\n";
} else {
    echo "Ошибка подключения\n";
}

Простой пример работы

// Создание новой записи
$data = [
    'topic_id' => 1,
    'city_id' => 1,
    'text' => 'Новое объявление',
    'price' => 5000000
];

$result = $api->native_insert('data', $data);
$new_id = $result['data']['new_record_id'];
echo "Создана запись с ID: $new_id\n";

// Загрузка записи
$record = $api->load_data('data', 'id', $new_id);
print_r($record);

// Удаление записи
$api->delete('data', 'id', $new_id);

Аутентификация

Метод connect()

Устанавливает соединение с API и получает session_key для дальнейших запросов.

$api = new Sitebill_SDK($url, $login, $password);
$connected = $api->connect();

if (!$connected) {
    die('Не удалось подключиться к API');
}

Возвращает: bool - true при успешной аутентификации, false при ошибке

Внутренний метод get_auth($login, $password)

Получает session_key по логину и паролю. Вызывается автоматически при connect().

Параметры:

  • $login (string) - Логин пользователя
  • $password (string) - Пароль

Возвращает:

[
    'success' => true,
    'session_key' => 'abc123...'
]

Endpoint: POST /apps/api/rest.php Параметры запроса:

[
    'action' => 'oauth',
    'do' => 'login',
    'login' => 'admin',
    'password' => 'password'
]

Методы SDK

1. load_grid_columns($model_name)

Загружает список колонок для указанной модели.

Параметры:

  • $model_name (string) - Название модели (например, 'data', 'user', 'page')

Возвращает: array - Массив с описанием колонок модели

Пример:

$columns = $api->load_grid_columns('data');
print_r($columns);

Ответ:

[
    'state' => 'success',
    'columns' => [
        [
            'name' => 'id',
            'type' => 'primary_key',
            'title' => 'ID',
            ...
        ],
        [
            'name' => 'text',
            'type' => 'textarea',
            'title' => 'Описание',
            ...
        ]
    ]
]

2. native_insert($model_name, $ql_items)

Добавляет новую запись в таблицу модели.

Параметры:

  • $model_name (string) - Название модели
  • $ql_items (array) - Ассоциативный массив значений полей

Возвращает: array - Результат операции с ID новой записи

Пример:

$data = [
    'topic_id' => 6162,      // Тип недвижимости
    'city_id' => 1,          // Город
    'street_id' => 100,      // Улица
    'text' => 'Продается квартира',
    'price' => 10000000,
    'square_all' => 75.5,
    'floor' => 5,
    'room_count' => 3
];

$result = $api->native_insert('data', $data);

if ($result['state'] == 'success') {
    $new_id = $result['data']['new_record_id'];
    echo "Создана запись ID: $new_id\n";
}

Ответ:

[
    'state' => 'success',
    'data' => [
        'new_record_id' => 12345
    ]
]

3. load_data($model_name, $primary_key, $key_value)

Загружает данные одной записи из таблицы.

Параметры:

  • $model_name (string) - Название модели
  • $primary_key (string) - Имя первичного ключа (обычно 'id')
  • $key_value (int) - Значение первичного ключа

Возвращает: array - Полные данные записи со всеми полями

Пример:

$record = $api->load_data('data', 'id', 12345);

if ($record['state'] == 'success') {
    echo "Цена: " . $record['data']['price']['value'] . "\n";
    echo "Описание: " . $record['data']['text']['value'] . "\n";
}

Структура ответа:

[
    'state' => 'success',
    'id' => 12345,
    'primary_key' => 'id',
    'table_name' => 'data',
    'data' => [
        'id' => [
            'name' => 'id',
            'value' => 12345,
            'title' => 'ID',
            'type' => 'primary_key'
        ],
        'text' => [
            'name' => 'text',
            'value' => 'Продается квартира...',
            'title' => 'Описание',
            'type' => 'textarea'
        ],
        'price' => [
            'name' => 'price',
            'value' => 10000000,
            'title' => 'Цена',
            'type' => 'text'
        ]
    ]
]

4. delete($model_name, $primary_key, $key_value)

Удаляет запись из таблицы.

Параметры:

  • $model_name (string) - Название модели
  • $primary_key (string) - Имя первичного ключа
  • $key_value (int) - Значение первичного ключа

Возвращает: array - Результат операции

Пример:

$result = $api->delete('data', 'id', 12345);

if ($result['state'] == 'success') {
    echo "Запись успешно удалена\n";
}

Ответ:

[
    'state' => 'success',
    'message' => 'Record deleted'
]

Работа с моделями (Model API)

API для работы с моделями предоставляет расширенные возможности управления данными.

Endpoint: action=model

Доступные методы (параметр do):

1. get_models

Получает список всех моделей в системе.

Запрос:

POST /apps/api/rest.php
action=model
do=get_models
session_key=xxx

Ответ:

[
    ['id' => 1, 'name' => 'data'],
    ['id' => 2, 'name' => 'user'],
    ['id' => 3, 'name' => 'page']
]

2. get_models_list

Получает расширенный список моделей с описаниями.

Ответ:

[
    'status' => 'success',
    'message' => 'models loaded',
    'data' => [
        [
            'id' => 1,
            'name' => 'data',
            'description' => 'Объявления'
        ],
        [
            'id' => 2,
            'name' => 'user',
            'description' => 'Пользователи'
        ]
    ]
]

3. load_config

Загружает публичную конфигурацию системы.

Ответ:

[
    'state' => 'success',
    'data' => [
        'site_title' => 'Мой сайт',
        'site_url' => 'http://example.com',
        'languages' => ['ru', 'en', 'tj'],
        'apps.mailbox.complaint_mode_variants' => [
            'spam' => 'Спам',
            'fraud' => 'Мошенничество'
        ]
    ]
]

4. load_only_model

Загружает структуру модели без данных.

Параметры:

  • model_name - название модели

Ответ:

[
    'state' => 'success',
    'columns' => [...],
    'columns_index' => [...],
    'data' => [...],
    'tabs' => [...]
]

5. load_data

Загружает данные записи с проверкой прав доступа.

Параметры:

  • model_name - название модели
  • primary_key - имя первичного ключа
  • key_value - значение ключа
  • entity_uri (опционально) - URI сущности
  • ql_items (опционально) - массив для фильтрации полей

Пример с фильтрацией полей:

POST /apps/api/rest.php
action=model
do=load_data
model_name=data
primary_key=id
key_value=100
ql_items[text]=1
ql_items[price]=1

Вернет только поля text и price.

6. graphql_update

Обновляет только указанные поля записи (GraphQL-стиль).

Параметры:

  • model_name - название модели
  • key_value - ID записи
  • ql_items - массив полей для обновления
  • only_ql (optional) - если true, обновляет только указанные поля

Пример:

$params = [
    'action' => 'model',
    'do' => 'graphql_update',
    'model_name' => 'data',
    'key_value' => 100,
    'ql_items' => [
        'price' => 15000000,
        'active' => 1
    ],
    'only_ql' => true
];

JavaScript пример:

$.ajax({
    url: '/apps/api/rest.php',
    data: {
        action: 'model',
        do: 'graphql_update',
        model_name: 'data',
        only_ql: true,
        key_value: 100,
        ql_items: {
            active: 0
        }
    },
    type: 'post',
    success: function(response) {
        console.log(response);
    }
});

7. native_insert

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

Дополнительные возможности:

  • Автоматическое создание URI из заголовка
  • Обработка geodata (координат)
  • Загрузка связанных данных

Пример:

POST /apps/api/rest.php
action=model
do=native_insert
model_name=data
ql_items[topic_id]=6162
ql_items[city_id]=1
ql_items[text]=Новое объявление
ql_items[price]=5000000
ql_items[geo][lat]=38.5598
ql_items[geo][lng]=68.7738

8. load_grid_columns

Загружает описание колонок для отображения в таблице.

Ответ:

[
    'state' => 'success',
    'columns' => [
        [
            'name' => 'id',
            'title' => 'ID',
            'type' => 'primary_key',
            'show_in_grid' => true,
            'sortable' => true
        ]
    ]
]

9. get_list

Получает список записей с пагинацией и фильтрацией.

Параметры:

  • model_name - название модели
  • page - номер страницы (по умолчанию 1)
  • per_page - записей на страницу (по умолчанию 20)
  • filter - массив фильтров
  • sort_by - поле сортировки
  • sort_order - порядок (ASC/DESC)

Пример:

POST /apps/api/rest.php
action=model
do=get_list
model_name=data
page=1
per_page=10
filter[city_id]=1
filter[price_from]=1000000
sort_by=date_added
sort_order=DESC

Ответ:

[
    'state' => 'success',
    'data' => [
        ['id' => 100, 'text' => '...', 'price' => 5000000],
        ['id' => 101, 'text' => '...', 'price' => 6000000]
    ],
    'pagination' => [
        'total' => 150,
        'per_page' => 10,
        'current_page' => 1,
        'total_pages' => 15
    ]
]

Работа с пользователями (User API)

Endpoint: action=user

1. register

Регистрация нового пользователя.

Параметры:

  • login - логин
  • password - пароль
  • email - email
  • fio - ФИО
  • phone - телефон

Пример:

POST /apps/api/rest.php
action=user
do=register
login=newuser
password=secret123
email=user@example.com
fio=Иван Иванов
phone=+992000000000

2. get_user_info

Получить информацию о текущем пользователе.

Ответ:

[
    'state' => 'success',
    'user_id' => 5,
    'login' => 'admin',
    'email' => 'admin@example.com',
    'fio' => 'Администратор',
    'user_group_id' => 1
]

3. update_profile

Обновление профиля пользователя.

Параметры:

  • user_id - ID пользователя
  • массив полей для обновления

Пример:

POST /apps/api/rest.php
action=user
do=update_profile
user_id=5
fio=Новое имя
phone=+992111111111

Работа с профилями (Profile API)

Endpoint: action=profile

1. load_profile

Загрузка данных профиля.

Параметры:

  • user_id - ID пользователя

Ответ:

[
    'state' => 'success',
    'data' => [
        'user_id' => 5,
        'fio' => 'Иван Иванов',
        'phone' => '+992000000000',
        'company' => 'ООО "Компания"',
        'address' => 'г. Душанбе'
    ]
]

Работа с загрузками файлов (Uploads API)

Endpoint: action=uploads

1. upload_file

Загрузка файла на сервер.

Параметры:

  • file - файл (POST multipart/form-data)
  • model_name - модель для привязки
  • record_id - ID записи

Пример с cURL:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://example.com/apps/api/rest.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'action' => 'uploads',
    'do' => 'upload_file',
    'session_key' => $session_key,
    'model_name' => 'data',
    'record_id' => 100,
    'file' => new CURLFile('/path/to/image.jpg')
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

Ответ:

[
    'state' => 'success',
    'file_id' => 456,
    'file_name' => 'image.jpg',
    'file_url' => '/img/data/image.jpg'
]

2. delete_file

Удаление файла.

Параметры:

  • file_id - ID файла

3. get_files

Получить список файлов записи.

Параметры:

  • model_name - модель
  • record_id - ID записи

Ответ:

[
    'state' => 'success',
    'files' => [
        [
            'id' => 456,
            'name' => 'image.jpg',
            'url' => '/img/data/image.jpg',
            'size' => 102400
        ]
    ]
]

Работа с комментариями (Comment API)

Endpoint: action=comment

1. add_comment

Добавить комментарий.

Параметры:

  • model_name - модель
  • record_id - ID записи
  • text - текст комментария
  • parent_id (optional) - ID родительского комментария

Пример:

POST /apps/api/rest.php
action=comment
do=add_comment
model_name=data
record_id=100
text=Отличное предложение!

2. get_comments

Получить список комментариев.

Параметры:

  • model_name - модель
  • record_id - ID записи

Ответ:

[
    'state' => 'success',
    'comments' => [
        [
            'id' => 1,
            'user_id' => 5,
            'user_name' => 'Иван',
            'text' => 'Отличное предложение!',
            'date_added' => '2024-01-15 10:30:00',
            'replies' => []
        ]
    ]
]

Работа с бронированием (Reservation API)

Endpoint: action=reservation

1. create_reservation

Создать бронирование.

Параметры:

  • record_id - ID объекта
  • date_from - дата начала
  • date_to - дата окончания
  • client_name - имя клиента
  • client_phone - телефон

2. get_reservations

Получить список бронирований.

Параметры:

  • record_id - ID объекта

Работа с поиском (MySearch API)

Endpoint: action=mysearch

1. search

Поиск по записям.

Параметры:

  • model_name - модель для поиска
  • query - поисковый запрос
  • filters - массив фильтров

Пример:

POST /apps/api/rest.php
action=mysearch
do=search
model_name=data
query=квартира
filters[city_id]=1
filters[price_from]=1000000
filters[price_to]=10000000

Работа со списками памяти (MemoryList API)

Endpoint: action=memorylist

Сохранение временных списков (избранное, сравнение и т.д.).

1. add_to_list

Добавить элемент в список.

Параметры:

  • list_name - название списка
  • record_id - ID записи

2. get_list

Получить список.

Параметры:

  • list_name - название списка

Работа со слоями (Layers API)

Endpoint: action=layers

Управление слоями карт (для недвижимости).

Работа с конфигурацией (Config API)

Endpoint: action=config

1. get_config

Получить конфигурацию.

2. update_config

Обновить конфигурацию (требуются права администратора).

Работа со статистикой (Stat API)

Endpoint: action=stat

1. get_stats

Получить статистику.

Параметры:

  • model_name - модель
  • date_from - дата начала
  • date_to - дата окончания

Регистрация (Register API)

Endpoint: action=register

1. register_user

Регистрация нового пользователя с валидацией.

Обработка ошибок

Все ответы API содержат поле state или status:

Успешный ответ:

[
    'state' => 'success',
    'data' => [...]
]

Ответ с ошибкой:

[
    'state' => 'error',
    'message' => 'Описание ошибки',
    'error_code' => 'ERROR_CODE'
]

Типичные ошибки:

Код Описание
check_session_key_failed Неверный или истекший session_key
access_denied Доступ запрещен
model_not_defined Модель не найдена
record_not_found Запись не найдена
validation_error Ошибка валидации данных

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

Пример 1: CRUD операции с объявлениями

<?php
require_once 'sitebill_sdk.php';

$api = new Sitebill_SDK(
    'http://estate.sitebill.ru/apps/api/rest.php',
    'admin',
    'admin'
);

if (!$api->connect()) {
    die('Ошибка подключения');
}

// CREATE - Создание объявления
$newAd = [
    'topic_id' => 6162,  // Квартира
    'city_id' => 1,       // Душанбе
    'street_id' => 50,
    'number' => '10',
    'text' => 'Продается 3-комнатная квартира',
    'price' => 15000000,
    'currency_id' => 1,   // Сомони
    'square_all' => 85.5,
    'square_live' => 60,
    'square_kitchen' => 12,
    'floor' => 5,
    'floor_count' => 9,
    'room_count' => 3,
    'active' => 1
];

$result = $api->native_insert('data', $newAd);
$adId = $result['data']['new_record_id'];
echo "Создано объявление ID: $adId\n";

// READ - Чтение объявления
$ad = $api->load_data('data', 'id', $adId);
echo "Цена: " . $ad['data']['price']['value'] . "\n";
echo "Площадь: " . $ad['data']['square_all']['value'] . " м²\n";

// UPDATE - Обновление через GraphQL
// (требуется прямой HTTP запрос, т.к. в SDK нет этого метода)

// DELETE - Удаление
$api->delete('data', 'id', $adId);
echo "Объявление удалено\n";

Пример 2: Работа с пользователями

<?php
// Получение списка колонок пользователей
$columns = $api->load_grid_columns('user');
print_r($columns);

// Загрузка данных пользователя
$user = $api->load_data('user', 'user_id', 5);
echo "Пользователь: " . $user['data']['login']['value'] . "\n";
echo "Email: " . $user['data']['email']['value'] . "\n";

Пример 3: Массовая загрузка объявлений

<?php
require_once 'sitebill_sdk.php';

$api = new Sitebill_SDK($url, $login, $password);
$api->connect();

// Массив объявлений для загрузки
$ads = [
    ['text' => 'Квартира 1', 'price' => 5000000],
    ['text' => 'Квартира 2', 'price' => 6000000],
    ['text' => 'Квартира 3', 'price' => 7000000],
];

$createdIds = [];

foreach ($ads as $adData) {
    $adData['topic_id'] = 6162;
    $adData['city_id'] = 1;
    $adData['active'] = 1;
    
    $result = $api->native_insert('data', $adData);
    
    if ($result['state'] == 'success') {
        $createdIds[] = $result['data']['new_record_id'];
        echo "Создано: ID {$result['data']['new_record_id']}\n";
    } else {
        echo "Ошибка: " . $result['message'] . "\n";
    }
}

echo "\nВсего создано: " . count($createdIds) . " объявлений\n";

Пример 4: Поиск и фильтрация (прямой HTTP запрос)

<?php
function apiRequest($url, $params) {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    
    $result = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($result, true);
}

// Получение session_key
$authResult = apiRequest($apiUrl, [
    'action' => 'oauth',
    'do' => 'login',
    'login' => 'admin',
    'password' => 'admin'
]);

$sessionKey = $authResult['session_key'];

// Поиск объявлений
$searchResult = apiRequest($apiUrl, [
    'action' => 'model',
    'do' => 'get_list',
    'session_key' => $sessionKey,
    'model_name' => 'data',
    'filter' => [
        'city_id' => 1,
        'price_from' => 1000000,
        'price_to' => 10000000,
        'room_count' => 3
    ],
    'sort_by' => 'date_added',
    'sort_order' => 'DESC',
    'page' => 1,
    'per_page' => 10
]);

foreach ($searchResult['data'] as $ad) {
    echo "ID: {$ad['id']}, Цена: {$ad['price']}\n";
}

Пример 5: Загрузка изображений

<?php
$apiUrl = 'http://your-domain.com/apps/api/rest.php';
$sessionKey = '...'; // получен через connect()

// Загрузка файла
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'action' => 'uploads',
    'do' => 'upload_file',
    'session_key' => $sessionKey,
    'model_name' => 'data',
    'record_id' => 100,
    'file' => new CURLFile('/path/to/photo.jpg', 'image/jpeg', 'photo.jpg')
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($result['state'] == 'success') {
    echo "Файл загружен: {$result['file_url']}\n";
}

Расширенные возможности

Работа с вкладками (Tabs)

Модели могут содержать вкладки для группировки полей:

$data = $api->load_data('data', 'id', 100);
$tabs = $data['tabs'];

foreach ($tabs as $tabName => $tabFields) {
    echo "Вкладка: $tabName\n";
    foreach ($tabFields as $field) {
        echo "  - {$field['title']}: {$field['value']}\n";
    }
}

Работа с координатами (Geodata)

$adData = [
    'text' => 'Квартира в центре',
    'price' => 10000000,
    'geo' => [
        'lat' => 38.5598,
        'lng' => 68.7738
    ]
];

$result = $api->native_insert('data', $adData);

Мультиязычность

// Загрузка конфигурации с языками
$config = apiRequest($apiUrl, [
    'action' => 'model',
    'do' => 'load_config',
    'session_key' => $sessionKey
]);

$languages = $config['data']['languages']; // ['ru', 'en', 'tj']

Советы по использованию

  1. Храните session_key в сессии: После первого подключения сохраните session_key, чтобы не аутентифицироваться при каждом запросе.

  2. Проверяйте ответы: Всегда проверяйте state в ответе перед обработкой данных.

  3. Обрабатывайте ошибки: Используйте try-catch для обработки исключений сети.

  4. Кэшируйте структуру моделей: Загружайте load_grid_columns один раз и кэшируйте результат.

  5. Используйте пагинацию: При работе с большими списками используйте параметры page и per_page.

  6. Валидация на клиенте: Проверяйте данные перед отправкой на сервер.

Заключение

Sitebill API PHP SDK предоставляет мощный и гибкий инструмент для интеграции с системой Sitebill. Документация охватывает основные возможности, но система поддерживает множество дополнительных функций. Для получения полной информации о доступных методах изучите исходный код в директории /apps/api/classes/.

Полезные ссылки:

Версия документации: 1.0
Дата: Ноябрь 2025
Автор: Generated for Sitebill CMS