Дополнительно:

1. Если поле “data” отсутствует, то в проданные попадут все марки, в указанных резервах

2. Возвращать марки по номеру резерва нельзя

3. Если отсутствуют поля “data” и “orderNumbers” - вернется ошибка

4. Если есть и “data” и “orderNumbers”, то в проданные попадут только марки из data. Марки которых нет в “data”, но они есть в указанных резервах будут сняты с резерва (вернутся в оборот).

Ответ:

Стандартный HTTP-пакет с кодом ответа. В теле:

Всегда присылается что все «ОК».

Запрос статуса марки

Имя: cash/validate

Метод: POST

Входящий:

JSON, состоящий из полей, общих для всех типов товаров, а так же из полей определяемых конкретным типом товара (определяется на основе "productType").

• Общая часть:

{ “id” <ID>, “version”: <версия API>, "inn": <ИНН>, “shop” : <номер магазина> , “cash” : <номер кассы>, “operationType” : <тип операции>,  “productType” : <тип товара>, “barcode” : <ШК товара>, "item":<артикул товара>, “deletionType” : <тип удаления> }

• Полный JSON для алкоголя(подчеркнута общая часть):

{ “id” <ID>, “version”: <версия API>, “shop” : <номер магазина> , “cash” : <номер кассы>, “operationType” : <тип операции>,  “productType” : <тип товара>, “barcode” : <ШК товара>, "item":<артикул товара>, “deletionType” : <тип удаления>, “excise” : <АМ>, “alcocode” : [<алкокод>, ...], “promoBarcode” : <ШК товара>, “strictСheck” : <признак проверки на остатках>, "price" : <цена товара>, “promoComponents” : [ { “alcocode” : [<алкокод>, ...],  “price” : <цена в копейках>, “barcode” :[ <ШК товара>, ... ], "item":<артикул компонента>}, ...]  }

• Полный JSON для табака(подчеркнута общая часть):

{ “id” <ID>, “version”: <версия API>, "inn": <ИНН>, “shop” : <номер магазина> , “cash” : <номер кассы>, “operationType” : <тип операции>,  “productType” : <тип товара>, “barcode” : <ШК товара>, "item":<артикул товара>,  “mark” : <код маркировки> }

Значения:

Общие:

• id - число, идентификатор запроса, обязательное поле
• version - число, версия API, обязательное поле (значения -  {1})
• inn - строка, 
• shop - число, номер магазина, обязательное поле
• cash - число, номер кассы, обязательное поле
• operationType -число, тип операции, обязательное поле {0 - продажа, 1 - возврат}
• productType - число, тип товара, обязательное поле  (значения - {1 - алкоголь, 2 - табак, ... })
• barcode - строка, штрихкод, необязательное поле (если не включена проверка ШК)
• item - строка, артикул, необязательное поле (если не включена проверка по артикулу)

Алкоголь:

• excise - строка, акцизная марка, обязательное поле
• alcocode - массив строк, алкокод, необязательное поле (если не включена проверка алкокодов)
• promoBarcode - строка, штрихкод промонабора, необязательное поле (если не включена проверка ШК) [если присутствует значения, в и случае возникнования ошибки, то поле будет добавлено в таблицу с описанием ошибок]
• strictСheck - boolean, признак строгой проверки АМ (true / false)
• price - число, цена товара в копейках
• promoComponents - массив компонентов , компонент состоит из списка алкокодов (поле "alcocode"), цены компонента (поле "price"), списка штрихкодов (поле "barcode") и артикула (поле "item")

Табак:

• mark - строка, обязательное поле

Исходящий:

стандартный HTTP-пакет с кодом ответа. В теле:

{ “id”: < ID > , “result”: < результат проверки > , “message”: < сообщение > , “barcode”: < ШК товара > , “alcocode”: < алкокод товара > , "amrc": < МРЦ в копейках > }

Значения:

• Id - число
• result - true / false
• message - строка, текстовое описание ошибки(или “OK” если ошибок нет).
• barcode - строка, необязательное поле. Добавляется если проверка успешна и barccode загружен в базу.
• alcoCode - строка, только для алкогольного товара, необязательное поле. Добавляется если проверка успешна и alcocode загружен в базу.
• amrc - целое число, только для алкогольного товара, необязательное поле. Минимальная розничная цена (в копейках).

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

{ "id": 101, "version": 1, "shop": 10000, "cash": "5", "operationType": 0, "productType": 1, "excise": "excise12340000101003", "alcocode": [], "barcode": "", "strictCheck": true }

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

{ "id": 101, "result": true, "message": "OK", "alcocode": "alcocode12340000101003", "barcode": "012340000101003", "amrc": 50000 }

Обратная связь для ERP (статусы по пакетам)

Имя: erp/status

Метод: POST

Входящие:

{ “id” : [<id пакета>, ...], “version”: <версия API>, “shop” : <номер магазина>}

Значения:

• id - массив чисел, обязательное поле (тип long)
• version - число, обязательное поле (значения -  {1})
• shop - число, обязательное поле (long)

Исходящие:

{ “version”: <версия API>, “shop” : <номер магазина>,  “errorCode” : <код ошибки входящего запроса>, “message” : <сообщение по входящему запросу>, “packets”:[{“id”: <id пакета>, “status”: <статус обработки пакета>, “errorCode”: <код ошибки пакета>, “message”: <сообщение по пакету>, “data” : [ { “field” : “<Имя поля с ошибкой>”, “value”: ”<Содержимое поля>”, “errorCode” : <код ошибки>, “message” : <сообщение>}, ... ]}, ...}

Значения:

• version - число(значения -  {1})
• shop - число

• errorCode - число, код ошибки при обработке текущего входящего запроса:

  Код ошибки	Текст ошибки	Описание ошибки
  0	OK	Без ошибок.
  504	Не корректное значение поля	Ошибка в текущем запросе: отсутствует обязательное поле, недопустимое значения поля.
  1000	Внутренняя ошибка сервиса	Внутренняя ошибка сервиса.

• message - строка, описание ошибок во всем запросе
• packets - массив json:
  • id - число
  • status - число:
    • 0 - Документ не существует;
    • 1 - Документ не прошел проверку валидности структуры;
    • 2 - Документ обрабатывается;
    • 3 - Документ обработан полностью;
    • 4 - Документ обработан, но некоторые сущности не прошли валидацию;
    • 5 - Произошла внутренняя критическая ошибка сервиса

  • errorCode - число, код ошибки при обработке пакета с заданным id, на уровне всего пакета:

    Код ошибки	Текст ошибки	Описание ошибки
    0	OK	Без ошибок.
    502	Неизвестный идентификатор (id) пакета	Пакет с запрашиваемым id не найден в системе (Получение статуса обработки пакета)
    504	Не корректное значение поля	Ошибки в запрашиваемом пакете: отсутствует обязательное поле, недопустимое значения поля. Запрашиваемый пакет не был обработан.
    506	Ошибка при обработке марки	Ошибки в процессе обработки запрашиваемого пакета. Пакет обработан частично. Пример: если в запросе на выгрузку из ERP списка активных АМ, одна АМ из списка пустая, а другая уже проданная, то пакет получит код ошибки 506, а конкретные АМ(поле "data") errorCode 501 и 507 соответственно. Остальные АМ из пакета будут обработаны в стандартном режиме.
    1000	Внутренняя ошибка сервиса	Внутренняя ошибка сервиса.

  • message - строка, описание ошибок связанных с конкретным пакетом
  • data - массив json, может быть пустым или отсутствовать если ошибок нет:
    • field - строка
    • value - строка
    • errorCode - число, код ошибки для конкретной записи в пакете с заданным выше Id (см. таблицу "Коды ошибок (статусы по пакетам)" ниже).
    • message - строка

Массив “data“ может быть пустым. Содержит описание полей с ошибками, если они есть, или ошибки в обработке вложенных сущностей, например одна из списка загружаемых в запрашиваемом пакете акцизных марок уже числится в проданных.

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

{
	"id": [101, 102],
	"version": 1,
	"shop": 10000
}

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

{
	"version": 1,
	"shop": 10000,
	"errorCode": 0,
	"message": "OK",
	"packets": [{
			"id": 101,
			"status": 3,
			"errorCode": 0,
			"message": "OK"
		}, {
			"id": 102,
			"status": 1,
			"errorCode": 504,
			"message": "Неожиданное значение поля",
			"data": [{
					"field": "productType",
					"value": "2",
					"errorCode": 504,
					"message": "должно быть между 1 и 1"
				}
			]
		}
	]
}

Коды ошибок (статусы по пакетам):

Журнал нарушений - обратная связь по проблемным АМ/КМ (сервис на стороне ERP)

Отправляем данные по проблемным АМ с периодичностью 10 мин (настраивается в application.properties --> setmark.error.report.timer в мс).

Метод: POST

Исходящие:

{ “id” : <id>, “version”: <версия API>, “data” : [ {“packetId” : <id пакета>, “productType” : <тип товара>, “shop” : <номер магазина>, “cash” : <номер кассы>, “excise” : “ <АМ>”, “barcode” : “ <ШК>”, “promoBarcode” : “ <ШК>”, “timestamp” : “<дата и время>”, “errorCode” : <код ошибки>, “message” : <сообщение> }, ...  ] }

Значения:

• id - число, генерируется сервисом
• version - число(значения -  {1})
• data - массив json:
• packetId - число
• productType - число, обязательное поле  (значения - {1 - алкоголь, 2 - табак, ... })
• inn - строка
• shop - число
• cash - число
• excise - строка
• barcode - строка
• promoBarcode - строка
• timestamp - дата (формат дата регулируется в конфигурации SetMark - параметр "spring.jackson.date-format" в aplication.properties)
• errorCode - число
• message - строка

Пример запроса от сервиса к ERP:

{
	"id": -2025307452,
	"version": 1,
	"data": [
		{
			"packetId": 0,
			"productType": 1,
            "inn": "0000000000",
			"shop": 10000,
			"cash": 25,
			"excise": "excise12340000101004",
			"barcode": null,
			"promoBarcode": null,
			"timestamp": "2021-11-23T14:17:35+0300",
			"errorCode": 3,
			"message": "Продажа АМ без запаса"
		}, {
			"packetId": 0,
			"productType": 1,
            "inn": "0000000000",
			"shop": 10000,
			"cash": 26,
			"excise": "excise12340000101005",
			"barcode": null,
			"promoBarcode": null,
			"timestamp": "2021-11-23T14:17:35+0300",
			"errorCode": 3,
			"message": "Продажа АМ без запаса"
		}
	]
}

Пример запроса от сервиса к ERP (ошибка проверки КМ в ОИСМ):

Значения

• errorCode - 17, код ошибки, переданной кассой в SM. В дальнейшем, при появлении новых типов ошибок передаваемых кассой, "errorCode" сохранит свое значение как 17.
• properties - структура, содержит информацию о конкретном значении конкретного параметра связанного с ошибкой, полученной кассой из внешней системы (в данном случае ОИСМ). 
• message - "Ошибка проверки КМ в ОИСМ". Для данного нарушения является константой.
• externalErrorCode - 18, цифровой идентификатор ошибки, возникающей при проверке КМ в ОИСМ (соответствует тексту "Ошибка проверки КМ в ОИСМ").
• TAG_2106 - ФФД1.2, тег "результат проверки сведений о товаре" в который записывается и в дальнейшем передается в ОФД, результат проверки кода маркировки в ОИСМ.

{
	"id": -2025307452,
	"version": 1,
	"data": [
		{
			"shop": 10000,
			"packetId": 0,
			"productType": 3,
			"cash": 25,
			"excise": "01066000000000092163c6724594ba4240640191ffd092Hncw1Ydy8EmpvyzbeyqEe9/aiw8cG7op8LPwU03vLPbn+G0dZNRQQu6cDqlCYQWPtBxY+3cqJgd2caC1VuStIg==",
			"barcode": "6600000000009",
			"timestamp": "2021-11-23T13:17:35+0300",
			"errorCode": 17,
			"message": "Ошибка проверки КМ в ОИСМ",
			"externalErrorCode": 18,
			"properties": {
				"TAG_2106": "11"
			}
		}
	]
}

Список кодов ошибок

начиная с версии 1.3

до версии 1.3