s3.php¶

Модуль управления S3-хранилищем: создание и удаление аккаунтов, управление бакетами и файлами, получение статистики использования, управление тарифными планами и биллингом.

Методы API¶

Метод	Действие	Описание
`create_account`	создание S3 аккаунта	Создает новый S3 аккаунт для клиента, привязывает тарифный план, создает бакет и оформляет заказ в биллинге.
`create_bucket`	создание бакета S3	Создает новый бакет в S3-хранилище для указанного пользователя. Требуется валидный s3uid текущего клиента.
`create_order`	создание заказа на S3-хранилище	Создает новый заказ на S3-хранилище для клиента. Валидирует тарифный план, проверяет лимиты бесплатных аккаунтов или кредиты, создает пользователя S3, бакет и сервис биллинга.
`delete_account`	удаление S3 аккаунта	Полностью удаляет S3 аккаунт пользователя. Требует указания идентификатора клиента (для администратора) или используется ID текущего пользователя, а также s3uid целевого аккаунта.
`delete_bucket`	удаление бакета S3	Удаляет указанный бакет S3. Проверяет права доступа и принадлежность бакета пользователю.
`delete_file`	удаление файла	Удаляет указанный файл из S3-бакета. Требует валидации токена и проверки прав доступа клиента.
`delete_payment_account`	отмена оплаты аккаунта	Инициирует отмену платного S3-аккаунта. Устанавливает дату отмены для сервиса, связанный с указанным s3uid.
`get_buckets`	получение списка бакетов	Возвращает список бакетов для указанного S3-аккаунта, включая информацию об использовании хранилища, квоте, метриках и ключах доступа. Использует асинхронный запрос через очередь задач.
`get_buckets_rmq`	получение списка бакетов и метрик через RMQ	Возвращает список бакетов пользователя S3, информацию об использовании хранилища, квоте, метриках трафика и ключах доступа. Использует очередь сообщений (RMQ) для получения актуальных данных.
`get_files`	получение списка файлов	Возвращает список файлов и папок в указанном S3-бакете с поддержкой пагинации и поиска.
`get_users`	получение списка пользователей S3	Возвращает список пользователей S3 с информацией о трафике, использовании хранилища и статусе сервиса. Поддерживает фильтрацию по ID клиента, ID плана, email, billing, s3uid, bucket_name, storage_type. Для администраторов доступны сортировка и пагинация.
`history`	получение истории изменений тарифного плана	Возвращает историю изменений или событий, связанных с указанным тарифным планом S3.
`list_plans`	получение списка планов S3	Возвращает список доступных тарифных планов S3. Для клиентов скрывает неактивные планы (если нет тега s3_test). Для администраторов при указании id возвращает детали конкретного плана.
`show_key`	получение ключа доступа	Возвращает расшифрованный ключ доступа (access_key или secret_key) для указанного S3-аккаунта.

s3/cancel_payment_account_deletion¶

Отменяет ранее инициированную процедуру удаления платного S3-аккаунта. Требует валидации токена и проверки прав доступа.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `cancel_payment_account_deletion`
token	✅	string	Токен авторизации пользователя
s3uid	✅	string	Уникальный идентификатор S3-пользователя (UID)
id	❌	int	ID клиента (используется администраторами для управления чужими аккаунтами)

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=cancel_payment_account_deletion" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "cancel_payment_account_deletion",
"termination_date": "2024-12-31 23:59:59"
}

Примеры ошибок

``` { "code": -1, "message": "s3/cancel_payment_account_deletion: S3 account not found for this customer" }

```

s3/create_account¶

Создает новый S3 аккаунт для клиента, привязывает тарифный план, создает бакет и оформляет заказ в биллинге.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Имя действия: `create_account`
token	✅	string	Токен авторизации пользователя
plan_id	✅	int	Идентификатор тарифного плана S3
bucket_name	✅	string	Имя создаваемого бакета (должно быть валидным)
location	❌	string	Код локации (по умолчанию NL). Должен поддерживаться выбранным планом.

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=create_account" \
--data "token=HOSTKEY_TOKEN" \
--data "plan_id=VALUE" \
--data "bucket_name=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "create_account",
"s3uid": "7VT1xrnQbWSIQhoOrAngpLUL5reuFcXY"
}

Примеры ошибок

``` { "code": -1, "message": "s3/create_account: missing auth token", "details": { "possible_errors": [ "s3/create_account: customer not found", "s3/create_account: no plan_id found", "s3/create_account: invalid location", "s3/create_account: you have maximum 3 free S3 accounts", "s3/create_account: S3 account was created, but have error: ..." ] } }

```

s3/create_bucket¶

Создает новый бакет в S3-хранилище для указанного пользователя. Требуется валидный s3uid текущего клиента.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `create_bucket`
token	✅	string	Токен авторизации пользователя
s3uid	✅	string	Уникальный идентификатор S3-пользователя (UID)
bucket_name	✅	string	Имя создаваемого бакета

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=create_bucket" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "bucket_name=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "create_bucket",
"message": {
"status": "success",
"bucket_name": "my-new-bucket",
"location": "NL"
}
}

Примеры ошибок

{
"code": -1,
"message": "s3/create_bucket: S3 account not found for this customer",
"details": {
"s3uid": "invalid_uid"
}
}

s3/create_order¶

Создает новый заказ на S3-хранилище для клиента. Валидирует тарифный план, проверяет лимиты бесплатных аккаунтов или кредиты, создает пользователя S3, бакет и сервис биллинга.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `create_order`
token	✅	string	Токен авторизации пользователя
plan_id	✅	int	Идентификатор тарифного плана S3
bucket_name	✅	string	Имя создаваемого бакета (должно быть валидным)
location	❌	string	Код локации (по умолчанию NL)

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=create_order" \
--data "token=HOSTKEY_TOKEN" \
--data "plan_id=VALUE" \
--data "bucket_name=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "create_order",
"s3uid": "7VT1xrnQbWSIQhoOrAngpLUL5reuFcXY"
}

Примеры ошибок

``` { "code": -1, "message": "s3/create_order: no plan_id found" }

```

s3/delete_account¶

Полностью удаляет S3 аккаунт пользователя. Требует указания идентификатора клиента (для администратора) или используется ID текущего пользователя, а также s3uid целевого аккаунта.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `delete_account`
token	✅	string	Токен авторизации
id	❌	int	ID клиента (обязательно для администратора, игнорируется для обычного пользователя)
s3uid	✅	string	Уникальный идентификатор S3 пользователя (s3uid)

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=delete_account" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "delete_account",
"message": "Account deleted successfully"
}

Примеры ошибок

``` { "code": -1, "message": "S3 account not found for this customer" }

```

s3/delete_bucket¶

Удаляет указанный бакет S3. Проверяет права доступа и принадлежность бакета пользователю.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `delete_bucket`
token	✅	string	Токен авторизации пользователя
s3uid	✅	string	Уникальный идентификатор S3-пользователя (UID)
bucket_name	✅	string	Имя бакета для удаления
id	❌	integer	ID клиента (используется администраторами для удаления бакетов других пользователей)

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=delete_bucket" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "bucket_name=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "delete_bucket",
"message": "Bucket deleted successfully"
}

Примеры ошибок

{
"code": -1,
"message": "s3/delete_bucket: bucket not found"
}

s3/delete_file¶

Удаляет указанный файл из S3-бакета. Требует валидации токена и проверки прав доступа клиента.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `delete_file`
token	✅	string	Токен авторизации пользователя
s3uid	✅	string	Уникальный идентификатор S3-пользователя (UID)
bucket_name	✅	string	Имя бакета, из которого удаляется файл
filename	✅	string	Имя файла (ключ объекта) для удаления

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=delete_file" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "bucket_name=VALUE" \
--data "filename=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "delete_file",
"message": "string"
}

Примеры ошибок

``` { "code": -1, "message": "s3/delete_file: Delete S3 file error: {error_message}. Response: {response_data}." }

```

s3/delete_payment_account¶

Инициирует отмену платного S3-аккаунта. Устанавливает дату отмены для сервиса, связанный с указанным s3uid.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `delete_payment_account`
token	✅	string	Токен авторизации пользователя
s3uid	✅	string	Уникальный идентификатор S3-пользователя
id	❌	int	ID клиента (для администраторов). Если не указан, используется ID из токена.

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=delete_payment_account" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "delete_payment_account",
"cancellation_date": "2024-12-31 23:59:59"
}

Примеры ошибок

{
"code": -1,
"message": "S3 account not found for this customer"
}

s3/get_buckets¶

Возвращает список бакетов для указанного S3-аккаунта, включая информацию об использовании хранилища, квоте, метриках и ключах доступа. Использует асинхронный запрос через очередь задач.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `get_buckets`
token	✅	string	Токен авторизации пользователя
s3uid	✅	string	Уникальный идентификатор S3-пользователя
id	❌	int	ID клиента (для администраторов)

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=get_buckets" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "get_buckets",
"message": [
{
"name": "my-bucket-01",
"creation_date": "2023-10-15T10:30:00Z",
"usage": 1073741824
},
{
"name": "my-bucket-02",
"creation_date": "2023-11-20T14:45:00Z",
"usage": 536870912
}
],
"usage_storage": 1610612736,
"quota": 5000,
"metering": {
"total_traffic_period_gb": 12.5,
"total_storage_peak_gb": 1.5
},
"access_key": "AKIAIOSFODNN7EXAMPLE",
"secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"endpoint": "https://s3.nl.hostkey.com"
}

Примеры ошибок

``` { "code": -1, "message": "S3 account not found for this customer" }

```

s3/get_buckets_rmq¶

Возвращает список бакетов пользователя S3, информацию об использовании хранилища, квоте, метриках трафика и ключах доступа. Использует очередь сообщений (RMQ) для получения актуальных данных.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `get_buckets_rmq`
token	✅	string	Токен авторизации пользователя
s3uid	✅	string	Уникальный идентификатор пользователя S3 (S3 UID)
id	❌	int	ID клиента (используется администраторами для запроса данных другого пользователя)

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=get_buckets_rmq" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "get_buckets_rmq",
"message": [
{
"name": "my-bucket-01",
"usage": 1024000,
"created": "2023-10-15T10:30:00Z"
},
{
"name": "backup-data",
"usage": 5120000,
"created": "2023-11-20T14:45:00Z"
}
],
"usage_storage": 6144000,
"quota": 5000,
"metering": {
"total_traffic_period_gb": 12.5,
"total_storage_peak_gb": 5.96
},
"access_key": "AKIAIOSFODNN7EXAMPLE",
"secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"endpoint": "https://s3.nl.hostkey.com"
}

Примеры ошибок

``` { "code": -1, "message": "s3/get_buckets_rmq: S3 account not found for this customer" }

```

s3/get_files¶

Возвращает список файлов и папок в указанном S3-бакете с поддержкой пагинации и поиска.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `get_files`
token	✅	string	Токен авторизации пользователя
s3uid	✅	string	Уникальный идентификатор S3-пользователя
bucket_name	✅	string	Имя бакета, содержимое которого нужно получить
continuation_token	❌	string	Токен для продолжения пагинации (если есть)
max_keys	❌	int	Максимальное количество ключей для возврата (по умолчанию 50, макс 100)
search	❌	string	Строка поиска по имени файла

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=get_files" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "bucket_name=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "get_files",
"files": {
"files": [
{
"key": "documents/report_2023.pdf",
"original_key": "documents/report_2023.pdf",
"size": 2048576,
"last_modified": "2023-10-25T14:30:00Z",
"etag": "\"d41d8cd98f00b204e9800998ecf8427e\""
},
{
"key": "images/logo.png",
"original_key": "images/logo.png",
"size": 15432,
"last_modified": "2023-11-01T09:15:00Z",
"etag": "\"5d41402abc4b2a76b9719d911017c592\""
}
],
"folders": [
"documents/",
"images/"
],
"next_token": "eyJDb250aW51YXRpb25Ub2tlbiI6ImV4YW1wbGUifQ=="
},
"folders": [
"documents/",
"images/"
],
"next_token": "eyJDb250aW51YXRpb25Ub2tlbiI6ImV4YW1wbGUifQ=="
}

Примеры ошибок

``` { "code": -1, "message": "s3/get_files: S3 account not found for this customer" }

```

s3/get_users¶

Возвращает список пользователей S3 с информацией о трафике, использовании хранилища и статусе сервиса. Поддерживает фильтрацию по ID клиента, ID плана, email, billing, s3uid, bucket_name, storage_type. Для администраторов доступны сортировка и пагинация.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `get_users`
token	✅	string	Токен авторизации
id	❌	int	ID клиента (для администратора) или ID пользователя S3
plan_id	❌	int	ID тарифного плана S3
s3uid	❌	string	Уникальный идентификатор пользователя S3
email	❌	string	Email пользователя для фильтрации
billing	❌	string	Система биллинга для фильтрации
bucket_name	❌	string	Имя бакета для поиска пользователя
storage_type	❌	string	Тип хранилища (Standard, Cold и т.д.)
location	❌	string	Локация (код региона, например NL)
period_from	❌	string	Начальная дата периода для статистики трафика (Y-m-d)
period_to	❌	string	Конечная дата периода для статистики трафика (Y-m-d)
order	❌	string	Поле для сортировки (total_traffic_period_gb, total_storage_peak_gb)
order_by	❌	string	Направление сортировки (ASC, DESC)
limit	❌	int	Количество записей для возврата
offset	❌	int	Смещение для пагинации

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=get_users" \
--data "token=HOSTKEY_TOKEN"

Пример успешного ответа

{
"result": "OK",
"action": "get_users",
"s3_users": [
{
"id": 123,
"s3uid": "7VT1xrnQbWSIQhoOrAngpLUL5reuFcXY",
"email": "user@example.com",
"billing": "whmcs",
"plan_id": 5,
"location": "NL",
"storage_type": "Standard",
"quota": 5000,
"traffic": 12.5,
"storage_usage": 45.2,
"service": {
"next_commit_date": "2024-02-01",
"cancellation_date": null,
"termination_date": null,
"termination_unix_date": null,
"cancellation_unix_date": null,
"status": "active"
}
}
]
}

Примеры ошибок

``` { "code": -1, "message": "s3/get_users: customer not found" }

```

s3/history¶

Возвращает историю изменений или событий, связанных с указанным тарифным планом S3.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `history`
token	✅	string	Токен авторизации пользователя
id	❌	int	Идентификатор тарифного плана S3

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=history" \
--data "token=HOSTKEY_TOKEN"

Пример успешного ответа

{
"result": "OK",
"action": "history",
"data": []
}

Примеры ошибок

``` { "code": -1, "message": "s3/history: invalid token, logout" }

```

s3/list_plans¶

Возвращает список доступных тарифных планов S3. Для клиентов скрывает неактивные планы (если нет тега s3_test). Для администраторов при указании id возвращает детали конкретного плана.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `list_plans`
token	✅	string	Токен авторизации пользователя
id	❌	int	ID плана. Если указан администратором, возвращает детали конкретного плана вместо списка.

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=list_plans" \
--data "token=HOSTKEY_TOKEN"

Пример успешного ответа

{
"result": "OK",
"action": "list_plans",
"plans": [
{
"id": 1,
"name": "Standard S3",
"active": 1,
"quota": 5000,
"storage_type": "Standard",
"locations": "NL,DE",
"monthly_rub": 4500,
"monthly_eur": 49.99,
"monthly_usd": 54.99,
"traffic_overage_price_rub": 10,
"traffic_overage_price_eur": 0.11,
"traffic_overage_price_usd": 0.12,
"storage_overage_price_rub": 5,
"storage_overage_price_eur": 0.05,
"storage_overage_price_usd": 0.06,
"bandwidth_limit": 1000,
"price": {
"rub": 4500,
"eur": 49.99,
"usd": 54.99
},
"tags": []
}
]
}

Примеры ошибок

``` { "code": -1, "message": "s3/list_plans: missing auth token" }

```

s3/show_key¶

Возвращает расшифрованный ключ доступа (access_key или secret_key) для указанного S3-аккаунта.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `show_key`
token	✅	string	Токен авторизации пользователя
s3uid	✅	string	Уникальный идентификатор S3-пользователя
s3_key	✅	string	Тип ключа для получения: 'access_key' или 'secret_key'

Пример запроса

curl -s "https://invapi.hostkey.ru/s3.php" -X POST \
--data "action=show_key" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "s3_key=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "show_key",
"key": "4KCTQIAZ1GLPB8TFIMTO"
}

Примеры ошибок

{
"code": -1,
"message": "s3/show_key: customer not found"
}