Интеграция калькулятора с сайтом через API: как настроить обмен каталогом, ценами и заявками

Интеграция калькулятора с сайтом через API — это схема, при которой калькулятор не держит собственный прайс, а получает товары, характеристики и цены из каталога и отправляет результат расчёта обратно: заявкой, конфигурацией или спецификацией. Работает такая связка только при одном источнике данных, явных версиях цен и предсказуемом поведении в момент сбоя.

Дальше разберём, из чего состоит этот обмен, где чаще всего рвётся и какие решения принимают до разработки, а не после первого инцидента.

Что именно связывает API между калькулятором и сайтом?

API в такой связке обслуживает три разных потока, и путать их нельзя. Первый — данные каталога: товары, параметры, цены, правила. Второй — результат расчёта: то, что клиент собрал на сайте, должно вернуться в систему в том же виде, в каком его считали. Третий — заявка: она уходит в учётную систему, где превращается в заказ, сделку или счёт.

У каждого потока свой ритм. Каталог меняется редко и пачками — например, при обновлении прайса. Расчёт происходит постоянно и требует быстрого ответа. Заявка — редкое, но самое чувствительное событие: потерянные данные здесь означают потерянную сделку, а не косметический дефект интерфейса.

Поэтому интеграцию проектируют не как «подключить эндпоинт», а как договор о данных: что считается истиной, кто инициатор обмена, что происходит при расхождении. Если этот договор не проговорён, разработка превращается в бесконечные правки, а бизнес — в споры о том, чья цена правильная.

Почему калькулятор не должен хранить свою копию прайса?

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

Типичная авария выглядит буднично. Коммерческий отдел поднял цену на одну линейку, каталог обновился, сайт обновился, а калькулятор остался на старой копии. Клиент считает по старой цене, менеджер видит новую, и разговор идёт уже не о продукте, а о том, кто ошибся. При этом формально виноватых нет: обе системы работали корректно, просто у каждой была своя правда.

Вторая проблема копии — стоимость поддержки. Каждое изменение номенклатуры нужно проводить дважды, каждую формулу — синхронизировать в двух местах, а тестировать оба контура. Чем больше продуктовая матрица, тем быстрее такая схема съедает ресурс команды.

Третий эффект — потеря управляемости. Когда цены живут в нескольких местах, никто не может ответить на простой вопрос: какая цена действовала в момент расчёта. Для коммерческого предложения, которое живёт неделю, это критично.

Какие сущности передаются по API?

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

Товар и его идентификатор

Первое, о чём договариваются, — стабильный идентификатор позиции. Артикул из прайса для этого подходит не всегда: поставщики меняют написание, добавляют префиксы, дублируют позиции под разными кодами. Внутренний идентификатор каталога переживает такие правки, а артикул остаётся атрибутом для людей и документов.

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

Характеристики и правила

Второй слой — параметры, по которым клиент выбирает: размеры, материалы, мощность, комплектация. Для калькулятора это входные данные формул, для конфигуратора — ещё и основание для проверки совместимости. Как это устроено на стороне продукта, описано в обзоре конфигуратора оборудования.

Правила совместимости лучше держать рядом с данными, а не в коде интерфейса. Когда правило «этот блок не ставится с этим приводом» зашито в фронтенд, каждое изменение требует релиза. Когда оно приходит из каталога как данные, коммерческий отдел меняет его сам.

Цена и условия её действия

Третий слой — цена. И здесь главная ошибка — считать цену одним числом. На практике цена — это набор: значение, валюта, база расчёта (с налогом или без), дата начала действия, источник. Число без этих атрибутов невозможно корректно сложить с другими числами, и именно на этом ломаются расчёты итогов.

Отдельно стоит договориться, что делать с наценками и скидками. Если калькулятор получает базовую цену, а правила наценки живут у него внутри, вы снова получили вторую копию логики. Если правила приходят из каталога, меняется только один источник.

Как устроена синхронизация цен?

Есть три рабочих режима, и выбор между ними — вопрос частоты изменений, а не моды на архитектуру.

Полная выгрузка

Каталог отдаёт весь набор данных целиком, калькулятор заменяет свою рабочую копию. Просто, предсказуемо, легко проверяется: после выгрузки можно сверить количество позиций и контрольные суммы. Минус — объём и время: на большой номенклатуре полная выгрузка становится тяжёлой операцией, которую нельзя делать часто.

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

Инкрементальные изменения

Каталог отдаёт только то, что изменилось с прошлого раза. Это дешевле по трафику и быстрее, но требует одного условия: у изменений должен быть признак, по которому их можно отобрать. Без него «инкремент» превращается в полную выгрузку с лишним названием.

Инкрементальный режим плохо переносит пропуски. Если один пакет изменений не дошёл, дальше система живёт с дырой, и заметить её можно только сверкой. Поэтому инкремент почти всегда дополняют периодической полной сверкой — например, раз в сутки или раз в неделю, в зависимости от темпа правок.

Событие вместо расписания

Самый точный режим — когда каталог сам сообщает об изменении. Тогда задержка между правкой цены и её появлением на сайте измеряется не часами, а минутами. Но у этого режима есть цена: нужна обработка повторов, потому что одно и то же событие может прийти дважды, и нужна защита от потери, потому что событие может не прийти вовсе.

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

Версия прайса и дата действия

Отдельный вопрос, который всплывает позже всех и стоит дороже всех: что делать с уже выпущенными коммерческими предложениями, когда цена изменилась.

Если калькулятор хранит только текущую цену, то открытое КП через день после обновления пересчитается по новой цене — и менеджер либо согласует её заново, либо отправит клиенту другую сумму, чем обсуждал. Поэтому в расчёте фиксируют, по какой версии прайса он сделан, и передают эту версию дальше — в заявку и в документ.

Дата действия решает смежную задачу: цена может быть объявлена заранее и вступать в силу с определённого числа. Если это не отражено в данных, сайт начнёт считать по новой цене раньше, чем она должна действовать.

Как результат расчёта возвращается на сайт и в учётную систему?

Результат — это не только итоговая сумма. В нём должны ехать состав конфигурации, выбранные параметры, применённая версия прайса и идентификатор расчёта. Без состава заявка превращается в «клиент хочет что-то за такую сумму», а менеджеру приходится переспрашивать.

Идентификатор расчёта нужен для сверки. Когда клиент звонит и говорит «у меня на сайте была другая цена», по нему можно поднять конкретный расчёт и увидеть, какие данные в нём участвовали. Без идентификатора разговор идёт по памяти.

Дальше — способ доставки. Опрос (сайт периодически спрашивает, нет ли новых заявок) проще в отладке, но даёт задержку и лишний трафик. Вебхук (система сама вызывает ваш адрес при событии) быстрее, но требует, чтобы адрес был доступен и умел отвечать на повторы. Частая ошибка — считать вебхук гарантированной доставкой: он не гарантирует ничего, пока на стороне получателя не реализована идемпотентность.

Идемпотентность — это когда повторная обработка одного и того же события не создаёт второй заказ. Достигается она просто: у события есть уникальный ключ, получатель его запоминает. Без этого один сбой сети превращается в дубль заявки, а менеджер — в человека, который вручную ищет совпадения.

Что делать, если API недоступен?

Считать, что API недоступен не будет, — самая распространённая ошибка в таких проектах. Он будет недоступен: на время обновления, из-за сетевого сбоя, из-за исчерпанного лимита. Вопрос не в том, случится ли это, а в том, что увидит клиент.

Первое решение — кэш. Последние полученные данные сохраняются и используются, пока свежие недоступны. Но у кэша обязана быть отметка актуальности: если данные получены вчера, интерфейс не должен делать вид, что цена сегодняшняя.

Второе — таймауты и повторные попытки. Запрос, который висит без ответа, хуже ошибки: он держит страницу и не даёт показать хоть что-то. Короткий таймаут и несколько повторов с нарастающей паузой закрывают большинство кратковременных сбоев.

Третье — предохранитель. Если сервис отвечает ошибками подряд, продолжать долбить его бессмысленно: это только удлиняет восстановление. После серии неудач обмен приостанавливается на короткое время, а затем проверяется пробным запросом.

Четвёртое и самое важное — честное поведение интерфейса. Есть три допустимых варианта: показать расчёт по кэшированным данным с пометкой, показать расчёт с оговоркой о необходимости подтверждения цены, либо честно сказать, что расчёт временно недоступен, и предложить оставить заявку. Недопустимый вариант один: молча показать устаревшую цену как актуальную. Именно он потом превращается в скандал на этапе согласования.

Отдельно продумывают заявку. Если учётная система недоступна, заявка не должна исчезать: она сохраняется локально с признаком «не передана» и уходит повторно. Клиент при этом видит подтверждение, а не ошибку — он свою часть работы выполнил.

Ключи доступа и лимиты: что закладывать сразу?

Ключ доступа — это не техническая мелочь, а граница ответственности. Практичные правила здесь простые и почти всегда нарушаются на первом этапе.

Отдельный ключ на каждую интеграцию. Общий ключ «на всё» удобен ровно до первого инцидента: когда нужно отозвать доступ у одного подрядчика, отзывать приходится у всех.

Минимум прав. Калькулятору, который только читает каталог, не нужен доступ на запись. Чем уже права, тем меньше последствия утечки.

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

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

Журнал обращений. Без логов невозможно ответить на вопрос «почему вчера цена была другой». Логировать стоит не только ошибки, но и факт выдачи данных: кто, что и когда запросил.

Как проверить интеграцию до запуска?

Проверка начинается не с «работает ли запрос», а с «что будет, если данные плохие». Хороший тестовый контур содержит копию каталога и позволяет воспроизвести реальные проблемы: позицию без цены, товар с двумя единицами измерения, правило, которое исключает все варианты.

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

Отдельно — сверка сумм. Один и тот же набор параметров прогоняют через калькулятор и через эталонный расчёт, а расхождение объясняют до запуска, а не после звонка клиента. Если объяснить не получается, значит, логика живёт в двух местах — и это надо исправлять в архитектуре, а не подкручивать числа.

И последнее: приёмка должна идти по сценариям, а не по факту «страница открывается». Список из десятка реальных клиентских путей — с обновлением цены посередине, с недоступным API, с повторной отправкой — даёт больше, чем неделя ручного тыканья.

С чего начать, если каталог пока в Excel?

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

Дальше — нормализация прайса и перенос данных в каталог. Этот шаг описан в обзоре параметрического каталога и data layer: импорт, единая структура характеристик и цен, выдача данных в интерфейсы по API. Ключевая идея проста — один источник, из которого читают все инструменты, вместо нескольких копий.

После этого калькулятор можно ставить на сайт как интерфейс к данным, а не как отдельную программу со своей правдой. Что такой инструмент умеет и куда встраивается, видно в разделе калькуляторы для сайта; если речь о подборе по параметрам с проверкой совместимости — в разделе конфигураторы.

Порядок работ и состав этапов удобнее смотреть в документации, а стоимость и формат старта — на странице тарифов. Если нужно обсудить конкретную схему обмена под ваш каталог, это делается на стартовой странице — с описанием того, откуда сейчас берутся цены и кто их правит.

Частые вопросы