GitHub - gulnaz-bakinova/n8n-automation-integrations-showcase: Production-ready Loyalty System middleware (Tilda ↔ iikoCard) built with n8n. Features: API Proxy layer, Idempotency, Global Error Handling, Custom JS Frontend, and SQL Analytics.
| Контекст |
Сеть кофеен (4 точки, Алматы), запуск D2C |
| Задача |
Внедрить систему лояльности iikoCard в интернет-магазин на Tilda |
| Роль |
Integration & Automation Engineer (Full cycle implementation: проектирование, разработка, внедрение) |
| Стек |
n8n (Railway), JS, REST API, Webhooks, Google Sheets as DB |
| Статус |
Production |
| Главный результат |
Реализована бесшовная синхронизация бонусов между сайтом и кассой (zero-touch processing) |
1. Проблема (Challenge)
- Нет омниканальности: Клиенты сайта не могли копить/тратить бонусы, что снижало удерживание.
- Ручной труд: Без интеграции менеджеру пришлось бы вручную переносить баллы в кассу (риск ошибок).
2. Решение (Solution)
Разработано Middleware на n8n, связывающее Tilda и iikoCard.
На фронтенд (Tilda) внедрен кастомный JS-скрипт, позволяющий клиенту видеть свой баланс и списывать баллы в корзине.
Обмен данными происходит в реальном времени через API-шлюз.
<aside>
3. Результат (Impact)
- 100% Zero-touch: За первые 2 месяца после запуска (soft-launch) система успешно обработала все онлайн-заказы без ручного вмешательства менеджеров.
- Процессинг лояльности: Автоматически рассчитано и начислено 5 600 бонусных баллов клиентам интернет-магазина.
- Замыкание цикла лояльности: Вернувшиеся клиенты успешно списали 1 500 баллов для частичной оплаты новых заказов (система корректно пересчитала остатки и чеки).
- Надежность: Исключены дубли транзакций (защита на уровне архитектуры). Система прошла боевую эксплуатацию – реальные транзакции, реальные клиенты, нулевые ошибки процессинга.
- Единый профиль: Клиент накапливает бонусы за покупку зерна онлайн и тратит их на кофе офлайн.
</aside>
4. Архитектура (Architecture)
| НАПРАВЛЕНИЯ |
ПЛАТФОРМЫ |
|
|
| Frontend |
Tilda + Custom JS — инъекция скриптов для проверки баланса и UI списания в корзине |
| Orchestrator |
n8n (Cloud-hosted on Railway) — вся бизнес-логика, роутинг, трансформации данных |
| Backend / System of Record |
iikoCard API — хранение балансов, транзакции |
| Database |
Google Sheets — журнал транзакций (logs), идемпотентность, аудит ошибок |
| Ops UI |
Telegram Bot — уведомления администраторов, интерфейс отмены заказов (Callback queries) |
| Notification Service |
WhatsApp (GreenAPI) — отправка статуса заказа и начисленных бонусов клиенту |
5. Реализованные функции (Core Functions)
- Проксирование баланса
- API Proxy layer (n8n). Сайт запрашивает баланс у n8n, n8n авторизуется в iiko и отдает "чистый" ответ (обрабатывая ошибки User not found как 0 баланс)
- Омниканальный процессинг
- Начисление: Расчет 5% от суммы (за вычетом бонусов)
- Списание: Валидация лимита кошелька и частичная оплата
- Управление возвратами (Refunds)
- Сложная логика отката транзакций через Telegram-бота (кнопка "Отмена заказа")
- Сценарии: "Вернуть списанное" или "Аннулировать начисленное" в зависимости от типа оплаты
<aside>
6. Надёжность и Эксплуатация (Reliability)
- Idempotency (Защита от дублей): Защита от дублей. Перед обработкой
order_id проверяется в базе (Google Sheets). Повторные вебхуки от Tilda игнорируются.
- Resilience (Отказоустойчивость): Политика Retry on Fail (3 попытки, экспоненциальная задержка) для всех HTTP-запросов к внешним API (iiko).
- Error Handling (Обработка ошибок): Глобальный Error Workflow. Перехватывает любые 4xx/5xx ошибки, пишет лог в БД и отправляет алерт с Debug-ссылкой в Telegram.
- Observability (Наблюдаемость): Структурированное логирование всех этапов (Request/Response) для дебага.
</aside>
7. Интеграции и Данные (Integrations Specs)
| Tilda |
Webhook (JSON POST). Триггер на событие Order Created |
| iikoCard API |
REST API |
- Auth: Dynamic Bearer Token (получение токена перед каждой сессией)
- Methods: customer/info (GET), wallet/chargeoff (POST), create_or_update (POST) |
| Google Sheets | OAuth2 Connection (безопасный доступ без шаринга паролей) |
| Telegram | Bot API (Webhook для кнопок, алерты) |
| WhatsApp | HTTP Request (POST). Отправка сообщений по номеру телефона заказчика о заказе и сумма начисленных бонусов |
8. Безопасность и конфиденциальность данных (Security)