Variable API

Variable API даёт внешней системе единый режим чтения: можно получить каталог разрешённых бизнес-полей и затем запросить значения этих полей у конкретной сущности.

Граница доступа

Variable API принимает только заранее выданный API key. Передавайте его в заголовке:

X-API-Key: spk_...

Ключ должен иметь variables.read и отдельный scope чтения нужного домена. Например, для полей номенклатуры требуются variables.read и catalog.read.

API возвращает только те paths, которые одновременно:

• входят в опубликованный каталог переменных;
• разрешены scopes выданного ключа;
• относятся к порталу этого ключа;
• не содержат секретов или служебной конфигурации.

Ключ Variable API не даёт доступ к сотрудникам, ролям, настройкам платформы или управлению установленными сервисами.

Доменные scopes

Scope	Данные
catalog.read	Номенклатура и характеристики товаров
price_lists.read	Прайс-листы и строки прайсов
warehouses.read	Склады и доступные остатки
counterparties.read	Контрагенты и разрешённые реквизиты
suppliers.read	Поставщики
purchase_requisitions.read	Заявки и их позиции
documents.read	Общие поля документов
customer_documents.read	КП, исходящие счета и договоры
supplier_documents.read	RFQ, ответы поставщиков и входящие счета
logistics.read	Объекты, маршруты, партии и документы поставки

Запрашивайте у владельца портала только scopes, необходимые конкретному сценарию.

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

GET /api/v1/variables?domain=catalog&entityType=catalogItem&search=sku&includeCustom=true
X-API-Key: spk_...

Фильтры:

Параметр	Назначение
domain	Ограничить каталог бизнес-доменом
entityType	Показать paths для конкретного типа сущности
search	Найти path или название поля
includeCustom	Включить разрешённые дополнительные поля портала

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

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

Каталог из ответа является источником истины для выданного ключа. Не подставляйте paths, которых в нём нет.

Получение значений

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

{
  "entityType": "catalogItem",
  "entityId": "catalog-item-001",
  "paths": [
    "catalogItem.id",
    "catalogItem.type",
    "catalogItem.sku",
    "catalogItem.gtin",
    "catalogItem.stock.available",
    "custom.vendorCode"
  ]
}

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

{
  "entityType": "catalogItem",
  "entityId": "catalog-item-001",
  "values": {
    "catalogItem.id": "catalog-item-001",
    "catalogItem.type": "product",
    "catalogItem.sku": "SKU-001",
    "catalogItem.gtin": "04600123456789",
    "catalogItem.stock.available": "8",
    "custom.vendorCode": "A-104"
  },
  "unresolved": [],
  "resolvedAt": "2026-05-11T09:00:00.000Z"
}

Path попадает в unresolved, если он отсутствует в доступном каталоге, запрещён scopes ключа, не относится к указанной сущности или не имеет значения. Клиент должен обрабатывать unresolved как ожидаемый результат, а не как повод повторять запрос без ограничений.

Формат paths

Path строится как namespace.path. Вложенные объекты используют точку, массивы обозначаются [].

Примеры безопасных бизнес-полей:

• procurement.id
• procurement.number
• procurement.status
• procurement.stage.name
• procurement.items[].name
• procurement.items[].quantity
• catalogItem.id
• catalogItem.type
• catalogItem.sku
• catalogItem.gtin
• catalogItem.stock.available
• priceList.items[].price
• counterparty.name
• counterparty.inn
• supplier.directory.legalSourceUrl
• supplier.directory.checkedAt
• supplier.directory.assortmentEvidence[].sourceUrl
• supplier.directory.assortmentEvidence[].confidence
• document.number
• document.totalAmount
• deliveryTrip.status
• deliveryTrip.plannedStartAt

Фактический перечень для конкретного портала и ключа всегда получайте через GET /api/v1/variables.

Для supplier-профиля каталог также может вернуть безопасное происхождение записи из каталога поставщиков: supplier.directory.legalSourceUrl, supplier.directory.contactSourceUrl, supplier.directory.assortmentSourceUrl, supplier.directory.checkedAt, supplier.directory.rfqReady и массивы supplier.directory.assortmentEvidence[].sourceUrl, supplier.directory.assortmentEvidence[].observedAt, supplier.directory.assortmentEvidence[].confidence. Эти поля передают только URL источника, дату и степень совпадения; контакты, личные каналы, ID job импорта и служебные снимки получателей RFQ в Variable API не публикуются.

Типы значений

• даты и время передаются в ISO 8601;
• денежные и количественные значения могут передаваться строкой, чтобы не терять точность;
• отсутствующее значение может быть null;
• массивы сохраняют порядок, заданный бизнес-сущностью;
• дополнительные поля имеют path custom.<key> и доступны только если присутствуют в каталоге выданного ключа.

Variable API не возвращает пароли, токены, API keys, секреты подписи, зашифрованную конфигурацию, служебные payload или постоянные ссылки на файлы.

Связанные страницы

• Обзор API
• Integration API
• Коды ошибок