Udoma техническая документация

Техническая документация

1. API-ключ сервисов интеграции

API-ключ предназначен для защиты вызовов всех сервисов интеграции UDOMA. Его можно получить в разделе "Настройки интеграции". API-ключ уникален и привязан к конкретной организации. Если Вы его сгенерировали заново, то нужно, во всех вызовах сервисов, старый заменить на новый. API-ключ при вызове передается в заголовке (header) запроса X-API-KEY.

Например:

X-API-KEY: 9af80846-7b7f-496d-a249-91c6fc724dc1

2.1. Импорт номенклатуры v.1

Сервис импорт номенклатуры предназначен для связи номенклатуры в учетной системе пользователя с номенклатурой в сервисе UDOMA.

При этом в интерфейсе UDOMA могут присутствовать как позиции номеналатуры, заведенные вручную через интерфейс, так и импортируемые через сервис. Сервис поддерживает работу с изменяемой частью номенклатуры. Т.е. у Вас нет необходимости выгружать каждый раз полный справочник номенклатуры (кроме первого раза). Достаточно выгружать записи измененные с последней выгрузки через сервис UDOMA, если Ваша учетная система хранит время изменения номенклатуры.

Тип метода: Post

Адрес: https://market.udoma.online/api/online/integration/v1/import-nomenclature

Дополнительный заголовок: Content-Type: application/json

Пример запроса

{
"turnOffMissingNomenclature": false,
"moveNomenclatureInGroups": true,
"nomenclatures": [{
"sourceSystemId": "n0001",
"groupSourceSystemId": "ng00101",
"name": "Молоко Раменское ультрапастеризованное 3,2%, 950г",
"shortDescription": "Ультрапастеризованное молоко будет полезно не только взрослым, но и маленьким детям.",
"description": "Состав: молоко нормализованное.\n\n\t\t\t\t\tПищевая ценность: жир 3,2г, белок 2,9г, углеводы 4,7г.\n\t\t\t\t\tЭнергетическая ценность: 59ккал/248кДж.\n\n\t\t\t\t\tХранить при температуре от +2`C до +25`C.\n\t\t\t\t\tПродукт во вскрытой упаковке хранить при температуре +2`C до +6`C.\n\t\t\t\t\tСрок годности 270 дней.\n\t\t\t\t\tГОСТ 31450-2013",
"vendorCode": "2342-v3",
"barCode": "123456789",
"alcohol": false,
"tobacco": false
},
{
"sourceSystemId": "n0002",
"groupSourceSystemId": "ng00102",
"name": "Кефир Раменский жирность 3.2%, тетрапак, объем 1л",
"shortDescription": "Это 100% натуральный кисломолочный продукт",
"description": "Состав (см. букву в маркировке): А-молоко нормализованное, закваска на кефирных грибах; В-молоко нормализованное, \t\t\t\t\tмолоко восстановленное, закваска на кефирных грибках. \n\n\t\t\t\t\tПищевая ценность в 100г продукта: жир 1г, белки 3г, углеводы 4г.\n\t\t\t\t\tЭнергетическая ценность: 37 ккал.\n\n\t\t\t\t\tХранить при температуре от +2 до +6`С до и после вскрытия упаковки.\n\t\t\t\t\tСрок годности: 14 суток.\n\t\t\t\t\tГОСТ Р 52093-2003",
"vendorCode": "2342-v4",
"alcohol": false,
"tobacco": false
},
{
"sourceSystemId": "n0003",
"groupSourceSystemId": "ng00103",
"name": "Творог Раменский Обезжиренный 0,2% 170г",
"shortDescription": "Обезжиренный творог - это сбалансированный натуральный состав и польза молочных продуктов.",
"description": "100% натуральный. \n\t\t\t\t\tСостав: молоко нормализованное, закваска.\n\t\t\t\t\tПищевая ценность в 100г: жир 0,2г, белки 16г, углеводы 1,8г.\n\t\t\t\t\tЭнергетическая ценность: 73 ккал.\n\t\t\t\t\tТемпература хранения от +2`C до +6`C.\n\t\t\t\t\tСрок годности: 30 сут.\n\t\t\t\t\tТУ 10.51.40-150-05268977-2014",
"vendorCode": "2342-v5",
"barCode": "333456789123777"
}]
}

Параметры запроса

Название

Описание

Обязательность

turnOffMissingNomenclature

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

Нет

moveNomenclatureInGroups

Перемещать товары в другую группах (если ранее сохраненный был в группе с другим groupSourceSystemId) По-умолчанию: "да"

Нет

sourceSystemId

Уникальный идентификатор номенклатуры в учетной системе

Да

groupSourceSystemId

Уникальный идентификатор родительской группы в учетной системе

Да

name

Наименование номенклатуры

Да

shortDescription

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

Нет

description

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

Нет

vendorCode

Артикул

Нет

barCode

Штрих-код товара. Очень важный параметр - по нему идёт сопоставление с нашим глобальным справочником товаров, а также его оперативное наполнение

Нет

okeiCode

Единица измерения. Если не указано или не входит в допустиме значени (796 - шт, 166 - кг, 163 - 100г, 778 - упак, 112 - л), то 796 (штука). Подробнее...

Нет

alcohol

Признак алкогольной продукции. По-умолчанию: "нет"

Нет

tobacco

Признак табачной продукции. По-умолчанию: "нет"

Нет

deleted

Признак того, что запись была удалена с момента предыдущей выгрузки. По-умолчанию: "нет"

Нет

Ошибки вызова

Статус

Код

Описание

400 Bad Request

Возможно невалидный json-объект запроса

400 Bad Request

invalid.json

В json-объекте отсутствуют обязательные поля

403 Forbidden

empty.api.key.not.allowed

Отсутствует API-ключ в заголовке запроса

403 Forbidden

api.key.not.found

Неверный или устаревшний API-ключ

400 BadRequest

nomenclature.doubles

Есть дубликаты в идентификаторах позиций номенклатуры

400 BadRequest

nomenclature.barcode.doubles

Есть дубликаты в штрих-кодах позиций номенклатуры

400 BadRequest

nomenclature.group.source.system.id.not.found

Не найдена группа номенклатуры

400 BadRequest

nomenclature.group.parent.source.system.id

Родительская группа импортируемой номенклатуры имеет дочерние группы. Группа должна содержать либо позиции номенклатуры, либо дочерние группы, но не вместе

2.2. Импорт номенклатуры v.2

Тип метода: Post

Адрес: https://market.udoma.online/api/online/integration/v2/import-nomenclature

Дополнительный заголовок: Content-Type: application/json

Пример запроса

{
"shopSourceSystemId": "s001",
"nomenclatures": [{
"sourceSystemId": "n0001",
"name": "Молоко Раменское ультрапастеризованное 3,2%, 950г",
"shortDescription": "Ультрапастеризованное молоко будет полезно не только взрослым, но и маленьким детям.",
"description": "Состав: молоко нормализованное.\n\n\t\t\t\t\tПищевая ценность: жир 3,2г, белок 2,9г, углеводы 4,7г.\n\t\t\t\t\tЭнергетическая ценность: 59ккал/248кДж.\n\n\t\t\t\t\tХранить при температуре от +2`C до +25`C.\n\t\t\t\t\tПродукт во вскрытой упаковке хранить при температуре +2`C до +6`C.\n\t\t\t\t\tСрок годности 270 дней.\n\t\t\t\t\tГОСТ 31450-2013",
"vendorCode": "2342-v3",
"barCode": "123456789",
"alcohol": false,
"tobacco": false
},
{
"sourceSystemId": "n0002",
"name": "Кефир Раменский жирность 3.2%, тетрапак, объем 1л",
"shortDescription": "Это 100% натуральный кисломолочный продукт",
"description": "Состав (см. букву в маркировке): А-молоко нормализованное, закваска на кефирных грибах; В-молоко нормализованное, \t\t\t\t\tмолоко восстановленное, закваска на кефирных грибках. \n\n\t\t\t\t\tПищевая ценность в 100г продукта: жир 1г, белки 3г, углеводы 4г.\n\t\t\t\t\tЭнергетическая ценность: 37 ккал.\n\n\t\t\t\t\tХранить при температуре от +2 до +6`С до и после вскрытия упаковки.\n\t\t\t\t\tСрок годности: 14 суток.\n\t\t\t\t\tГОСТ Р 52093-2003",
"vendorCode": "2342-v4",
"alcohol": false,
"tobacco": false
},
{
"sourceSystemId": "n0003",
"name": "Творог Раменский Обезжиренный 0,2% 170г",
"shortDescription": "Обезжиренный творог - это сбалансированный натуральный состав и польза молочных продуктов.",
"description": "100% натуральный. \n\t\t\t\t\tСостав: молоко нормализованное, закваска.\n\t\t\t\t\tПищевая ценность в 100г: жир 0,2г, белки 16г, углеводы 1,8г.\n\t\t\t\t\tЭнергетическая ценность: 73 ккал.\n\t\t\t\t\tТемпература хранения от +2`C до +6`C.\n\t\t\t\t\tСрок годности: 30 сут.\n\t\t\t\t\tТУ 10.51.40-150-05268977-2014",
"vendorCode": "2342-v5",
"barCode": "333456789123777"
}]
}

Параметры запроса

Название

Описание

Обязательность

shopSourceSystemId

Уникальный идентификатор магазина в учетной системе

Да

shopSourceSystemVersion

Информация о версиия учетной системы (например, версия 1С)

Нет

shopSourceSystemInfo

Информация об учетной системе (например, конфигурация 1С)

Нет

sourceSystemId

Уникальный идентификатор номенклатуры в учетной системе

Да

name

Наименование номенклатуры

Да

shortDescription

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

Нет

description

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

Нет

vendorCode

Артикул

Нет

barCode

Нет

okeiCode

Единица измерения. Если не указано или не входит в допустиме значени
(796 - шт, 166 - кг, 163 - 100г, 778 - упак, 112 - л), то 796 (штука). Подробнее...

Нет

alcohol

Признак алкогольной продукции. По-умолчанию: "нет"

Нет

tobacco

Признак табачной продукции. По-умолчанию: "нет"

Нет

deleted

Признак того, что запись была удалена с момента предыдущей выгрузки. По-умолчанию: "нет"

Нет

Ошибки вызова

Статус

Код

Описание

400 Bad Request

Возможно невалидный json-объект запроса

400 Bad Request

invalid.json

В json-объекте отсутствуют обязательные поля

403 Forbidden

empty.api.key.not.allowed

Отсутствует API-ключ в заголовке запроса

403 Forbidden

api.key.not.found

Неверный или устаревшний API-ключ

400 BadRequest

nomenclature.doubles

Есть дубликаты в идентификаторах позиций номенклатуры

400 BadRequest

nomenclature.barcode.doubles

Есть дубликаты в штрих-кодах позиций номенклатуры

400 BadRequest

nomenclature.group.source.system.id.not.found

Не найдена группа номенклатуры

3.1. Импорт цен и остатков по магазинам v.1

Сервис импорта цен и остатков по магазинам предназначен для импорта в систему UDOMA цен, остатков, а также опционально скидок в разрезе магазинов.

До начала использования сервиса необходимо в разделе "Настройки интеграции" привязать идентификаторы магазинов в Вашей учетной системе с магазинами заведенными через интерфейс UDOMA, а также (опционально) задать параметры импорта остатков.

Тип метода: Post

Адрес: https://market.udoma.online/api/online/integration/v1/import-assortment

Дополнительный заголовок: Content-Type: application/json

Пример запроса

{
"turnOffMissingAssortment": false,
"shopAssortment": [
{
"shopSourceSystemId": "s001",
"nomenclatureSourceSystemId": "n0001",
"remains": 2,
"price": 123.32
},
{
"shopSourceSystemId": "s001",
"nomenclatureSourceSystemId": "n0001",
"remains": 12,
"price": 100,
"salePrice": 90,
"salePercent": 10
},
{
"shopSourceSystemId": "s001",
"nomenclatureSourceSystemId": "n0002",
"remains": 80,
"price": 58.3
}
]
}

Параметры запроса

Название

Описание

Обязательность

turnOffMissingAssortment

Обнулять цены и остатки отсутствующего ассортимента (не пришли в запросе) в магазинах, по которым импортируются остатки. Установленный в true параметр желательно применять только при полном импорте остатков для подчистки по тем или иным причинам не попавшим в выборку позициям. По-умолчанию: "нет"

Нет

shopSourceSystemId

Уникальный идентификатор магазина в учетной системе

Да

nomenclatureSourceSystemId

Уникальный идентификатор номенклатуры в учетной системе

Да

remains

Остатки заданного товара в заданном магазине

Да

price

Новая цена продажи

Да

salePrice

Новая цена со скидкой. Если не задан, но задан salePercent, то будет вычислен автоматически

Нет

salePercent

% скидки в текущий период. Если не задан, но задан salePrice, то будет вычислен автоматически

Нет

Ошибки вызова

Статус

Код

Описание

400 Bad Request

Возможно невалидный json-объект запроса

400 Bad Request

invalid.json

В json-объекте отсутствуют обязательные поля

403 Forbidden

empty.api.key.not.allowed

Отсутствует API-ключ в заголовке запроса

403 Forbidden

api.key.not.found

Неверный или устаревший API-ключ

400 Bad Request

shop.not.found.by.source.system.id

В настройках интеграции нет привязки к магазину идентификатора в учетной системе пользователя

3.2. Импорт цен и остатков по магазинам v.2

Тип метода: Post

Адрес: https://market.udoma.online/api/online/integration/v2/import-assortment

Дополнительный заголовок: Content-Type: application/json

Пример запроса

{
"turnOffMissingAssortment": false,
"shopSourceSystemId": "s001",
"shopAssortment": [
{
"nomenclatureSourceSystemId": "n0001",
"remains": 2,
"price": 123.32
},
{
"nomenclatureSourceSystemId": "n0001",
"remains": 12,
"price": 100,
"salePrice": 90,
"salePercent": 10
},
{
"nomenclatureSourceSystemId": "n0003",
"remains": 80,
"price": 58.3
}
]
}

Параметры запроса

Название

Описание

Обязательность

turnOffMissingAssortment

Нет

shopSourceSystemId

Уникальный идентификатор магазина в учетной системе

Да

nomenclatureSourceSystemId

Уникальный идентификатор номенклатуры в учетной системе

Да

remains

Остатки заданного товара в заданном магазине

Да

price

Новая цена продажи

Да

salePrice

Новая цена со скидкой. Если не задан, но задан salePercent, то будет вычислен автоматически

Нет

salePercent

% скидки в текущий период. Если не задан, но задан salePrice, то будет вычислен автоматически

Нет

Ошибки вызова

Статус

Код

Описание

400 Bad Request

Возможно невалидный json-объект запроса

400 Bad Request

invalid.json

В json-объекте отсутствуют обязательные поля

403 Forbidden

empty.api.key.not.allowed

Отсутствует API-ключ в заголовке запроса

403 Forbidden

api.key.not.found

Неверный или устаревшний API-ключ

400 Bad Request

shop.not.found.by.source.system.id

В настройках интеграции нет привязки к магазину идентификатора в учетной системе пользователя

4. Экспорт заказов

Сервис экспорта заказов предназначен для экспорта во внешнюю учетную систему пользователя заказов и позиций заказа, проишедших за заданный период времени (как правило за время с предыдущей выгрузки).

С заданной периодичностью или вручную в учетную систему запрашивает заказы происшедшие с момента последнего вызова сервиса экспорта заказов UDOMA. Возвращаются только заказы совершенные в магазинах привязанных к учетной системе пользователя и позиции заказа (номенклатура) также привязанные к учетной системе пользователя.

Тип метода: Post

Адрес: https://market.udoma.online/api/online/integration/v1/export-orders

Дополнительный заголовок: Content-Type: application/json

Пример запроса

{
"shopSourceSystemId": "s001",
"dateFromUtc": "2010-09-10T15:38:51+05:00",
"dateToUtc": "2021-09-10T17:38:51+05:00"
}

Параметры запроса

Название

Описание

Обязательность

shopSourceSystemId

Уникальный идентификатор магазина в учетной системе

Да

dateFromUtc

Начало периода запроса (исключительно), время в формате UTC

Нет

dateToUtc

Окончание периода запроса (включительно), время в формате UTC

Нет

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

{
    "code": "search.successful",
    "detail": {
        "orders": [
            {
                "shopSourceSystemId": "s001",
                "orderId": "a4b74a75-3092-4672-a3cf-beeba96e4be8",
                "ticketNumber": "00037",
                "dateUtc": "2019-09-19T13:41:47.061163+05:00",
                "paymentMethod": "terminal",
                "positions": [
                    {
                        "nomenclatureSourceSystemId": "n001",
                        "itemsCount": 2,
                        "purchasePrice": 123.32
                    },
                    {
                        "nomenclatureSourceSystemId": "n002",
                        "itemsCount": 3,
                        "purchasePrice": 70
                    }
                ]
            },
            {
                "shopSourceSystemId": "s002",
                "orderId": "10b3543b-7872-4ec3-a4d8-ef6daca1c2f6",
                "ticketNumber": "00021",
                "dateUtc": "2019-09-19T17:41:47.061163+05:00",
                "paymentMethod": "cash",
                "positions": [
                    {
                        "nomenclatureSourceSystemId": "n002",
                        "itemsCount": 1,
                        "purchasePrice": 70
                    }
                ]
            }
        ]
    }
}

Параметры ответа

Название

Описание

Обязательность

order.ticketNumber

Номер заказа в системе UDOMA

Да

dateUtc

Время создания заказа, время в формате UTC

Да

paymentMethod

Способ оплаты (terminal или cash)

Да

order.deliveryCost

Стоимость доставки

Нет

position.nomenclatureSourceSystemId

Уникальный идентификатор номенклатуры в учетной системе

Да

position.itemsCount

Количество единиц товара

Да

position.purchasePrice

Цена на момент покупки

Да

Ошибки вызова

Статус

Код

Описание

400 Bad Request

Возможно невалидный json-объект запроса

400 Bad Request

invalid.json

В json-объекте отсутствуют обязательные поля

403 Forbidden

empty.api.key.not.allowed

Отсутствует API-ключ в заголовке запроса

403 Forbidden

api.key.not.found

Неверный или устаревший API-ключ

5. Интеграция с 1С

Функция интеграции с 1С предназначена для связи номенклатуры в учётной системе 1С с номенклатурой в сервисе UDOMA.

При этом в интерфейсе UDOMA могут присутствовать как позиции номенклатуры, заведённые вручную через интерфейс, так и импортируемые из 1С. Сервис поддерживает работу с изменяемой частью номенклатуры, поэтому у вас нет необходимости выгружать каждый раз полный справочник номенклатуры (кроме первого раза). Достаточно выгружать только изменения в записях с момента последней выгрузки через сервис UDOMA.

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

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

Скачать

Файл обработки:

Скачать

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

Скачать

Файл обработки:

Скачать

6. Инвентаризация товара

Инструкция по проведению инвентаризации для управляемой формы:

Скачать

Файл обработки:

Скачать