Быстрый старт

QueryX — это платформа для аналитики маркетплейсов с AI-помощником. Система автоматически собирает данные с Ozon, Wildberries и МойСклад, позволяет создавать дашборды с помощью AI и экспортировать их в Google Sheets.

Первые шаги

  1. 1

    Создайте проект

    Перейдите в раздел "Проекты" и создайте новый проект. Проект — это изолированное рабочее пространство для вашего бизнеса.

  2. 2

    Подключите маркетплейс

    В настройках проекта добавьте подключение к одному из маркетплейсов: Ozon, Wildberries или МойСклад. Вам понадобятся API-ключи для доступа к данным.

  3. 3

    Запустите синхронизацию

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

  4. 4

    Создайте дашборд

    Используйте AI-конструктор или создайте дашборд вручную. Настройте SQL-запросы для анализа ваших данных.

  5. 5

    Экспортируйте в Google Sheets

    Настройте автоматический экспорт дашборда в Google Sheets с периодическим обновлением.

Проекты

Проект в QueryX — это изолированное рабочее пространство со своей базой данных и настройками. Один проект может содержать несколько подключений к маркетплейсам.

Создание проекта

Для создания нового проекта:

  1. Перейдите в раздел "Проекты"
  2. Нажмите кнопку "Создать проект"
  3. Укажите название и описание проекта
  4. Настройте параметры синхронизации (опционально)
💡 Совет

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

Настройки проекта

В настройках проекта вы можете:

  • Включить/выключить автоматическую синхронизацию
  • Настроить уведомления об ошибках
  • Управлять доступом пользователей
  • Настроить расписание синхронизации

Подключение маркетплейсов

QueryX поддерживает интеграцию с основными маркетплейсами и системами учета. Для каждого маркетплейса требуется настройка API-ключей.

Wildberries

Получение API-ключа

  1. Войдите в личный кабинет продавца Wildberries
  2. Перейдите в раздел "Настройки" → "Доступ к API"
  3. Создайте новый токен доступа
  4. Скопируйте токен (он отображается только один раз)

Поддерживаемые данные

  • Заказы и продажи
  • Остатки на складах
  • Рекламные кампании и статистика
  • Акции и промо-коды
  • Отчеты по реализации (ОТЧ)
  • Воронка продаж (NM Report)

Ozon

Получение API-ключа

  1. Войдите в личный кабинет продавца Ozon
  2. Перейдите в "Настройки" → "API"
  3. Создайте новый ключ доступа
  4. Скопируйте Client ID и API Key
⚠️ Важно

API-ключи следует хранить в безопасности. Не передавайте их третьим лицам. В QueryX ключи хранятся в зашифрованном виде.

МойСклад

Для подключения МойСклад требуется:

  • Логин и пароль от аккаунта
  • Или токен доступа (рекомендуется)

Настройка синхронизации

После подключения маркетплейса настройте параметры синхронизации:

  • Частота обновления: от 5 минут до ежедневного
  • Типы данных: выберите, какие данные нужно синхронизировать
  • Период истории: за какой период загружать исторические данные

Создание дашбордов

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

Структура дашборда

Дашборд состоит из:

  • Строки: метрики (например, "Заказы руб.", "Выкупы шт.")
  • Столбцы: периоды времени (даты)
  • Ячейки: SQL-запросы или текст

Создание вручную

  1. Перейдите в "Дашборды" → "Создать дашборд"
  2. Выберите шаблон или создайте пустой
  3. Добавьте строки и столбцы
  4. Для каждой ячейки с данными создайте SQL-запрос
  5. Нажмите "Сохранить"

Пример SQL-запроса для ячейки

SELECT SUM(finished_price)/100.0 FROM wb_orders WHERE date::date = CURRENT_DATE - INTERVAL '1 days'
💡 Важно

Все SQL-запросы должны возвращать одно значение (скаляр). Используйте агрегатные функции: SUM, COUNT, AVG, MAX, MIN.

Типы ячеек

  • Текст: для заголовков строк и столбцов
  • Формула (SQL): для вычисляемых значений

AI-конструктор дашбордов Beta

AI-конструктор позволяет создавать дашборды за секунды, просто описав что нужно на русском языке.

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

  1. Нажмите кнопку "🤖 AI Помощник" в конструкторе дашбордов
  2. Опишите, какой дашборд вам нужен (например: "Покажи продажи за последние 7 дней по дням")
  3. AI сгенерирует структуру дашборда и SQL-запросы
  4. Система автоматически проверит SQL-запросы и исправит ошибки (до 3 попыток)
  5. Просмотрите результат и примените, если все корректно

Примеры запросов

"Покажи продажи за последние 7 дней по дням"
"Создай дашборд с метриками: заказы в рублях, выкупы в рублях, реклама в рублях за последние 14 дней"
"Покажи динамику продаж по дням за последний месяц"

Автоисправление SQL

Если AI сгенерировал SQL-запрос с ошибкой, система автоматически:

  1. Определит тип ошибки (синтаксис, тип данных, несуществующая таблица)
  2. Отправит ошибку обратно в AI для исправления
  3. Повторит попытку до 3 раз
  4. Покажет результат с индикацией успешных/неуспешных запросов
✅ Совет

Чем более детально вы опишете свои требования, тем точнее AI создаст дашборд. Укажите конкретные метрики, периоды и маркетплейсы.

SQL-запросы

QueryX использует PostgreSQL для хранения данных. Все SQL-запросы выполняются в контексте проекта (изолированная база данных).

Основные правила

  • Запросы должны начинаться с SELECT
  • Запрещены операции INSERT, UPDATE, DELETE, DROP, ALTER
  • Запрос должен возвращать одно значение (скаляр)
  • Используйте агрегатные функции для группировки данных

Типы данных в таблицах

Важно: типы полей nm_id

При работе с nm_id обратите внимание на типы данных:

Таблица Тип nm_id Пример JOIN
wb_products STRING (VARCHAR) s.nm_id::INTEGER = p.nm_id
wb_orders INTEGER o.nm_id = p.nm_id::INTEGER
wb_sales INTEGER s.nm_id = p.nm_id::INTEGER

Работа с датами

В таблицах используются разные типы для дат:

  • wb_orders.date — тип TIMESTAMP
  • wb_sales.date — тип DATE

Фильтрация по дате (TIMESTAMP)

SELECT SUM(finished_price)/100.0 FROM wb_orders WHERE date::date = CURRENT_DATE - INTERVAL '1 days'

Фильтрация по дате (DATE)

SELECT SUM(finished_price)/100.0 FROM wb_sales WHERE date = CURRENT_DATE - INTERVAL '1 days'

Примеры запросов

Сумма заказов за сегодня

SELECT COALESCE(SUM(finished_price)/100.0, 0) FROM wb_orders WHERE date::date = CURRENT_DATE

Средний чек за последние 7 дней

SELECT COALESCE(AVG(finished_price)/100.0, 0) FROM wb_orders WHERE date::date >= CURRENT_DATE - INTERVAL '7 days'

Сумма рекламы для конкретного товара

SELECT COALESCE(SUM(sum)/100.0, 0) FROM wb_advert_day_stat WHERE nm_id = 169318150 AND date >= CURRENT_DATE - INTERVAL '2 days'

JOIN с приведением типов

SELECT SUM(s.finished_price)/100.0 FROM wb_sales s JOIN wb_products p ON s.nm_id::INTEGER = p.nm_id::INTEGER WHERE s.date = CURRENT_DATE - INTERVAL '1 days'
⚠️ Важно

Всегда используйте COALESCE для обработки NULL значений. Это гарантирует, что в ячейке будет отображаться 0 вместо пустого значения.

Шаблоны дашбордов

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

Доступные шаблоны

  • Пустой шаблон: для создания дашборда с нуля
  • Продажи по дням: базовый шаблон для анализа продаж
  • Реклама и эффективность: анализ рекламных кампаний
  • Остатки и логистика: мониторинг складских остатков

Использование шаблона

  1. При создании дашборда выберите шаблон
  2. Шаблон будет применен к вашему дашборду
  3. Вы можете редактировать структуру и SQL-запросы
  4. Сохраните изменения

Интеграция с Google Sheets

QueryX позволяет автоматически экспортировать дашборды в Google Sheets с периодическим обновлением данных.

Настройка экспорта

  1. Перейдите в раздел "Google Sheets"
  2. Нажмите "Создать экспорт"
  3. Выберите шаблон дашборда для экспорта
  4. Укажите ID таблицы Google Sheets и название листа
  5. Настройте диапазон для записи данных
  6. Укажите частоту обновления (от 5 минут)
  7. Настройте сервисный аккаунт Google

Сервисный аккаунт Google

Создание сервисного аккаунта

  1. Перейдите в Google Cloud Console
  2. Создайте новый проект или выберите существующий
  3. Включите Google Sheets API
  4. Создайте сервисный аккаунт
  5. Скачайте JSON-файл с ключами
  6. Предоставьте доступ к таблице для сервисного аккаунта

Предоставление доступа к таблице

  1. Откройте Google Sheets таблицу
  2. Нажмите "Настройки доступа"
  3. Добавьте email сервисного аккаунта (например: new-351@analog-medium-415913.iam.gserviceaccount.com)
  4. Установите права "Редактор"

Частота обновления

Вы можете настроить автоматическое обновление данных в Google Sheets:

  • Каждые 5 минут: для критичных данных
  • Каждые 15 минут: стандартная частота
  • Каждые 30 минут: для аналитики
  • Каждый час: для отчетов
  • Ежедневно: для сводных отчетов
  • Вручную: обновление по кнопке

Формат данных

Данные экспортируются в следующем формате:

  • Первая строка — заголовки (даты)
  • Первый столбец — метрики (названия строк)
  • Остальные ячейки — значения из SQL-запросов
  • Пустые значения заменяются на 0

Ручное обновление

Вы можете в любой момент обновить данные в Google Sheets вручную, нажав кнопку "Обновить сейчас" в списке экспортов.

Настройка синхронизации

Синхронизация данных происходит асинхронно через очереди. Это позволяет обрабатывать большие объемы данных без блокировки интерфейса.

Типы синхронизации

Автоматическая синхронизация

Система автоматически запускает синхронизацию по расписанию:

  • Цены: обновление цен товаров
  • Остатки: синхронизация складских остатков
  • Заказы: загрузка новых заказов, продаж и возвратов
  • Реклама: обновление статистики рекламных кампаний
  • Акции: синхронизация промо-акций
  • Отчеты: загрузка отчетов по реализации и воронке продаж

Ручная синхронизация

Вы можете запустить синхронизацию вручную через интерфейс или командную строку:

php artisan sync:wb-orders --connection_id=1 --days=7

Лимиты API

Система автоматически учитывает лимиты API маркетплейсов:

  • Wildberries: различные лимиты для разных типов данных (от 1 до 600 запросов в минуту)
  • Ozon: лимиты согласно документации API

Логи синхронизации

Все операции синхронизации логируются. Вы можете просмотреть логи в разделе "Логи":

  • Статус выполнения (успешно/ошибка)
  • Тип данных
  • Время начала и окончания
  • Детали ошибок (если были)

API

QueryX предоставляет REST API для программного доступа к данным и управления проектами.

ℹ️ Информация

API находится в разработке. Полная документация будет доступна после релиза.

Аутентификация

API использует токены доступа для аутентификации. Токен можно получить в настройках профиля.

Основные endpoints

  • GET /api/projects — список проектов
  • GET /api/dashboards — список дашбордов
  • POST /api/dashboards — создание дашборда
  • GET /api/sync-logs — логи синхронизации

Часто задаваемые вопросы

Общие вопросы

Как часто обновляются данные?

Вы можете настроить частоту обновления от 5 минут до ежедневного. По умолчанию используется автоматическое расписание в зависимости от типа данных.

Сколько данных можно хранить?

Ограничений по объему данных нет. Каждый проект имеет изолированную базу данных PostgreSQL.

Безопасны ли мои данные?

Да. Все данные хранятся в изолированных базах данных. API-ключи шифруются. Система соответствует стандартам безопасности.

Дашборды

Сколько дашбордов можно создать?

Количество дашбордов не ограничено. Вы можете создавать столько дашбордов, сколько необходимо для вашего бизнеса.

Можно ли экспортировать дашборд в Excel?

Сейчас поддерживается только экспорт в Google Sheets. Экспорт в Excel планируется в будущих версиях.

Работает ли AI-конструктор на мобильных устройствах?

Да, AI-конструктор доступен через браузер на любых устройствах. Интерфейс адаптирован для мобильных экранов.

SQL-запросы

Можно ли использовать JOIN между таблицами?

Да, но важно учитывать типы данных. При JOIN таблиц с разными типами nm_id используйте приведение типов: s.nm_id::INTEGER = p.nm_id

Что делать, если SQL-запрос возвращает ошибку?

Система автоматически попытается исправить ошибку с помощью AI (до 3 попыток). Если ошибка не исправлена, проверьте синтаксис запроса и типы данных.

Google Sheets

Как часто обновляется Google Sheets?

Вы можете настроить частоту от 5 минут до ежедневного обновления. Также доступно ручное обновление по кнопке.

Можно ли экспортировать несколько дашбордов в одну таблицу?

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

Решение проблем

Синхронизация не работает

Проверьте API-ключи

  • Убедитесь, что API-ключи актуальны и не истекли
  • Проверьте права доступа ключа
  • Для Wildberries: убедитесь, что ключ имеет права на нужные типы данных

Проверьте логи

Перейдите в раздел "Логи" и найдите последние записи синхронизации. Ошибки будут отмечены статусом "FAILED" или "ERROR".

SQL-запрос не работает

Типичные ошибки

  • Ошибка типа данных: используйте приведение типов для nm_id
  • Ошибка с датами: используйте date::date для TIMESTAMP полей
  • Таблица не найдена: проверьте название таблицы и подключение к правильному проекту

Примеры исправлений

Было (ошибка):

SELECT * FROM wb_orders WHERE nm_id = '123456'

Стало (правильно):

SELECT * FROM wb_orders WHERE nm_id = 123456

Google Sheets не обновляется

  • Проверьте доступ сервисного аккаунта к таблице
  • Убедитесь, что указан правильный ID таблицы и название листа
  • Проверьте диапазон для записи данных
  • Попробуйте обновить вручную через кнопку "Обновить сейчас"

AI-конструктор не создает дашборд

  • Проверьте подключение к интернету
  • Убедитесь, что OpenAI API ключ настроен корректно
  • Попробуйте более простой запрос
  • Проверьте логи в консоли браузера (F12)