API предназначен для интеграции сервера валидации маркированной продукции СуперМаг Марко с внешней торговой системой. Описание структуры и функционала сервера валидации представлено в соответствующей статье.
Следует иметь в виду, что информацию о маркированном товаре внешняя система должна выгружать в СуперМаг Марко в виде GTIN+Серийный номер. Например:
В марке содержится следующая информация: 010460043993125621AJgXJ5.T. Для этой марки в СуперМаг Марко должно быть выгружено: 04600439931256AJgXJ5.T.
API представлено в отдельности для каждого сервиса в составе продукта:
{
"openapi" : "3.0.1",
"info" : {
"title" : "Сервис валидации КИЗ"
},
"security" : [ ],
"tags" : [ {
"name" : "Продажа"
}, {
"name" : "Возврат"
}, {
"name" : "Проверка продажи"
}, {
"name" : "Проверка возврата"
} ],
"paths" : {
"/base64/checkreturn" : {
"post" : {
"tags" : [ "Проверка возврата" ],
"summary" : "Проверка доступности КИЗ в формате base64 для возврата",
"description" : "Если товар с КИЗ можно возвращать, ответ будет списком кодов товаров. Иначе будет возвращено описание ошибки",
"operationId" : "postRet",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebReceipt"
}
}
}
},
"responses" : {
"200" : {
"description" : "КИЗ можно возвращать",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ItemsCodes"
}
}
}
},
"409" : {
"description" : "Ошибка (с описанием)",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
},
"500" : {
"description" : "Внутренняя ошибка сервера",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
}
}
}
},
"/checkreturn" : {
"post" : {
"tags" : [ "Проверка возврата" ],
"summary" : "Проверка доступности КИЗ для возврата",
"description" : "Если товар с КИЗ можно возвращать, ответ будет списком кодов товаров. Иначе будет возвращено описание ошибки",
"operationId" : "postRet_1",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebReceipt"
}
}
}
},
"responses" : {
"200" : {
"description" : "КИЗ можно возвращать",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ItemsCodes"
}
}
}
},
"409" : {
"description" : "Ошибка (с описанием)",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
},
"500" : {
"description" : "Внутренняя ошибка сервера",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
},
"example" : "Ошибка"
}
}
}
}
}
},
"/base64/checksell" : {
"post" : {
"tags" : [ "Проверка продажи" ],
"summary" : "Проверка доступности КИЗ в формате base64 для продажи",
"description" : "Если КИЗ доступен для продажи, ответ будет списком кодов товаров. Иначе будет возвращено описание ошибки",
"operationId" : "postMark",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebReceipt"
}
}
}
},
"responses" : {
"200" : {
"description" : "КИЗ доступен",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ItemsCodes"
}
}
}
},
"409" : {
"description" : "Ошибка (с описанием)",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
},
"500" : {
"description" : "Внутренняя ошибка сервера",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
}
}
}
},
"/checksell" : {
"post" : {
"tags" : [ "Проверка продажи" ],
"summary" : "Проверка доступности КИЗ для продажи",
"description" : "Если КИЗ доступен для продажи, ответ будет списком кодов товаров. Иначе будет возвращено описание ошибки",
"operationId" : "postMark_1",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebReceipt"
}
}
}
},
"responses" : {
"200" : {
"description" : "КИЗ доступен для продажи",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ItemsCodes"
}
}
}
},
"409" : {
"description" : "Ошибка (с описанием)",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
},
"500" : {
"description" : "Внутренняя ошибка сервера",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
}
}
}
},
"/base64/return" : {
"post" : {
"tags" : [ "Возврат" ],
"summary" : "Возврат КИЗ в формате base64 (проверка и изменение статуса)",
"description" : "Если КИЗ доступен для возврата, ответ будет пустым. Иначе будет возвращено описание ошибки",
"operationId" : "postRet_2",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebReceipt"
}
}
}
},
"responses" : {
"200" : {
"description" : "КИЗ возвращён",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
},
"409" : {
"description" : "Ошибка (с описанием)",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
},
"500" : {
"description" : "Внутренняя ошибка сервера",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
}
}
}
},
"/return" : {
"post" : {
"tags" : [ "Возврат" ],
"summary" : "Возврат КИЗ (проверка и изменение статуса)",
"description" : "Если КИЗ доступен для возврата, ответ будет пустым. Иначе будет возвращено описание ошибки",
"operationId" : "postRet_3",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebReceipt"
}
}
}
},
"responses" : {
"200" : {
"description" : "КИЗ возвращён",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
},
"409" : {
"description" : "Ошибка (с описанием)",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
},
"500" : {
"description" : "Внутренняя ошибка сервера",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
}
}
}
},
"/base64/sell" : {
"post" : {
"tags" : [ "Продажа" ],
"summary" : "Продажа КИЗ в формате base64 (проверка и изменение статуса)",
"description" : "Если КИЗ ещё не продан, его статус будет изменён и вернётся пустой ответ.",
"operationId" : "postSell",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebReceipt"
}
}
}
},
"responses" : {
"200" : {
"description" : "КИЗ продан",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
},
"409" : {
"description" : "Ошибка (с описанием)",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
},
"500" : {
"description" : "Внутренняя ошибка сервера",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
}
}
}
},
"/sell" : {
"post" : {
"tags" : [ "Продажа" ],
"summary" : "Продажа КИЗ (проверка и изменение статуса)",
"description" : "Если КИЗ ещё не продан, его статус будет изменён и вернётся пустой ответ.",
"operationId" : "postSell_1",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebReceipt"
}
}
}
},
"responses" : {
"200" : {
"description" : "КИЗ продан",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
},
"409" : {
"description" : "Ошибка (с описанием)",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
},
"500" : {
"description" : "Внутренняя ошибка сервера",
"content" : {
"text/plain(UTF-8)" : {
"schema" : {
"type" : "string"
}
}
}
}
}
}
}
},
"components" : {
"schemas" : {
"WebReceiptItem" : {
"required" : [ "item", "mark" ],
"type" : "object",
"properties" : {
"item" : {
"$ref" : "#/components/schemas/WebItem"
},
"mark" : {
"type" : "string",
"description" : "КИЗ"
}
},
"description" : "Позиция чека"
},
"WebItem" : {
"required" : [ "sku" ],
"type" : "object",
"properties" : {
"sku" : {
"type" : "string",
"description" : "Артикул"
},
"barcode" : {
"type" : "string",
"description" : "Штрихкод"
}
},
"description" : "Товар"
},
"SeqString" : {
"required" : [ "traversableAgain" ],
"type" : "array",
"properties" : {
"traversableAgain" : {
"type" : "boolean"
},
"empty" : {
"type" : "boolean"
}
},
"description" : "Список товаров",
"items" : {
"type" : "string",
"description" : "Список товаров"
}
},
"ItemsCodes" : {
"required" : [ "list" ],
"type" : "object",
"properties" : {
"list" : {
"required" : [ "traversableAgain" ],
"type" : "array",
"properties" : {
"traversableAgain" : {
"type" : "boolean"
},
"empty" : {
"type" : "boolean"
}
},
"description" : "Список товаров",
"items" : {
"type" : "string",
"description" : "Список товаров"
}
}
},
"description" : "Коды товаров"
},
"WebReceipt" : {
"required" : [ "items", "receiptId", "storeId" ],
"type" : "object",
"properties" : {
"storeId" : {
"type" : "integer",
"description" : "Идентификатор магазина",
"format" : "int64"
},
"receiptId" : {
"type" : "string",
"description" : "Номер чека"
},
"items" : {
"required" : [ "traversableAgain" ],
"type" : "array",
"properties" : {
"traversableAgain" : {
"type" : "boolean"
},
"empty" : {
"type" : "boolean"
}
},
"description" : "Список позиций чека, содержащих КИЗ",
"items" : {
"$ref" : "#/components/schemas/WebReceiptItem"
}
}
},
"description" : "Чек"
}
}
}
}
{
"openapi" : "3.0.1",
"info" : {
"title" : "Сервис загрузки информации о КИЗ"
},
"security" : [ ],
"tags" : [ {
"name" : "DeleteMarks"
}, {
"name" : "UploadMarks"
} ],
"paths" : {
"/deletemarks" : {
"post" : {
"tags" : [ "DeleteMarks" ],
"summary" : "Удалить информацию о КИЗ",
"operationId" : "delRoute",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebMarksToDelete"
}
}
}
},
"responses" : {
"200" : {
"description" : "Удалено"
},
"400" : {
"description" : "Ошибка разбора КИЗ, Ошибка удаления KIZ"
},
"500" : {
"description" : "Внутренняя ошибка"
}
}
}
},
"/uploadmarks" : {
"post" : {
"tags" : [ "UploadMarks" ],
"summary" : "Загрузить информацию о КИЗ",
"operationId" : "postRoute",
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WebMarks"
}
}
}
},
"responses" : {
"200" : {
"description" : "Загрузка успешна"
},
"400" : {
"description" : "Ошибка разбора KIZ"
},
"500" : {
"description" : "Внутренняя ошибка"
}
}
}
}
},
"components" : {
"schemas" : {
"SeqString" : {
"required" : [ "traversableAgain" ],
"type" : "array",
"properties" : {
"traversableAgain" : {
"type" : "boolean"
},
"empty" : {
"type" : "boolean"
}
},
"description" : "Товары, которым может принадлежать КИЗ (артикулы и/или штрихкоды)",
"items" : {
"type" : "string",
"description" : "Товары, которым может принадлежать КИЗ (артикулы и/или штрихкоды)",
"default" : "123456789"
},
"default" : "123456789"
},
"WebMark" : {
"type" : "object",
"properties" : {
"mark" : {
"type" : "string",
"description" : "КИЗ"
},
"state" : {
"type" : "integer",
"description" : "Состояние КИЗ (1 - доступен для продажи, 2 - продан)",
"format" : "int32",
"default" : 1,
"enum" : [ 1, 2 ]
},
"store" : {
"type" : "integer",
"description" : "Идентификатор магазина, в котором можно продавать товары с указанным КИЗ",
"format" : "int64"
},
"items" : {
"required" : [ "traversableAgain" ],
"type" : "array",
"properties" : {
"traversableAgain" : {
"type" : "boolean"
},
"empty" : {
"type" : "boolean"
}
},
"description" : "Товары, которым может принадлежать КИЗ (артикулы и/или штрихкоды)",
"items" : {
"type" : "string",
"description" : "Товары, которым может принадлежать КИЗ (артикулы и/или штрихкоды)",
"default" : "123456789"
},
"default" : "123456789"
}
},
"description" : "Информация о КИЗ"
},
"WebMarksToDelete" : {
"type" : "object",
"properties" : {
"marks" : {
"required" : [ "traversableAgain" ],
"type" : "array",
"properties" : {
"traversableAgain" : {
"type" : "boolean"
},
"empty" : {
"type" : "boolean"
}
},
"description" : "Список КИЗ для удаления",
"items" : {
"type" : "string",
"description" : "Список КИЗ для удаления"
}
}
}
},
"SeqWebMark" : {
"type" : "array",
"properties" : {
"traversableAgain" : {
"type" : "boolean"
},
"empty" : {
"type" : "boolean"
}
},
"items" : {
"$ref" : "#/components/schemas/WebMark"
}
},
"WebMarks" : {
"required" : [ "marks" ],
"type" : "object",
"properties" : {
"marks" : {
"type" : "array",
"properties" : {
"traversableAgain" : {
"type" : "boolean"
},
"empty" : {
"type" : "boolean"
}
},
"items" : {
"$ref" : "#/components/schemas/WebMark"
}
}
}
}
}
}
}
{
"openapi" : "3.0.1",
"info" : {
"title" : "Запрос всех ошибок обработки КИЗ"
},
"security" : [ ],
"tags" : [ {
"name" : "ErrorsLog"
} ],
"paths" : {
"/errors" : {
"get" : {
"tags" : [ "ErrorsLog" ],
"summary" : "Запрос всех ошибок",
"description" : "Вернёт все ошибки обработки КИЗ",
"operationId" : "getRoute",
"responses" : {
"200" : {
"description" : "Ошибки обработки КИЗ",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DBErrorMessage"
}
}
}
}
}
}
}
},
"components" : {
"schemas" : {
"DBErrorMessage" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "object"
},
"time" : {
"type" : "string",
"description" : "Время возникновения ошибки"
},
"src" : {
"type" : "string",
"description" : "Источник ошибки (чек, позиция)"
},
"err" : {
"type" : "string",
"description" : "Описание ошибки"
}
},
"description" : "Сообщение об ошибке"
}
}
}
}
{
"openapi" : "3.0.1",
"info" : {
"title" : "Сервис получения информации об изменениях состояния КИЗ"
},
"security" : [ ],
"tags" : [ {
"name" : "GetMarkState"
} ],
"paths" : {
"/api/v1.0/{mark}/markstate" : {
"get" : {
"tags" : [ "GetMarkState" ],
"operationId" : "postRoute",
"parameters" : [ {
"name" : "mark",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "Информация об изменениях состояния КИЗ",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/DBStateMessage"
}
}
}
},
"400" : {
"description" : "Ошибка разбора KIZ"
},
"500" : {
"description" : "Внутренняя ошибка"
}
}
}
}
},
"components" : {
"schemas" : {
"DBStateMessage" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "object"
},
"mark" : {
"type" : "string",
"description" : "КИЗ"
},
"time" : {
"type" : "string",
"description" : "Время изменения состояния"
},
"src" : {
"type" : "string",
"description" : "Источник (чек либо внешняя система)"
},
"stateChange" : {
"type" : "string",
"description" : "Состояние"
}
},
"description" : "Информация об изменениях состояния КИЗ"
}
}
}
}