Skip to main content

Ключи

В данный момент документация только разрабатывается. И на этой странице представлено для примера часть ключей из спецификации Product offer. 

Эти ключи не являются окончательными это не стабильная версия, пользоваться ими на текущий момент не рекомендуется!

 

 

 Спецификация ключей и их значений

// Валидным будет файл с минимальным количеством логически обязательных ключей и без указания метаданных.

 

//Идея - глобальная таксономия для отнесения товаров по категориям

Универсальные ключи

id  – идентификатор. Уникальное значение идентифицирующее сущность передающей системой в рамках обмена.

name – наименование сущности.

name – .

name – .

adress – .

description – описание.

html_description – описание с разметкой в формате html.

summary_description – краткое описание, например: описание для показа в каталоге товаров. 

description_url - адрес по которому находится дополнительная информация о продукте (url).

img_url – адрес для скачивания изображения продукта (url).

video_url – адрес для скачивания видео по продукту (url).

file_url  – адрес для скачивания дополнительных документов (url).

Зафиксировать иной способ передачи файлов и сопоставления с продуктом

Метаданные файла

standart_name –  наименование стандарта: jsoncommerce.

standart_version – версия стандарта. На текущий момент версия: 0.1.

created – создано. Дата и время подготовки файла по ISO 8601. Например: '2021–03–10T11:30:00+02:00'  

completeness – полнота данных. Значения:

  • full data – полные данные; 

  • data changes – только изменения относительно предыдущей передачи.

exchange_version – версия изменений. /!\ Только если completeness: 'data changes'. Значение: целое число, шаг версии единица.

type_data – тип передаваемых данных. Значения:

  • product offer – предложение продукта;

  • order – .

supplier – поставщик. Информация о том, кто делает предложение/ а с заказом???

description – описание. Произвольное текстовое описание.

condition для кого это предложение сроки годности предложения?

 

Внутренние справочники

Таксономия

Таксономия – инструмент классификации и систематизации иерархически соотносящихся сущностей. Например, яблоки можно классифицировать по вкусу и относить их к сладким или кислым, а можно по цвету и относить их к красным, зеленым или желтым. Пример иерархичной таксономии: категория Бытовая техника имеет подкатегории Стиральные машины, Микроволновые печи.

Как правило, таксономия передается в файле после метаданных, а в самом товаре указываем идентификатор категории. Причем, если используется несколько таксономий, то все-равно их идентификаторы не должны совпасть (это нужно для экономии объема передаваемых данных). Если категоризация несущественна и единственна, то можно передавать сразу названия категорий в товаре.

catalog – корневой таксон. Можно сразу передавать несколько каталогов в массиве.

category – любой нижележащий таксон. 

weight_sequence –  вес в последовательности. Используется для явного указания порядка вывода категорий

Таксон имеет id, name, также может иметь: description, html_description, summary_description, description_url, img_url.

category_id – указание в продукте на id ранее объявленной категории. 

 

Характеристики

characteristic – характеристика – какой-либо параметр объекта присущий всей группе объекта, отражающий одно из его свойств. Например: Цвет, размер, скорость.

Свойство – конкретное значение характеристики. Например, объект: автомобиль, может иметь характеристики: цвет и объём двигателя, а, соответственно, свойства: красный, 2.4 л.

id – идентификатор характеристики.

name – наименование характеристики.

type – типы значений характеристик:

  • nymeric – цифровое значение (+единица измерения). Например: 2kWt; 200m.

  • list – Значение из перечня фиксированных значений (+единицы измерения) . Например: сладкий, соленый; керамика, чугун. Кроме того, такая характеристика может иметь несколько значений.

  • boolean – логическое значение (Да/Нет). Например: Режим отпаривания: есть.

  • color – цвет из перечня + какое-либо значение цвета. Например: Бордовый #C60009 или Бордовый RGB (198, 0 ,9).

  • text – текст. Описательное произвольное значение. Не позволяет сортировать или фильтровать выборку.

  • img – для отображения, например, текстуры, удобнее будет произвести демонстрацию в виде изображения. Передача изображений осуществляется не отдельными файлами, а в base64, например. (но объем данных!?)

group – группа характеристик, созданных для определённых категорий объектов. Это удобно для организации фильтрации в каталоге товаров. Не обязательно передавать, возможно на той стороне будет свое соответствие.

В продукте передаем массив с указанием id характеристики и значения: value, color, img.

 

Варианты

variant – вариант продукта отличающийся только одной или несколькими характеристиками.  Пример: футболки одного фасона, отличающаяся только цветами. У вариантов, как правило, разные цены и остатки. Пока не определено передвать ли id главного варианта или перечислять связь всех.

 

Склады

warehouse – перечень складов. Имеет id, name, также может иметь: adress, description.

 

Валюты

Взаиморасчет между сторонами происходит в местной валюте. Но если на рынке колебания стоимости местной валюты, то удобнее указывать цены в иностранной валюте.

base_cyrrency – валюта взаиморасчетов между сторонами.

cyrrency_rate – курс валюты относительно базовой. Здесь перечисляются используемые в файле валюты и указывается курс валюты относительно основной валюты посредством математического выражения, либо через курс этой валюты от общеизвестного источника с коэффициентом

cyrrency – указание валюты в продукте. 

 

Значения по умолчанию

для того, чтобы не указывать значения в каждом продукте, можно предварительно указать значения основных ключей по умолчанию, например: unit, unit_weight, unit_height, currency, tax_vat_rate.

 
 

Спецификация ключей для передачи данных о продуктах

В первую очередь рассматриваются требования для физических товаров, а затем особенности других типов продукта.

product * – корневой ключ для передачи информации о продукте (товарах и услугах). 

 

product_type – тип продукта указывает на специфические свойства продукта. Значения:

  • goods – физический товар, например: молоко, арматура, монитор.

  • content –  электронное интеллектуальное произведение, которое можно передать по каналам связи для личного (или по иным условиям) использования. Например: изображение, книга, аудио, видео, чертеж. Может предоставляться с ограничениями по времени или количеству воспроизведений и прочими ограничениями.

  • delivery – услуги по доставке физических товаров, например: авиадоставка, курьер, сборные грузы.

  • service  – услуга, например: стрижка, фотосессия, фрезерование металла, юридическая консультация, создание сайта, охрана, обед в ресторане.

Аренда жилья, авто, гостиничные услуги

Купон на приобретение товара

Фьючерс Обязательство

Долговые обязательства

Страхование

Услуги связи: интернет- телефония, хостинг АТС аренда платформы для создания сайта или фотошоп

Культурные театральное представление, живой концерт, спортивные состязания.

Чаевые

Лицензия 

Фрахт

Брокерские услуги

Радиовещание

Реклама

электронный билет. проездной билет

Возможно увеличение количества групп, если это потребуется на практике.

 

Идентификаторы продукта

 

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

manufacturer's article – артикул товара данный производителем

vendor_article – артикул товара данный поставщиком

 

id * – идентификатор продукта в рамках обмена данными. Как правило это генерируемая компьютером последовательность символов, т.к. при использовании артикула в качестве идентификатора могут возникнуть вышеописанные сложности.

seriаl_number – серийный номер экземпляра продукта. Уникальный идентификатор, который присваивается каждой единице продукта.

consignment_number (или series batch???) – номер партии продукта. Уникальный идентификатор, который присваивается однородной группе продуктов.

Прочие ean isbn позже рассмотрим

barcode – линейный штрих-код

qr_code – двумерный код

 

Наименования продукта

species_name  – общевидовое название товара. Например: кроссовки, керамическая плитка, смартфон, сумка, конструктор, мобильный телефон, экструдированный пенополистирол.

brand – торговая марка товара. Например: Mayolica, Audi, LEGO, Dior.

collection – коллекция  – стилистически схожая группа товаров в линейке производителя. может объединять разные виды товаров. Например, DAINO NATURAL (коллекция керамической плитки от Mayolica), BOOK TOTE (коллекция сумок от Dior).

model – модель  – некое сформированное производителем товарное предложение обладающий совокупностью определенных потребительских свойств. Например: A6 allroad quattro (автомобиль), Macbook Pro 19”(ноутбук) mi6 (телефон). Модель не исключает наличие вариаций характеристик или опций для индивидуализации товарного предложения. 

name – полное наименование продукта, позволяющее получить представление о продукте и отличии от аналогов. Наименование может собираться из значений других полей, например:

Керамическая настенная плитка Mayolica DAINO бежевая 34X67 

[Вид продукта + Производитель + Коллекция + характеристики цвета и размера];

 

Ноутбук Apple Macbook Pro 16", серый, i9 2,4 ГГц, 16 Гб

[Вид продукта + Производитель + Модель + характеристики];

 

Конструктор LEGO Hidden Side 70423 Автобус охотников за паранормальными явлениями 3000

[Вид продукта+Производитель+Серия продукта+Артикул+Наименование модели].

 

Описание

description – описание продукта.

html_description – описание с разметкой в формате html.

summary_description – краткое описание продукта, например, для показа в каталоге товаров.

description_url - адрес по которому находится дополнительная информация о продукте (url).

img_url – адрес для скачивания изображения продукта (url).

video_url – адрес для скачивания видео по продукту (url).

file_url – адрес для скачивания дополнительных документов (url).

Зафиксировать иной способ передачи файлов и сопоставления с продуктом

 

Характеристики

Массо-габаритные параметры 

Отдельная группа предопределенных характеристик товаров, используемая для расчета стоимости доставки и хранения.

Для облегчения процесса передачи данных вес передается в килограммах, объем в литрах, габариты в метрах.

nweght – вес нетто (netweight). Чистый вес товара без упаковки. 

weght – вес полунетто. Включается и масса первичной упаковки расфасованных товаров, неотделимой от товара до его потребления, например: силиконовый герметик в тубе.

volume – Объем нетто Применяется для жидкостей.

heigth – Высота нетто Глубина без упаковки 

width – Ширина нетто Глубина без упаковки 

length – Длина нетто Длина без упаковки 

depth – Глубина Глубина без упаковки

thickness – Толщина Толщина без упаковки

Дополнительно см. раздел Упаковка.

 

Дополнительные данные о товаре

 

Страна производства

Производитель

Поставщик/поставщики Для внутренних нужд

Информация о поставщике: Наименование, описание, лого

Информация о производителе Наименование, описание, лого Страна производства

Возрастная категория Ограничения для просмотра контента по возрасту. Значения: 0, 6, 12, 16, 18., 

религии Товар имеет отношение к удовлетворению сексуальных потребностей, либо иным образом эксплуатирует интерес к сексу.

Сигареты, Алкоголь, наркотики, лекарства Оружие

Кто производитель

Ограничения

16+

manufacturer_id – Идентификатор производителя. КОД ПРОИЗВОДИТЕЛЯ а не товара??

vendor_id – код поставщика.

Справочник этих производителей в начале? manufacturer { id, name, adress, tel}

 

Категория продукта

category_id – указание на id ранее объявленной категории. 

Дополнительный вариант для более простых случаев:

category – просто указываем наименование категории. 

 

Количество продукта

unit * – единица измерения количества . Зарезервированные значения в справочнике единиц измерения.

avl – (availability) доступный продукт. Количество товара в наличии, который можно незамедлительно передать (весь минус резерв и минус некондиционный).

reserved – зарезервированный продукт. Продукт, который есть в наличии, но его нельзя передать из-за того, что он предназначен для другого покупателя, сделавшего заказ ранее. Есть некая вероятность, что резерв может быть отменен. Весть товар = доступный + зарезервированный

warehouse – информация о товарах на складах. Передается массив данных в разрезе складов, при этом склады объявлены заранее.

 

//Заказы, логистика  

в разработке по необходимости (не первостепенная задача)

can_ordered – возможность заказать продукт. Логическое значение. По умолчанию значение: false. True, если продукт не уникальный и его можно заказать, даже если его нет сейчас в наличии, конечно, без гарантий сроков и в разумных количествах.

expected – ожидаемый товар.  Товар, который заказан и находится в пути от поставщика ( на производстве? СРОКИ? .

доступный из ожидаемого?

Товар, который есть у поставщика на складе СРОКИ? 

Стоимость продукта

Цены передаются В указанной валюте (currency) за единицу (unit), включая налоги, а отдельно передается информация сколько налогов включено в цену.

Цена, как правило, не включает в себя дополнительные расходы на упаковку и доставку, эти условия передаются отдельно.

cyrrency – указывается валюта цен данного товара

Разные валюты в рамках одного товарного предложения проработать дополнительно

price – базовая цена по которой осуществляется сделка между сторонами участвующими в обмене данными. абстрактное понятие price не используем.

price_retail – рекомендованная розничная цена. Часто поставщик запрещает продажу ниже данной цены.

price_vendor – цена поставки товара поставщиком. Используется внутри своей системы для вычисления, например, валовой прибыли или максимального порога скидок.

price_cost – цена себестоимости. Цена ниже которой в обычных ситуациях нельзя продавать продукт. Она больше цены поставщика с учетом, например, транспортных и других операционных и общехозяйственных расходов (алгоритм расчета у каждого хозяйствующего субъекта свой).

tax_vat_rate – Ставка НДС. Передается число означающее количество процентов, а если не облагается НДС, то это прямо указывается значением: 'not'.

 

price_indicative – ориентировочная цена. Используется, если нельзя точно рассчитать автоматически, а расчет будет проверяться при подтверждении заказа. При использовании ориентировочной цены возможно не следует брать предоплату. 

 

Для передачи дополнительных типов цен в начале файла объявляются любые другие типы цен, при этом префикс сохраняем, например: price_dealer1, price_dealer2.

 

Упаковка

pck – тара, упаковка (package). 

id – идентификатор упаковки.Необязательное значение

name – наименование упаковки. Наименование и описание упаковки

qty – количество единиц товара в упаковке(Quantity) Количество единиц товара в упаковке. Используется единица измерения передаваемая в ключе unit. Если не указано, значение принимается равным 1.

gweight – Вес брутто (Grossweight) Вес товара в транспортировочной 

gwidth – Ширина брутто (Gross width) Ширина в транспортной упаковке 

ghigth – Высота брутто (Gross higth) Высота в транспортной упаковке

glength – Длина брутто (Gross length) Длина в транспортной упаковке

Кратность отпуска и ограничения продажи 

multiples – кратность отпуска товара, выражается в используемых единицах измерения unit. Без указания кратности продажа идет в соответствии с единицей измерения (unit). Например:  цена пряжи указывается за кг, но  отпускаем по 100 г

 

min_batch – минимальный объем партии товара. Например: отпуск бензина от 5 литров.

и т. д.