Nomenclature(POST)

Этот раздел описывает метод API 1Bridge для синхронизации информации о товарах. В отличие от методов, специфичных для конкретных сервисов (как Yeda API), этот эндпоинт предназначен для общего обновления данных о номенклатуре в системе 1Bridge, которые затем могут использоваться для различных интеграций.

Обновление/Создание Номенклатуры

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

POST /nomenclature HTTP/1.1
Host: api.1bridge.net
Authorization: Bearer {your_access_token}
X-Partner-Id: {your_partner_id}
X-Place-Id: {your_place_id}
Content-Type: application/json

{
    "categories": [
        {
            "id": "uuid-category-1",
            "parentId": null,
            "name": "Молочные продукты"
        },
        {
            "id": "uuid-category-milk",
            "parentId": "uuid-category-1",
            "name": "Молоко"
        }
    ],
    "items": [
        {
            "barcode": {
                "type": "ean13",
                "value": "4601234567890",
                "values": [
                    "4601234567890"
                ],
                "weightEncoding": "none"
            },
            "categoryId": "uuid-category-milk",
            "description": {
                "composition": "молоко нормализованное",
                "expiresIn": "14",
                "general": "Отборное молоко 3.2%",
                "nutritionalValue": "60 ккал, 3 белки, 3.2 жиры, 4.7 углеводы",
                "packageInfo": "Тетрапак",
                "purpose": "Для питья",
                "storageRequirements": "+2..+6 C",
                "vendorCountry": "Казахстан",
                "vendorName": "Молочный Завод #1"
            },
            "exciseValue": null,
            "id": "uuid-item-milk-1",
            "images": [
                {
                    "order": 1,
                    "url": "https://example.com/images/milk1.jpg"
                }
            ],
            "isCatchWeight": false,
            "labels": [],
            "limitPerOrder": 10,
            "markingType": "default",
            "measure": {
                "quantum": 1.0,
                "unit": "GRM",
                "value": 1000
            },
            "name": "Молоко Отборное 3.2% 1л",
            "oldPrice": 550.00,
            "price": 490.00,
            "vat": 12, // Пример НДС 12%
            "vendorCode": "MILK-SELECT-1L",
            "vendorInn": null,
            "volume": {
                "unit": "MLT",
                "value": 1
            }
        }
        // ... другие товары ...
    ]
}

Request

POST /nomenclature

Headers

Name	Description	Required	Type
Authorization	`Bearer {your_access_token}`. Токен доступа, полученный при аутентификации партнера (см. раздел Аутентификация).	Да	string
X-Partner-Id	Уникальный идентификатор партнера в системе 1Bridge. Должен соответствовать ID, для которого был выдан токен.	Да	string
X-Place-Id	Уникальный идентификатор склада/ресторана/торговой точки в системе 1Bridge. Должен соответствовать UID склада в 1С	Да	string
Content-Type	`application/json`	Да	string

Body Parameters

Name	Description	Required	Type
`categories`	Массив объектов, описывающих категории товаров. Если категория уже существует по `id`, ее данные (например, `name`, `parentId`) могут быть обновлены. Новые создаются.	Да	Categories[]
`items`	Массив объектов, описывающих товары. Если товар уже существует по `id`, его данные обновляются. Новые товары создаются.	Да	NomenclatureItems[]

`Categories`

Объект, описывающий категорию товара.

Name	Description	Required	Type	Example	Constraints
`id`	Уникальный идентификатор категории в вашей системе (например, UUID из 1С). Используется для связи товаров и построения иерархии.	Да	string	`uuid-category-1`	Max 64
`name`	Наименование категории.	Да	string	`Молочные продукты`
`parentId`	`id` родительской категории для построения дерева. `null` или отсутствует для корневых категорий.	Нет	string	`uuid-category-1`	Max 64

`NomenclatureItems`

Объект, описывающий товар.

Name	Description	Required	Type	Example	Constraints
`id`	Уникальный идентификатор товара в вашей системе (например, UUID номенклатуры из 1С).	Да	string	`uuid-item-milk-1`	Max 64
`categoryId`	`id` категории из блока `categories`, к которой относится товар.	Да	string	`uuid-category-milk`	Max 64
`name`	Наименование товара.	Да	string	`Молоко Отборное 3.2% 1л`
`price`	Текущая цена продажи единицы товара. Для весовых товаров - цена за базовую единицу веса (например, 1 кг или 1000 г, уточнить стандарт).	Да	number (float)	`490.00`
`barcode`	Информация о штрихкоде(ах). См. Структура `Barcode`.	Да	Barcode
`description`	Детальное описание товара. См. Структура `ItemDescription`.	Да	ItemDescription
`images`	Массив изображений товара. См. Структура `Images`.	Да	Images[]
`isCatchWeight`	Флаг весового товара. `true` - весовой, `false` - штучный/фасованный.	Да	boolean	`false`
`measure`	Характеристики измерения (вес/объем) единицы товара. См. Структура `Measure`.	Да	Measure
`vendorCode`	Артикул товара (код производителя или внутренний артикул).	Да	string	`MILK-SELECT-1L`
`oldPrice`	Старая цена (до скидки). Используется для отображения скидки в некоторых сервисах.	Нет	number (float)	`550.00`
`vat`	Ставка НДС в процентах (например, `12`, `20`) или `-1` (Без НДС). Значение `0` недопустимо. Уточните допустимые значения для вашего региона/сервисов.	Нет	integer	`12`
`labels`	Массив строковых меток для особых признаков товара (`adult`, `prescription`, `frozen`, `alcoholic` и т.д.). Уточните список поддерживаемых меток.	Нет	string[]	`["frozen"]`
`limitPerOrder`	Максимальное количество данного товара в одном заказе. Для весовых - в квантах.	Нет	integer	`10`
`markingType`	Тип обязательной маркировки (если применимо, например, для системы "Честный ЗНАК"). Уточните возможные значения.	Нет	string	`default`
`exciseValue`	Тип акциза (если применимо). Уточните возможные значения.	Нет	string	`null`	Enum: `ССН`?
`vendorInn`	ИНН фактического продавца товара, если отличается от основного ИНН магазина/партнера (редкий случай).	Нет	string	`null`
`volume`	Физический объем упаковки товара для расчета доставки. См. Структура `Volume`.	Нет	Volume

Дополнительные структуры

`Barcode`

Name	Description	Required	Type	Example	Constraints
`value`	Основной штрихкод товара. Если штрихкода нет, может использоваться уникальный внутренний код.	Да	string	`4601234567890`
`type`	Тип основного штрихкода. Рекомендуется `ean13`, `ean8`, `upc`, `code128` или другой релевантный. Уточните список поддерживаемых типов.	Да	string	`ean13`	Enum: `ean13`, `code128`, etc.
`values`	Массив всех штрихкодов, присвоенных этому товару (включая основной `value`).	Нет	string[]	`["4601234567890"]`
`weightEncoding`	Алгоритм кодирования веса в штрихкоде для весовых товаров (`isCatchWeight = true`). `none` для штучных. Уточните поддерживаемые алгоритмы (например, `ean13-tail-gram-4`).	Да	string	`none`	Enum: `none`, `ean13-tail-..`

`ItemDescription`

Name	Description	Required	Type	Example
`general`	Основное (маркетинговое) описание товара.	Нет	string	`Отборное молоко 3.2%`
`composition`	Состав продукта.	Нет	string	`молоко нормализованное`
`nutritionalValue`	Пищевая ценность (КБЖУ).	Нет	string	`60 ккал, 3 белки, 3.2 жиры, 4.7 углеводы`
`expiresIn`	Срок годности в днях.	Нет	string	`14`
`storageRequirements`	Условия хранения.	Нет	string	`+2..+6 C`
`packageInfo`	Тип упаковки.	Нет	string	`Тетрапак`
`vendorName`	Наименование производителя.	Нет	string	`Молочный Завод #1`
`vendorCountry`	Страна производства.	Нет	string	`Казахстан`
`purpose`	Назначение товара (если применимо).	Нет	string	`Для питья`

`Images`

Name	Description	Required	Type	Example	Constraints
`url`	Прямая публично доступная ссылка на изображение товара. 1Bridge не хранит изображения, используйте свой хостинг или CDN.	Да	string (uri)	`https://example.com/images/milk1.jpg`
`order`	Порядок сортировки изображений (0 или 1 - главное, остальные по возрастанию).	Нет	integer	`1`	Min 0

`Measure`

Характеристики измерения единицы товара.

Name	Description	Required	Type	Example	Constraints
`value`	Номинальное значение веса или объема единицы товара. Для весовых - базовая единица (например, 1000 для грамм или 1 для кг).	Да	number (float)	`1000`
`unit`	Единица измерения `value`. Рекомендуется: `GRM` (граммы), `KGM` (килограммы), `MLT` (миллилитры), `L` (литры), `PCS` (штуки). Уточните стандартный набор.	Да	string	`L`	Enum: `GRM`, `L`...
`quantum`	Минимальный шаг заказа (квант) для весовых товаров (`isCatchWeight = true`). Указывается как доля от `value`. Например, если `value`=1000, `unit`=GRM, `quantum`=0.1, то минимальный заказ 100 г.	Да (для весовых)	number (float)	`1.0`

`Volume`

Физический объем упаковки (для расчета доставки).

Name	Description	Required	Type	Example	Constraints
`value`	Значение объема.	Да	integer	`1`	Min 1
`unit`	Единица измерения объема. `CMQ` (куб. см) или `DMQ` (куб. дм / литры).	Да	string	`DMQ`	Enum: `CMQ`, `DMQ`

Responses

200 OK

Успешная обработка запроса. Тело ответа обычно пустое или содержит краткий статус.

{
    "status": "success",
    "message": "Nomenclature data accepted for processing."
}

(Формат успешного ответа может отличаться)

400 Bad Request

Ошибка в формате запроса (например, отсутствуют обязательные поля, неверный тип данных). Тело ответа содержит массив ошибок.

[
    {
        "code": 4001, // Пример внутреннего кода ошибки
        "field": "items[0].price",
        "description": "Price must be a positive number."
    }
]

Name	Description	Type
`code`	Внутренний код ошибки 1Bridge.	integer
`description`	Описание ошибки.	string
`field`	(Опционально) Поле, вызвавшее ошибку.	string

401 Unauthorized

Ошибка аутентификации (неверный или просроченный Authorization токен, или X-Partner-Id не соответствует токену).

{
    "code": 4010,
    "description": "Invalid or expired access token."
    // "reason": "Access token has expired." (Может присутствовать)
}

403 Forbidden

Токен валиден, но у данного партнера нет прав на выполнение этой операции.

{
    "code": 4030,
    "description": "Permission denied to update nomenclature."
}

500 Internal Server Error

Внутренняя ошибка на сервере 1Bridge при обработке запроса.

{
    "code": 5000,
    "description": "An internal error occurred. Please try again later or contact support."
}

(Коды ошибок 400X, 401X, 403X, 500X являются примерами, используйте ваши реальные коды, если они есть, или обратитесь к разделу Error Codes.)