Variable API

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

Авторизация

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

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

Примеры доменных 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`	Объекты, маршруты, партии и документы поставки
`messengers.read`	Безопасные внешние идентификаторы Wazzup и связанные чаты
`company.read` или `settings.read`	Компания и региональные настройки
`users.read`	Пользователи

API key без variables.read не может получить ни каталог переменных, ни значения переменных. Legacy scope procurements.read принимается как alias для старых интеграций.

Переменная company.nomenclatureSavePolicy доступна в домене company со scope settings.read. Значение соответствует режиму сохранения номенклатуры: SUPPLIER_QUOTES_ALL, ACCEPTED_QUOTE_LINES_ONLY или ALL_PR_IMPORTED_AND_MANUAL_ITEMS.

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

http

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

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

http

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

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

json

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

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

http

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.stock.available",
    "custom.vendorCode"
  ]
}

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

json

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

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

Формат paths

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

procurement.id
procurement.stage.externalId
procurement.stage.name
procurement.customerRequestFileName
procurement.selectedSupplier.name
company.nomenclatureSavePolicy
procurement.constructionProject.actualStartDate
procurement.customerContact.fullName
procurement.responsible.code
catalogItem.type
catalogItem.sku
catalogItem.currentCostPrice
priceList.items[].price
document.totalAmount
document.pricingMode
document.commissionAmount
document.grossMarginPercent
counterparty.checkingAccount
counterparty.paymentRequisites[].bankName
logisticsObject.name
deliveryRoute.vehicleNumber
deliveryBatch.number
generatedDocument.carrierName
diadoc.status
diadoc.messageId
saby.status
saby.documentId
astral.status
astral.docflowId
user.code
custom.vendorCode

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

Для контрагентов основной платёжный реквизит доступен через counterparty.bankName, counterparty.bik, counterparty.checkingAccount и counterparty.correspondentAccount. Все сохранённые счета можно читать массивами counterparty.paymentRequisites[].label, counterparty.paymentRequisites[].bankName, counterparty.paymentRequisites[].bik, counterparty.paymentRequisites[].checkingAccount, counterparty.paymentRequisites[].correspondentAccount и counterparty.paymentRequisites[].isPrimary. Для API key нужны variables.read и counterparties.read.

Для заявок, связанных с amoCRM или другой CRM, доступны безопасные поля обмена: procurement.customerRequestFileName, procurement.plannedTotal, procurement.actualTotal, procurement.dueDate, procurement.selectedSupplier.name, procurement.selectedSupplier.supplierId, procurement.selectedSupplier.counterpartyId и procurement.selectedSupplier.inn.

Стройка+

Если для портала включено отраслевое расширение Стройка+, в заявках и партиях доставки доступны безопасные строительные поля:

procurement.constructionProject.name
procurement.constructionProject.actualStartDate
procurement.constructionProject.actualEndDate
procurement.constructionObject.name
procurement.constructionObject.address
procurement.constructionStage.name
procurement.items[].sourceSectionName
procurement.items[].workType
procurement.items[].requiredAt
procurement.items[].needGroupKey
request.constructionProject.actualStartDate
request.constructionProject.actualEndDate
deliveryBatch.constructionProject.actualStartDate
deliveryBatch.constructionProject.actualEndDate

Обеспечение строк заявки

Для заявок доступны переменные построчного обеспечения поставщиками:

procurement.items[].supplyCoverage.status — not_covered, partially_covered или covered;
procurement.items[].supplyCoverage.percent — процент закрытого количества по строке;
procurement.items[].supplyCoverage.acceptedQuantity — количество, принятое к обеспечению у поставщиков;
procurement.items[].supplyCoverage.remainingQuantity — остаток количества без выбранного поставщика;
procurement.items[].supplyCoverage.suppliers[].name — выбранные поставщики по строке.

Эти переменные показывают принятое решение снабжения: у каких поставщиков планируется закупка и в каком объёме. Они не заменяют receivedQuantity и не означают фактический приход на склад.

Портал и согласия

Для портала доступны безопасные сведения о компании и последней зафиксированной записи согласий:

company.name
company.slug
company.companyInn
company.legalConsent.hasRecord
company.legalConsent.acceptedOffer
company.legalConsent.acceptedPersonalData
company.legalConsent.acceptedMarketing
company.legalConsent.acceptedAt
company.legalConsent.source
company.legalConsent.documentVersions
company.legalConsent.documentUrls
company.paidWidgets[].slug
company.paidWidgets[].name
company.paidWidgets[].licenseStatus
company.paidWidgets[].effectiveLicenseStatus
company.paidWidgets[].activeFrom
company.paidWidgets[].activeUntil
company.paidWidgets[].priceMonthlyRub
company.paidWidgets[].estimatedMonthlyAmountRub

Для получения значений через API key нужны variables.read и company.read или settings.read. IP, user-agent, хэши документов и служебные доказательные данные через Variable API не раскрываются.

В массив company.paidWidgets[] попадают только видимые платные виджеты со статусом notPaid, trial или active. Отключенные disabled-виджеты и служебные metadata, payload заявок, токены и audit-данные через Variable API не раскрываются.

Себестоимость и маржа

Для номенклатуры доступны поля текущей себестоимости:

catalogItem.type — product для товара или service для услуги
catalogItem.currentCostPrice
catalogItem.currentCostCurrency
catalogItem.currentCostSource
catalogItem.currentCostUpdatedAt
catalogItem.suppliers[].name
catalogItem.suppliers[].lastPrice
catalogItem.suppliers[].sources

Для поставщиков доступны безопасные поля ассортимента:

supplier.assortment.categories[].name
supplier.assortment.products[].name

Для исходящих документов после выпуска доступны снимки себестоимости и маржинальности:

document.costTotalAmount
document.grossProfitAmount
document.grossMarginPercent
document.costCoveragePercent
document.costCapturedAt
items.rows[].unitCost
items.rows[].lineCostAmount
items.rows[].grossProfitAmount
items.rows[].grossMarginPercent
items.rows[].costIsEstimated

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

Контур.Диадок

Для исходящих счетов, договоров и документов поставки доступны безопасные переменные ЭДО:

diadoc.status;
diadoc.signatureStatus;
diadoc.statusText;
diadoc.senderBoxId;
diadoc.recipientBoxId;
diadoc.messageId;
diadoc.attachmentEntityId;
diadoc.documentId;
diadoc.sentAt;
diadoc.syncedAt;
diadoc.signedAt.

Через Variable API не раскрываются OAuth-токены, настройки подключения, raw-ответы Диадок и файловые хэши.

СБИС / SABY ЭДО

Для исходящих счетов, договоров и документов поставки доступны безопасные переменные ЭДО:

saby.status;
saby.signatureStatus;
saby.statusText;
saby.statusDetails;
saby.documentId;
saby.revisionId;
saby.attachmentId;
saby.counterpartyParticipantId;
saby.counterpartyName;
saby.counterpartyInn;
saby.counterpartyKpp;
saby.lastEventId;
saby.lastEventName;
saby.sentAt;
saby.syncedAt;
saby.signedAt.

Через Variable API не раскрываются пароль, настройки подключения, raw-ответы SABY и файловые хэши.

Калуга Астрал ЭДО

Для исходящих счетов, договоров и документов поставки доступны безопасные переменные ЭДО:

astral.status;
astral.signatureStatus;
astral.statusText;
astral.statusDetails;
astral.direction;
astral.senderAbonentId;
astral.recipientId;
astral.draftId;
astral.docflowId;
astral.documentId;
astral.signingRequestId;
astral.counterpartyName;
astral.counterpartyInn;
astral.counterpartyKpp;
astral.lastEventId;
astral.lastEventName;
astral.sentAt;
astral.syncedAt;
astral.signedAt.

Через Variable API не раскрываются API-токен, настройки подключения, raw-ответы Калуга Астрал и файловые хэши.

Коммерческие предложения

Для сущности commercialProposal доступны безопасные поля расширенного расчёта КП:

document.pricingMode
document.proposalModel
document.commissionMode
document.commissionPercent
document.commissionFixedAmount
document.materialsAmount
document.servicesAmount
document.expenseTotalAmount
document.allocatedExpenseAmount
document.commissionAmount
items.rows[].lineType
items.rows[].supplierName
items.rows[].groupKey
items.rows[].groupLabel
items.rows[].unitCost
items.rows[].markupPercent
items.rows[].markupAmount
items.rows[].allocatedExpenseAmount
items.rows[].commissionPercent
items.rows[].commissionFixedAmount
items.rows[].commissionAmount
items.rows[].lineCostAmount

Для получения значений через API key нужны variables.read, documents.read и customer_documents.read. Raw metadata, токены, webhook payload, зашифрованные настройки и служебные JSON-поля через Variable API не раскрываются.

Логистика и документы поставки

Для документов поставки доступны безопасные поля логистики:

logisticsObject.code
logisticsObject.name
logisticsObject.address
logisticsObject.latitude
logisticsObject.longitude
logisticsObject.contactName
deliveryRoute.name
deliveryRoute.isActive
deliveryRoute.originAddress
deliveryRoute.originLatitude
deliveryRoute.originLongitude
deliveryRoute.destinationAddress
deliveryRoute.destinationLatitude
deliveryRoute.destinationLongitude
deliveryRoute.stops[].sequence
deliveryRoute.stops[].kind
deliveryRoute.stops[].label
deliveryRoute.stops[].address
deliveryRoute.stops[].latitude
deliveryRoute.stops[].longitude
deliveryRoute.stops[].object.name
deliveryRoute.carrierName
deliveryRoute.driverName
deliveryRoute.vehicleNumber
deliveryBatch.number
deliveryBatch.status
deliveryBatch.isActive
deliveryBatch.items[].name
deliveryBatch.items[].quantity
logisticsVehicle.latestLocation.recordedAt
logisticsVehicle.latestLocation.status
logisticsVehicle.latestLocation.latitude
logisticsVehicle.latestLocation.longitude
logisticsVehicle.latestLocation.address
logisticsVehicle.locations[].recordedAt
logisticsVehicle.locations[].status
generatedDocument.kind
generatedDocument.number
generatedDocument.stage
generatedDocument.scope
generatedDocument.carrierName
generatedDocument.driverName
generatedDocument.vehicleNumber
generatedDocument.attorneyName
generatedDocument.recipientName
generatedDocument.deliveryAddress

Для получения значений через API key нужны variables.read и logistics.read. Ссылки хранения, подписи скачивания, служебные JSON-поля и технические audit payload через Variable API не раскрываются.

Wazzup и мессенджеры

Для PR, RFQ поставщику, поставщика и контрагента доступны безопасные поля внешней переписки:

wazzup.chat.channelId
wazzup.chat.chatType
wazzup.chat.chatId
wazzup.links[].externalKind
wazzup.links[].externalId
wazzup.lastMessage.messageId
wazzup.lastMessage.requestId
wazzup.lastMessage.status
wazzup.lastMessage.createdAt

Для получения значений через API key нужны variables.read и messengers.read. API-ключи Wazzup, bearer-токены webhook, iframe URL и зашифрованные настройки через Variable API не раскрываются.

YouGile

Для закупки доступны безопасные поля связи с задачником YouGile:

yougile.primary.targetType
yougile.primary.externalId
yougile.links[].targetType
yougile.links[].externalId
yougile.task.taskId
yougile.task.idTaskCommon
yougile.task.idTaskProject
yougile.task.title
yougile.task.columnId
yougile.task.completed
yougile.task.archived
yougile.task.lastSyncedAt
yougile.task.lastEventAt

Для получения значений через API key нужны variables.read и доступ к закупкам. API key YouGile, webhook token, зашифрованная конфигурация и raw payload задач через Variable API не раскрываются.

Дополнительные поля

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

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

Тип пользовательского поля после создания не меняется. Для select опции хранятся как { "items": ["..."] }, а записываемое значение должно совпадать с одним из вариантов, если список задан.

Для закупок дополнительно доступны безопасные переменные текущего этапа воронки:

procurement.stage.id
procurement.stage.externalId
procurement.stage.name
procurement.stage.color

После создания поля с ключом vendorCode для catalogItem или amocrmProcurementNumber для procurement в каталоге переменных этого портала появляется custom.vendorCode или custom.amocrmProcurementNumber. Пользовательские переменные ограничены порталом: другой портал не увидит и не сможет получить это поле.

При импорте PR колонки можно сопоставить с дополнительными полями номенклатуры. Такие значения сохраняются на связанном catalogItem и затем доступны как custom.<key> для товара и как items.rows[].custom.<key> в строках клиентских документов.

Variable API ​

Авторизация ​

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

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

Формат paths ​

Стройка+ ​

Обеспечение строк заявки ​

Портал и согласия ​

Себестоимость и маржа ​

Контур.Диадок ​

СБИС / SABY ЭДО ​

Калуга Астрал ЭДО ​

Коммерческие предложения ​

Логистика и документы поставки ​

Wazzup и мессенджеры ​

YouGile ​

Дополнительные поля ​

Variable API

Авторизация

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

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

Формат paths

Стройка+

Обеспечение строк заявки

Портал и согласия

Себестоимость и маржа

Контур.Диадок

СБИС / SABY ЭДО

Калуга Астрал ЭДО

Коммерческие предложения

Логистика и документы поставки

Wazzup и мессенджеры

YouGile

Дополнительные поля