Документация 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/.

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

• GitHub репозиторий SDK: https://github.com/rumantic/sitebill_api_php_sdk
• Исходный код API: /apps/api/classes/
• Документация по моделям: /apps/api/classes/class.model.php

---

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