Variable API

Variable API даёт внешним системам единый read-only способ узнать, какие поля доступны в SNABZHENETS+, и получить значения по конкретной сущности. Те же paths используются в документах, API-интеграциях и будущих донастройках.

Авторизация

Variable API поддерживает два способа доступа:

• JWT текущего пользователя: права берутся из роли пользователя в портале.
• API key: ключ передаётся в заголовке X-API-Key и должен иметь scope variables.read плюс доменный read-scope.

Примеры доменных scopes:

Scope	Доступ
catalog.read	Номенклатура и связанные каталоговые переменные
price_lists.read	Прайсы
warehouses.read	Склады и остатки
counterparties.read	Контрагенты
suppliers.read	Поставщики
procurements.read	Заявки и закупки
documents.read	Документы
customer_documents.read	КП, исходящие счета, договоры
supplier_documents.read	RFQ, ответы поставщиков, входящие счета
company.read или settings.read	Компания и региональные настройки
users.read	Пользователи

API key без variables.read не может получить ни каталог переменных, ни resolved values.

Каталог переменных

GET /api/v1/variables?domain=catalog&entityType=catalogItem&search=sku&includeCustom=true
Authorization: Bearer <accessToken>

Или через ключ:

GET /api/v1/variables?entityType=priceList
X-API-Key: spk_...

Ответ содержит плоский список items, сгруппированный список groups для UI и meta.

{
  "items": [
    {
      "path": "catalogItem.sku",
      "label": "SKU",
      "domain": "catalog",
      "entityTypes": ["catalogItem"],
      "valueType": "string",
      "scopes": ["catalog.read"]
    }
  ],
  "groups": [],
  "meta": {
    "total": 1,
    "includeCustom": true,
    "authType": "apiKey"
  }
}

Resolve values

POST /api/v1/variables/resolve
X-API-Key: spk_...
Content-Type: application/json

{
  "entityType": "catalogItem",
  "entityId": "22222222-2222-4222-8222-222222222222",
  "paths": [
    "catalogItem.id",
    "catalogItem.sku",
    "catalogItem.stock.available",
    "custom.vendorCode"
  ]
}

Пример ответа:

{
  "entityType": "catalogItem",
  "entityId": "22222222-2222-4222-8222-222222222222",
  "values": {
    "catalogItem.id": "22222222-2222-4222-8222-222222222222",
    "catalogItem.sku": "SKU-001",
    "catalogItem.stock.available": "8",
    "custom.vendorCode": "A-104"
  },
  "unresolved": [],
  "resolvedAt": "2026-05-11T09:00:00.000Z"
}

Если path недоступен по scope, отсутствует в каталоге или не имеет значения у сущности, он попадает в unresolved; генерация документов и интеграции не должны падать из-за пустого значения.

Формат paths

Path строится как namespace.path:

• procurement.id
• catalogItem.sku
• priceList.items[].price
• document.totalAmount
• custom.vendorCode

[] означает массив строк или связанных записей. В v1 Variable API только читает данные; запись выполняется через обычные доменные endpoints.

Custom fields

Индивидуальные поля портала описываются в настройках:

Метод	Путь	Назначение
GET	/api/v1/settings/custom-fields?entityType=catalogItem	Список определений
POST	/api/v1/settings/custom-fields	Создать определение
PATCH	/api/v1/settings/custom-fields/:id	Обновить label/type/options/status
DELETE	/api/v1/settings/custom-fields/:id	Архивировать определение
GET	/api/v1/settings/custom-fields/values?entityType=catalogItem&entityId=...	Значения сущности
PUT	/api/v1/settings/custom-fields/:id/values	Записать значение сущности

После создания определения key=vendorCode для catalogItem в каталоге переменных этого портала появляется custom.vendorCode. Custom variables tenant-scoped: другой портал не увидит и не сможет resolve-ить это поле.