Баланс и тарифы

Все методы ниже вызываются относительно BASE_GATE с заголовком Authorization: Bearer ..., см. Аутентификация и ключи.

Баланс

Запрос: GET /v1/billing/balance?workspace=<guid>

Параметр запроса workspace обязателен: это GUID рабочей области (workspace), для которой запрашивается баланс.

Ответ 200 — объект JSON со свойствами (имена совпадают с ответом внутренней системы учёта балансов):

Поле	Тип	Смысл
`currency`	строка	Код валюты счёта
`availableMinor`	целое	Доступный баланс в минимальных денежных единицах (копейки для RUB и т.п.)
`updatedAt`	строка времени ISO 8601	Время последнего обновления записи учёта

Ответ 404 при отсутствии счёта — JSON с полем описания ошибки по смыслу «акаунт для workspace не найден».

Ответ 500 — JSON с сообщением об внутренней ошибке сервера (детали см. телом ответа в отладке).

Малые единицы (*Minor)

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

Тарифы (цены)

Запрос: GET /v1/billing/prices

Параметр plan в контракте зарезервирован; если не использован бекендом, он может игнорироваться.

Ответ 200 — объект JSON с массивом items (каждый элемент описывает одну активную связку «модель + тариф»). Имена полей приходят в camelCase. Типичные поля элементов включая тарифную математику:

Поле	Комментарий
`modelId`	GUID модели в реестре
`provider`, `name`, `displayName`	Строковые свойства описания модели и провайдера
`registryEnabled`, `isActive`	Признак доступности записи модели и тарифа
`inPricePerUnitMultiplierMinor`, `inUnitMultiplier`, `inComissThPercent`, `inMinCommissionPerBlockMinor`	Входящая часть тарификации (в «малых» суммах и множителях, см. код сервера)
`outPricePerUnitMultiplierMinor`, `outUnitMultiplier`, `outComissThPercent`, `outMinCommissionPerBlockMinor`	Исходящая сторона
`updatedAt`	Время изменения строки тарифа

Точную семантику коэффициентов см. во внутренней документации операций; для клиента API этого достаточно, чтобы отображать список и выбирать расчёт расходов в своём приложении или уточнять детали у поддержки продукта.

Ответ 404 — тарифная конфигурация не найдена (план).

Ответ 500 — внутренняя ошибка.

Примеры

Подставьте TOKEN, BASE_GATE и реальный WORKSPACE_GUID.

Pythoncurl

import os
import requests

BASE_GATE = os.environ["BASE_GATE"].rstrip("/")
TOKEN = os.environ["TOKEN"]
WORKSPACE_GUID = os.environ["WORKSPACE_GUID"]

headers = {"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}

bal = requests.get(
    f"{BASE_GATE}/v1/billing/balance",
    params={"workspace": WORKSPACE_GUID},
    headers=headers,
    timeout=30,
)
bal.raise_for_status()
print("Баланс:", bal.json())

prices = requests.get(
    f"{BASE_GATE}/v1/billing/prices",
    headers=headers,
    timeout=60,
)
prices.raise_for_status()
print("Тарифы, элементов:", len(prices.json().get("items", [])))

export BASE_GATE="https://api.theta-cloud.ru"
export TOKEN='...'
export WORKSPACE_GUID='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

curl -sS -G "${BASE_GATE}/v1/billing/balance" \
  --data-urlencode "workspace=${WORKSPACE_GUID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json"

curl -sS "${BASE_GATE}/v1/billing/prices" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json"