ТЗ на разработку модуля CMS

Дата: 28 марта 2026

Версия: 1.0

Продукт: Бикодо: Онлайн-чеки и учет

Цель:

Создать модуль для CMS (1C-Bitrix, WooCommerce, OpenCart), обеспечивающий интеграцию интернет-магазина с приложением Бикодо: Онлайн-чеки и учет в кассе Эвотор.

Модуль должен автоматически передавать заказы из интернет-магазина в приложение на кассе, обеспечивать формирование чеков в соответствии с требованиями законодательства, а также синхронизировать остатки товаров между сайтом и кассой.

Дополнительно модуль должен поддерживать работу с маркированными товарами (т.е учитывать какой именно вид маркировки имеет товар), учитывать характеристики товаров (например, размер, цвет)

Определение:

Бикодо: Онлайн-чеки и учет - приложение для касс Эвотор https://bicodo.ru/p?id=67

Эвотор - Онлайн-касса https://evotor.ru/

Техническое задание:

1. UI

Настройки в администраторской части модуля:

‍

Ключ доступа для кассы Эвотор

Касса Эвотор выполняет авторизацию в модуле с использованием ключа доступа. При каждом запросе ключ передается в модуль и проходит проверку. Доступ разрешается только при успешной валидации ключа.

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

‍

Генерация ключа доступа

При нажатии на кнопку "Сгенерировать" генерируется 11 значный ключ доступа который вставляется в INPUT (Ключ доступа для кассы Эвотор).

Формат: Разрешаются только числовые значения.

Пример: 12345678901

‍

Язык для выгрузки данных

Необходимо реализовать поле выбора языка (select) для выгрузки данных в кассу Эвотор.

Требования Тип поля: выпадающий список (select) Значения: список доступных языков, настроенных в CMS Значение по умолчанию: язык по умолчанию сайта

Логика работы Выбранный язык используется при формировании данных для передачи в кассу Эвотор При выгрузке товаров должны использоваться в:

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

характеристики

описания

‍

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

Дать пользователю выбирать характеристики товара которые можно выводить при событиях продаж и экспорта товара в кассу Эвотор.

Как в итоге показываются в карточке товаров в кассе Эвотор:

т.е Наименование | Харктеристика 1, Харктеристика 2 и т.д

✏️Note

Характеристики товара — это дополнительные свойства товаров (цвет, размер, бренд), используемые для фильтрации, сравнения и детального описания на витрине.

Характеристика товара в CS-CART на витрине:

Характеристика товара в CS-CART в карточке товара:

‍

Информация

Необходимо реализовать раздел «Информация» в административной части модуля.

Назначение Раздел предназначен для предоставления пользователю ссылок на:

Официальный сайт: https://bicodo.ru , ссылка введет на https://bicodo.ru/p?id=67

Документация: https://wiki.bicodo.ru, ссылка введет на https://wiki.bicodo.ru/index.php/%D0%91%D0%B8%D0%BA%D0%BE%D0%B4%D0%BE:_%D0%9E%D0%BD%D0%BB%D0%B0%D0%B9%D0%BD_%D1%87%D0%B5%D0%BA%D0%B8_%D0%B8_%D1%83%D1%87%D0%B5%D1%82_(ru)

‍

Сохранение

Кнопка сохранения настроек

Логика:

Сохраняются в базу данных настройки:

Ключ доступа

Язык для выгрузки данных

Выбранные характеристики товаров

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

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

‍

Функциональные требования

В блоке должен быть доступен выбор вида товара (включая маркированные категории)

Значения выбираются из заранее заданного списка:

Поле выбора вида товара (select):

0 — Товар 100 — Услуга 204 — Алкоголь: Безалкогольное пиво 300 — Лотерея: Лотерейный билет 301 — Лотерея: Выигрыш в лотерею 401 — Маркированный товар: Обувь 402 — Маркированный товар: Табак 403 — Маркированный товар: Шины 404 — Маркированный товар: Духи 405 — Маркированный товар: Фототовары 406 — Маркированный товар: Одежда и белье 407 — Маркированный товар: Другая курительная продукция 408 — Маркированный товар: Молочная продукция 409 — Маркированный товар: Вода 410 — Маркированный товар: Меховые изделия 411 — Маркированный товар: Велосипеды 412 — Маркированный товар: Антисептики и дезинфицирующие средства 413 — Маркированный товар: Биологически активные добавки к пище 414 — Маркированный товар: Соковая продукция и безалкогольные напитки 415 — Маркированный товар: Кресла-коляски 416 — Маркированный товар: Медицинские изделия 417 — Маркированный товар: Растительные масла 418 — Маркированный товар: Морепродукты (Икра) 419 — Маркированный товар: Ветеринарные препараты 420 — Маркированный товар: Корма для животных 421 — Маркированный товар: Лекарства 422 — Маркированный товар: Ювелирные изделия

Пример html:

html
<select name="product_data[bridgecte_marksevotor]" id="bridgecte_marksevotor">
            <option value="0">Товар</option>
            <option value="100">Услуга</option>
            <option value="204" selected="">Алкоголь: Безалкогольное пиво</option>
            <option value="300">Лотерея: Лотерейный билет</option>
            <option value="301">Лотерея: Выигрыш в лотерею</option>
            <option value="401">Маркированный товар: Обувь</option>
            <option value="402">Маркированный товар: Табак</option>
            <option value="403">Маркированный товар: Шины</option>
            <option value="404">Маркированный товар: Духи</option>
            <option value="405">Маркированный товар: Фототовары</option>
            <option value="406">Маркированный товар: Одежда и белье</option>
            <option value="407">Маркированный товар: Другая курительная продукция</option>
            <option value="408">Маркированный товар: Молочная продукция</option>
            <option value="409">Маркированный товар: Вода</option>
            <option value="410">Маркированный товар: Меховые изделия</option>
            <option value="411">Маркированный товар: Велосипеды</option>
            <option value="412">Маркированный товар: Антисептики и дезинфицирующие средства</option>
            <option value="413">Маркированный товар: Биологически активные добавки к пище</option>
            <option value="414">Маркированный товар: Соковая продукция и безалкогольные напитки</option>
            <option value="415">Маркированный товар: Кресла-коляски</option>
            <option value="416">Маркированный товар: Медицинские изделия</option>
            <option value="417">Маркированный товар: Растительные масла</option>
            <option value="418">Маркированный товар: Морепродукты (Икра)</option>
            <option value="419">Маркированный товар: Ветеринарные препараты</option>
            <option value="420">Маркированный товар: Корма для животных</option>
            <option value="421">Маркированный товар: Лекарства</option>
            <option value="422">Маркированный товар: Ювелирные изделия</option>
</select>

Логика работы

Если CMS не поддерживает маркированные товары:

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

Если CMS поддерживает маркированные товары: при условии что все виды маркированных и не маркированных товаров поддерживаются

Особенности

Список видов товаров должен соответствовать требованиям Эвотор

Выбранное значение передается при:

продаже товара

экспорте товаров в кассу

Массовые изменения карточек товара

Для упрощения работы с маркированными товарами необходимо реализовать функцию массового изменения вида товара.

Назначение

Функция позволяет избежать ручного редактирования каждой карточки товара и быстро назначить вид товара (в том числе маркированный) сразу для нескольких товаров.

Функциональные требования

В списке товаров (административная панель) добавить действие: «Массовое изменение вида товара (Бикодо: Онлайн-чеки и учет)»

Действие применяется к выбранным товарам (через чекбоксы)

Поведение

При выборе действия:

Открывается форма (модальное окно или отдельный блок)

В форме доступно поле:

Вид товара (select со списком типов товаров)

Кнопка: «Сохранить»

Логика работы

После сохранения выбранный вид товара применяется ко всем выбранным товарам

Значение записывается в поле модуля для каждого товара

Изменения должны происходить без необходимости открытия каждой карточки

Особенности

Используется тот же список видов товаров, что и в карточке товара

Функция должна работать быстро даже при большом количестве товаров

Должна быть защита от случайного применения (например, подтверждение действия)

Назначение для пользователя

Функция необходима для:

быстрой настройки маркированных товаров

массового обновления данных

сокращения времени на настройку каталога

Статусы заказов

Назначение

Для корректной работы с чеками необходимо добавить дополнительный (промежуточный) статус заказа.

Этот статус позволяет избежать повторной отправки чека на кассу.

Требование

В CMS необходимо создать новый статус заказа:

Обработан: Чек на обработке у кассы

‍

Логика работы (без модуля)

Стандартный путь продажи выглядит так:

Логика работы (с модулем)

При продаже на сайте статус заказа изменяется на "Обработан" (статус "обработан" значит "оплачено клиентом")

Далее мы добавляем промежуточный статус:

Обработан: Чек на обработке у кассы

тем самым путь продажи меняется на:

Важно

Пока заказ находится в статусе: «Обработан: Чек на обработке у кассы» он считается уже отправленным в кассу

Повторная отправка чека не должна происходить

Зачем это нужно

Чтобы избежать ситуации, когда:

касса повторно запрашивает заказ

и чек печатается второй раз

Этот статус служит маркером, что чек уже был отправлен в кассу.

‍

2. Запросы от сервера к модулю

Сервер по адресу: https://automation.bicodo.ru/_import/evotor.php отправляет запрос в модуль CMS.

Тип запросов: Все входящие запросы являются POST запросами

Заголовки (Headers): Содержит Content-Type: application/json

Кодировка: UTF-8

‍

Авторизация

URL для обработки запроса

Разработчик модуля должен реализовать endpoint (URL), который будет принимать входящие запросы от сервера Бикодо, и предоставить этот URL заказчику для настройки интеграции.

Пример (для CS-Cart):

url
/index.php?dispatch=postbicodo_receiptinv.check&addon=bicodo_receiptinv

Конкретный URL зависит от CMS, но должен быть доступен извне (по HTTPS).

Формат запроса

Запрос отправляется в формате JSON и содержит ключ доступа:

Пример:

json
{
  "keyss": "12345678"
}

где:

keyss — ключ доступа (строка)

Логика обработки

Модуль должен принять JSON-запрос

Извлечь значение поля keyss

Сравнить его с ключом доступа, сохранённым в настройках модуля

Ответ модуля:

Результат проверки	JSON массив
Ключ корректный	["ok"]
Ключ некорректный	["error"]

‍

Требования

Endpoint должен принимать внешние HTTP/HTTPS-запросы

Ответ должен быть строго в формате JSON

Без дополнительных данных и сообщений

Проверка ключа обязательна для всех входящих запросов

Обязательное условие: Запрос от сервера и ответ модуля сохранить в логах CMS

‍

Вывод остатков

URL для обработки запроса

Пример (для CS-Cart):

url
/index.php?dispatch=postbicodo_receiptinv.ost&addon=bicodo_receiptinv

Конкретный URL зависит от CMS, но должен быть доступен извне (по HTTPS).

Формат запроса

Запрос отправляется в формате JSON и содержит ключ доступа:

Пример:

json
{
  "keyss": "12345678"
}

где:

keyss — ключ доступа (строка), логика работы keyss

Ответ модуля:

Остатки товаров активные на сайте

Пример:

json
[
    {
        "code": "180",
        "article_number": "Q01802L8VS",
        "quantity": "23.00",
        "price": "1.00",
        "name": "Пакет2",
        "description": "Пакет",
        "alcoCodes": "[]",
        "is_excisable": "false",
        "is_age_limited": "false",
        "classification_code": "",
        "measure_name": "шт",
        "tax": "NO_VAT",
        "allow_to_sell": "true",
        "cost_price": "0.00",
        "id": "045117b0e0a14a24ab9765e79cbf113f",
        "type": "NORMAL"
    },
    {
        "code": "292",
        "article_number": "ARE5JHDOLK03",
        "quantity": "0.00",
        "price": "5000.00",
        "name": "HOKA M Challenger ATR 6 | Сезон:Лето, Бренд:Hoka",
        "description": "В шестой версии Challenger ATR 6 укрепляет свою репутацию самых универсальных кроссовок. Как следует из названия, эти кроссовки-вездеходы бросают в",
        "alcoCodes": "[]",
        "is_excisable": "false",
        "is_age_limited": "false",
        "classification_code": "",
        "measure_name": "шт",
        "tax": "NO_VAT",
        "allow_to_sell": "true",
        "cost_price": "0.00",
        "id": "1700002963a44da1b542e0726b7bb758",
        "type": "NORMAL"
    },
    {
        "code": "293",
        "article_number": "6625110671AF0",
        "quantity": "2.00",
        "price": "5000.00",
        "name": "HOKA M Challenger ATR 6 | Сезон:Лето, Бренд:Hoka",
        "description": "В шестой версии Challenger ATR 6 укрепляет свою репутацию самых универсальных кроссовок. Как следует из названия, эти кроссовки-вездеходы бросают в",
        "alcoCodes": "[]",
        "is_excisable": "false",
        "is_age_limited": "false",
        "classification_code": "",
        "measure_name": "шт",
        "tax": "NO_VAT",
        "allow_to_sell": "true",
        "cost_price": "0.00",
        "id": "53c3bce66e434e4fa09556518c2fcb54",
        "type": "NORMAL"
    }
...

Поле json остатков	Формат	обьяснение
code	INTEGER	Уникальный id товара Код товара или модификации товара. До 25 символов.
article_number	STRING	Артикул товара.
quantity	DECIMAL	Доступный к продаже остаток товара или модификации товара. До семи знаков в целой и двух знаков в дробной части.
price	DECIMAL	Отпускная цена товара (услуги) или модификации товара. Формат: DECIMAL
name	STRING	Название товара (услуги) или модификации товара. Наименование мы показываем с характеристикой товара по выбранным показателям клиента. Например пользователь помечает что он хочет показать: далее мы берем эти харктеристики и ставим в наименование, например: HOKA M Challenger ATR 6 \| Бренд:Hoka, Размер:40, Цвет:Красный
description	STRING	Описание товара или модификации товара. Поле не поддерживет данные в формате HTML и XML, только строка. Ограничение по количеству символов: 150
alcoCodes	ARRAY	Передаем пустой массив JSON_ARRAY() Массив кодов алкогольной продукции ЕГАИС для алкогольных товаров и модификаций товаров. Длина одной строки (кода) строго 19 символов, так как алкоголь не разрешается продавать в интернет магазинах массив должен быть пустым.
is_excisable	BOOLEAN	Просто создаем false Указывает, является ли товар подакцизным: true – товар подакцизный; false – товар не подакцизный.
is_age_limited	BOOLEAN	Определяет, установлены ли возрастные ограничения для товара: true – товар с возрастными ограничениями; false – товар без возрастных ограничений.
classification_code	STRING	просто создаем пустую строку Это классификационный код товара.
measure_name	STRING	Единица измерения для товара или модификации товара: - шт или ед - г - кг - т - см - дм - м - кв. см - кв. дм - кв. м - мл - л - куб. м - кВт*ч - Гкал - сутки - час - мин - с - Кбайт - Мбайт - Гбайт - Тбайт Если это товар просто создаем строку "шт"
tax	STRING	Код ставки НДС для товара или модификации товара: NO_VAT – без НДС; VAT_0 – основная ставка 0%; VAT_10 – основная ставка 10%; VAT_10_110 – расчётная ставка 10%; VAT_18 – основная ставка 18%. С первого января 2019 года может содержать 20% VAT_18_118 – расчётная ставка 18%. С первого января 2019 года может содержать 20%. VAT_5 – основная ставка 5%; VAT_5_105 – расчётная ставка 5%; VAT_7 – основная ставка 7%; VAT_7_107 – расчётная ставка 7%; VAT_22 – основная ставка 22%; VAT_22_122 – расчётная ставка 22%.
allow_to_sell	BOOLEAN	Признак разрешения продажи. Указывает можно добавить товар в чек или нельзя:true - товар можно добавить в чек; false - товар нельзя добавить в чек.
cost_price	DECIMAL	Закупочная цена товара или модификации товара.
id	STRING	Идентификатор товара, услуги или модификации. Идентификатор уникален в рамках магазина. Максимальная длина идентификатора — 200 символов. Символы идентификатора должны удолетворять регулярному выражению A-a0-9-_. В качестве идентификаторов товаров вы можете использовать, например, uuid4, соответствующий RFC. На практике если у вас нет UUID можно переделать уникальный code в uuid
type	STRING	Настройки есть внутри товара во вкладке модули: также есть в списке товаров. Настройки - Массовое изменение "вида товара": 0-tovar, 100-service, 200-markbeer, 201-markbeerkegs, 202-excisealcoholstrong, 203-nonmarkbeer, 204-nonabeer, 300-lticket, 301-lwin, 401-Shoes, 402-Tobacco, 403-Tires, 404-Perfume, 405-Photographic goods, 406-Clothes and underwear, 407-Other smoking products, 408-Dairy products, 409-Water, 410-Fur products, 411-Bicycles, 412-Antiseptics and disinfectants, 413-Biologically active food supplements, 414-Juice products and soft drinks, 415-Wheelchairs, 416-Medical products, 417-VEGETABLE_OIL_MARKED, 418-CAVIAR_MARKED, 419-VETERINARY_MARKED, 420-PET_FOOD_MARKED, 421-MEDICINE_MARKED, 422-JEWELRY_MARKED или Товар = NORMAL Услуга = SERVICE Алкоголь: Маркированное пиво = BEER_MARKED Алкоголь: Маркированное пиво (кеги) = BEER_MARKED_KEG Алкоголь: Акцизный алкоголь (Крепкий) = ALCOHOL_MARKED Алкоголь: Немаркированный алкоголь (Пиво и слаб. алк.) = ALCOHOL_NOT_MARKED Алкоголь: Безалкогольное пиво = NOT_ALCOHOL_BEER_MARKED Лотерея: Лотерейный билет = LOTTERY_TICKET Лотерея: Выигрыш в лотерею = LOTTERY_PRIZE Маркированный товар: Обувь = SHOES_MARKED Маркированный товар: Табак = TOBACCO_MARKED Маркированный товар: Шины = TYRES_MARKED Маркированный товар: Духи = PERFUME_MARKED Маркированный товар: Фототовары = PHOTOS_MARKED Маркированный товар: Одежда и белье = LIGHT_INDUSTRY_MARKED Маркированный товар: Другая курительная продукция = TOBACCO_PRODUCTS_MARKED Маркированный товар: Молочная продукция = DAIRY_MARKED Маркированный товар: Вода = WATER_MARKED Маркированный товар: Меховые изделия = FUR_MARKED Маркированный товар: Велосипеды = BIKE_MARKED Маркированный товар: Антисептики и дезинфицирующие средства = ANTISEPTIC_MARKED Маркированный товар: Биологически активные добавки к пище = DIETARY_SUPPLEMENTS_MARKED Маркированный товар: Соковая продукция и безалкогольные напитки = JUICE_MARKED Маркированный товар: Кресла-коляски = WHEELCHAIRS_MARKED Маркированный товар: Медицинские изделия = MEDICAL_DEVICES_MARKED Маркированный товар: Растительные масла = VEGETABLE_OIL_MARKED Маркированный товар: Морепродукты (Икра) = CAVIAR_MARKED Маркированный товар: Ветеринарные препараты = VETERINARY_MARKED Маркированный товар: Корма для животных = PET_FOOD_MARKED P.S: Список всех возможных типов товаров — вы найдёте в разделе «Схемы товаров».

Требования

Endpoint должен принимать внешние HTTP/HTTPS-запросы

Ответ должен быть строго в формате JSON

Без дополнительных данных и сообщений

Проверка ключа обязательна для всех входящих запросов

Обязательное условие: Запрос от сервера и ответ модуля сохранить в логах CMS

Запрос на вычитание остатков при офлайн-продажах

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

Логика работы

На кассе происходит продажа товара

Приложение формирует данные о продаже

Отправляется запрос в модуль CMS

Модуль:находит товар по идентификатору

создает новый заказ (тем самым уменьшает количество остатка на сайте)

или:

уменьшает остаток товара

сохраняет изменения

‍

URL для обработки запроса

Пример (для CS-Cart):

url
/index.php?dispatch=postbicodo_receiptinv.sellextranull&addon=bicodo_receiptinv

Конкретный URL зависит от CMS, но должен быть доступен извне (по HTTPS).

Формат запроса

Запрос отправляется в формате JSON и содержит ключ доступа и массив данных от чека Эвотор:

Пример:

json
{
  "keyss": "12345678",
  "orderidznac": "[Position{uuid='ddf74ccb-dd03-4cd8-8f39-a664538fd02c', productUuid='e836d813fd184325932fca8edcdfb40e', productCode='466', productType=NORMAL, name='Пакет черный', measure='Measure(name=шт, precision=0, code=0)', taxNumber=NO_VAT, price=1, priceWithDiscountPosition=1, quantity=1, barcode='null', mark='null', alcoholByVolume=0, alcoholProductKindCode=0, tareVolume=0, extraKeys=[], subPositions=[], attributes={}, settlementMethod=ru.evotor.framework.receipt.position.SettlementMethod$FullSettlement@7f1eeaf, agentRequisites=null, importationData=null, excise=null, classificationCode=, preferentialMedicine=null, partial=null, isExcisable=false, marksCheckingInfo=null, isAgeLimited=null, isMarkSkipped=null, veterinaryAttribute=null, forceTaxNumber=null}]"
}

где:

keyss — ключ доступа (строка), логика работы keyss

orderidznac - массив значений от чека Эвотор. Пример кода получения массива

Нам по сути нужны 3 ключа, это:

productCode - основной идентификатор товара

name - наименование товара

quantity - количество проданного товара

‍

Для того чтобы найти товар на сайте:

по "productCode", если значение в нем пустое или отсутсвует в массиве, по "name".

Далее есть два пути:

Вариант 1: Предпочтительный способ, это создать новый заказ: тем самым за счёт стандартной логики CMS произойдет списание остатков. Важно: Заранее удостовериться чтобы этот заказ не передавался по событию продаж обратно на кассу или загрузке продаж

Напрямую уменьшить остаток товара на значение "quantity"

‍

Ответ модуля:

Результат	JSON массив
Успешно	{ "0": true }
Ошибка	{ "0": false }

‍

Требования

Endpoint должен принимать внешние HTTP/HTTPS-запросы

Ответ должен быть строго в формате JSON

Без дополнительных данных и сообщений

Проверка ключа обязательна для всех входящих запросов

Обязательное условие: Запрос от сервера и ответ модуля сохранить в логах CMS

‍

Загрузка продаж

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

Логика работы

Касса запрашивает у модуля CMS список заказов, которые необходимо фискализировать (пробить чек).

Касса по запросу или при событии онлайн продаж которую отправил модуль сайта отправляет запрос в модуль CMS

Модуль отвечает на запрос выводом актуальных заказов со статусом "Обработан"

‍

URL для обработки запроса

Пример (для CS-Cart):

url
/index.php?dispatch=postbicodo_receiptinv.sell&addon=bicodo_receiptinv

Конкретный URL зависит от CMS, но должен быть доступен извне (по HTTPS).

Формат запроса

Запрос отправляется в формате JSON и содержит ключ доступа и UNIX-временная метка:

Пример:

json
{
  "keyss": "12345678",
  "p_int2": "176770656"
}

где:

keyss — ключ доступа (строка), логика работы keyss

p_int2 - Это дата (UNIX-временная метка, в секундах). Зачем это нужно: Для того чтобы не грузить все заказы, которые уже не актульные с сервера поступает время с которой надо выгрузить данные. Модуль должен вывести заказы созданные после указанного времени со статусом "Обработан"

Без этого механизма:

при каждом запросе пришлось бы передавать все заказы

это:

увеличивает нагрузку

замедляет работу

может привести к повторной фискализации

Что дает p_int2

передаются только новые заказы

уменьшается нагрузка на сервер

исключается дублирование чеков

‍

Ответ модуля:

Модуль должен возвращать только заказы:

с нужным статусом («Обработан»)

соответствующие условию по времени (p_int2)

‍

json
{
    "0": {
        "order_id": "156",
        "total": "1.90",
        "subtotal": "2.00",
        "phone": "+79245915510",
        "email": "jt1988@yandex.ru",
        "timestamp": "1774434219",
        "company_address": "ул. Хабарова 5г, офис 6В",
        "company_website": "https://www.dev.runnr.ru",
        "products": [
            {
                "product_id": "180",
                "product_code": "Q01802L8VS",
                "type": "NORMAL",
                "product": "Пакет2",
                "uuid": "045117b0e0a14a24ab9765e79cbf113f",
                "price": "1.00",
                "amount": "1"
            },
            {
                "product_id": "466",
                "product_code": "Q01802L8VS1",
                "type": "NOT_ALCOHOL_BEER_MARKED",
                "product": "Пакет черный",
                "uuid": "e836d813fd184325932fca8edcdfb40e",
                "price": "1.00",
                "amount": "1"
            }
        ]
    }
}

Поле json продаж	Обьяснение
order_id	Уникальный номер заказа в CMS:
total	Итоговая сумма заказа с учетом скидок
subtotal	Сумма заказа без учета скидки
phone	Номер телефона клиента
email	Email клиента
timestamp	Время создания заказа: UNIX-временная метка, в секундах
company_address	Адрес компании
company_website	Адрес веб-сайта

Вложенный массив в поле "products" содержит данные товаров в заказе:

Поле json	Обьяснение
product_id	Уникальный id товара Код товара или модификации товара. До 25 символов. Смотри поле code в таблице "остатков"
product_code	Артикул товара Смотри поле article_number в таблице "остатков"
type	Вид товара Смотри поле type в таблице "остатков"
product	Наименование товара + характеристика Смотри поле name в таблице "остатков"
uuid	уникальный код uuid Смотри поле id в таблице "остатков"
price	Стоимость товара без учета скидки
amount	Количество заказанного товара

‍

После того как модуль вернул заказы в ответ на запрос кассы, необходимо изменить статус этих заказов:

Требование: Для всех успешно переданных заказов установить статус: «Обработан: Чек на обработке у кассы»

Логика:

Статус должен изменяться сразу после формирования ответа

Меняются только те заказы, которые были фактически переданы в ответе

Это предотвращает повторную отправку тех же заказов

Важно

Если статус не изменить:

заказ будет снова попадать в выборку

чек может быть сформирован повторно

‍

ЕСЛИ нет данных для показа, т.е заказов нет:

json
{
    "0": {
        "order_id": -1
    }
}

Требования

Endpoint должен принимать внешние HTTP/HTTPS-запросы

Ответ должен быть строго в формате JSON

Без дополнительных данных и сообщений

Проверка ключа обязательна для всех входящих запросов

Обязательное условие: Запрос от сервера и ответ модуля сохранить в логах CMS

Изменение статуса заказа на "Выполнен"

Данный запрос используется для изменения статуса заказа на «Выполнен» на стороне интернет-магазина после успешного формирования чека на кассе.

Логика работы

После успешного формирования чека (в рамках процесса «Загрузка продаж») статус заказа должен быть изменён на «Выполнен», чтобы отразить успешную обработку заказа после формирования чека на стороне кассы.

‍

URL для обработки запроса

Пример (для CS-Cart):

url
/index.php?dispatch=postbicodo_receiptinv.sellorderidznac&addon=bicodo_receiptinv

Конкретный URL зависит от CMS, но должен быть доступен извне (по HTTPS).

Формат запроса

Запрос отправляется в формате JSON и содержит ключ доступа и массив данных от чека Эвотор:

Пример:

json
{
  "keyss": "12345678",
  "orderidznac": "158"
}

где:

keyss — ключ доступа (строка), логика работы keyss

orderidznac - Номер заказа, смотри order_id в поле json продаж

Ответ модуля:

Результат	JSON массив
При успешном изменении статуса	{ "0": true }
При ошибке	{ "0": false }

Требования

Endpoint должен принимать внешние HTTP/HTTPS-запросы

Ответ должен быть строго в формате JSON

Без дополнительных данных и сообщений

Проверка ключа обязательна для всех входящих запросов

Обязательное условие: Запрос от сервера и ответ модуля сохранить в логах CMS

Изменение статуса заказа на "Обработан"

Данный запрос используется для изменения статуса заказа на «обработан» на стороне интернет-магазина после НЕуспешного формирования чека на кассе.

Логика работы

После НЕуспешного формирования чека (в рамках процесса «Загрузка продаж») статус заказа должен быть изменён обратно на «Обработан»:

Заказ был передан в кассу

Статус заказа установлен: «Обработан: Чек на обработке у кассы»

При формировании чека произошла ошибка

Модуль должен: изменить статус заказа на «Обработан»

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

‍

URL для обработки запроса

Пример (для CS-Cart):

url
/index.php?dispatch=postbicodo_receiptinv.sellorderidznacfalse&addon=bicodo_receiptinv

Конкретный URL зависит от CMS, но должен быть доступен извне (по HTTPS).

Формат запроса

Запрос отправляется в формате JSON и содержит ключ доступа и массив данных от чека Эвотор:

Пример:

json
{
  "keyss": "12345678",
  "orderidznac": "158"
}

где:

keyss — ключ доступа (строка), логика работы keyss

orderidznac - Номер заказа, смотри order_id в поле json продаж

Ответ модуля:

Результат	JSON массив
При успешном изменении статуса	{ "0": true }
При ошибке	{ "0": false }

Требования

Endpoint должен принимать внешние HTTP/HTTPS-запросы

Ответ должен быть строго в формате JSON

Без дополнительных данных и сообщений

Проверка ключа обязательна для всех входящих запросов

Обязательное условие: Запрос от сервера и ответ модуля сохранить в логах CMS

2. Запросы от модуля к серверу

‍

Событие онлайн продаж и передача чека в кассу

После успешного события продажи, когда заказ получает статус: "Обработан" нужно отправить уведомление в кассу

Уведомление необходимо для того, чтобы касса инициировала запрос: "Загрузка продаж" и получила новые заказы для формирования чеков.

‍

Условие

Уведомление отправляется только при: успешном изменении статуса заказа на «Обработан»

Важно

Уведомление не содержит сами данные заказа, оно лишь инициирует процесс запроса со стороны кассы

Получение данных происходит через отдельный запрос «Загрузка продаж»

‍

Запроса от модуля

Запрос выполняется на URL: https://automation.bicodo.ru/_import/evotor.php

Заголовки (Headers): Content-Type: application/json

Кодировка: UTF-8

Тип запроса: POST

‍

Примерное тело запроса

json
(
    [seckey] => hofewhio89fewrhuio89fgiefru7hgu9rfi8e90ewyfr0ll
    [keyss] => 12345678
    [domain] => domain.ru
    [status_from] => C
    [status_to] => P
)

Поле json	Обьяснение
seckey	Значение статичное: hofewhio89fewrhuio89fgiefru7hgu9rfi8e90ewyfr0ll Нужно для того чтобы выполнилась правильная функция
keyss	Ключ доступа
domain	домен сайта без http и https
status_from	Предыдущий статус заказа
status_to	Актуальный статус заказа

‍

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

array
array (
  'response_httpcode' => 202,
  'error' => '',
)

Обработка запроса считается успешной при выполнении следующих условий:

значение поля response_httpcode равно одному из:

200

202

204

поле error содержит пустую строку

‍

Обязательное условие: Ответ от сервера сохранить в логах CMS

Примеры кода

Код уникального значения в uuid:

php
str_replace('-', '', bicodo_receiptinv_idToUuid5($datad[$datad_k]['code'])); 


function bicodo_receiptinv_idToUuid5($originalId) { //id to uuid
    // Создаем хеш от ID
    $hash = md5($originalId);
    $hashBytes = hex2bin($hash);
    
    // Устанавливаем версию 4 и вариант
    $hashBytes[6] = chr(ord($hashBytes[6]) & 0x0F | 0x40); // версия 4
    $hashBytes[8] = chr(ord($hashBytes[8]) & 0x3F | 0x80); // вариант 2
    
    // Конвертируем обратно в hex и форматируем как UUID
    $hex = bin2hex($hashBytes);
    
    return sprintf('%08s-%04s-%04s-%04s-%012s',
        substr($hex, 0, 8),
        substr($hex, 8, 4),
        substr($hex, 12, 4),
        substr($hex, 16, 4),
        substr($hex, 20, 12)
    );
}

‍

Получение массива из строки чека Эвотор

php
function parseEvotorArray($string) {
    // Декодируем Unicode
    $string = json_decode('"' . str_replace('"', '\"', $string) . '"');
    
    $result = [];
    
    // Находим все объекты Position
    preg_match_all('/Position\{([^}]+)\}/', $string, $matches);
    
    foreach ($matches[1] as $posContent) {
        $position = [];
        
        // Используем preg_split с сохранением строк в кавычках
        $tokens = preg_split('/,\s*(?=[^=]+=)/', $posContent);
        
        foreach ($tokens as $token) {
            if (strpos($token, '=') === false) continue;
            
            list($key, $value) = explode('=', $token, 2);
            $key = trim($key);
            
            // Если значение в кавычках - сохраняем с пробелами
            if (preg_match("/^'(.*)'$/", trim($value), $m)) {
                $value = $m[1];
            } else {
                $value = trim($value);
            }
            
            // Преобразование типов
            if ($value === 'null') $value = null;
            elseif ($value === 'true') $value = true;
            elseif ($value === 'false') $value = false;
            elseif (is_numeric($value)) $value = (int)$value;
            elseif ($value === '[]') $value = [];
            
            $position[$key] = $value;
        }
        
        $result[] = $position;
    }
    
    return $result;
}

print_r(parseEvotorArray($string));

‍

Требования к документации

Разработчик обязан подготовить документацию по реализованному модулю.

Формат

Документация должна быть предоставлена в формате Markdown (.md)

Требования к содержанию

Документация должна включать:

описание установки модуля

описание настроек

описание всех endpoint (URL, формат запросов и ответов)

описание логики работы

описание форматов передаваемых данных (JSON)

описание возможных ошибок и их обработки

Требования к структуре

использовать заголовки

использовать код-блоки

разделять документацию на логические разделы

избегать неструктурированного текста

Назначение

Документация должна быть понятна:

разработчикам

техническим специалистам

‍

Составил ТЗ:

Дмитрий Ермолаев

Whatsapp/Telegram/KakaoTalk/MAX: +79245915510

E-mail: jt198893@gmail.com

‍

Ответственный:

‍

Срок:

Bearer