Документация

Подключения, доставки и контроль качества

Подключение внешней базы

POST /api/v1/connections. Обязательны code, name, driver, host, database. Код содержит строчные латинские буквы, цифры и дефис. Дополнительно: port, username, password, description, options, is_active.

{
  "code":"store-db",
  "name":"База магазина",
  "driver":"pgsql",
  "host":"db.example.invalid",
  "port":5432,
  "database":"catalog",
  "username":"catalog_writer",
  "password":"REPLACE_ME",
  "options":{"schema":"public","sslmode":"require"}
}

Драйверы: pgsql, mysql, mongodb, s3. Для MongoDB доступны auth_source и replica_set в options. Для S3 database означает bucket, username: ключ доступа, password: секрет. В options задаются region, use_path_style, use_tls, base_prefix. Не вставляйте строку подключения целиком в host.

POST /connections/{id}/test проверяет сохранённое подключение. POST /connections/probe проверяет параметры до сохранения. Эти операции обращаются к указанному серверу. Секреты подключения обратно не выдаются; не считайте пустое поле пароля в интерфейсе отсутствием сохранённого секрета.

Доставка результата

Создание: POST /exports/{id}/deliveries.

{
  "name":"Обновление каталога",
  "target":"database",
  "connection_id":1,
  "table_name":"products",
  "write_mode":"upsert",
  "trigger":"after_run",
  "incremental":true,
  "is_active":true
}

Параметр	Значения
target	`file`: файл, `database`: база
write_mode	`upsert`: обновление по ключу, `append`: добавление, `replace`: очистка и замена
trigger	`after_run`, `manual`, `cron`
cron	Выражение обязательно при trigger=cron
timezone	Например `Europe/Moscow`
incremental	Отправлять изменения после последней успешной доставки

Для доставки cron находится в корне JSON, в отличие от preset.cron расписания сбора. replace удаляет прежнее содержимое таблицы: используйте только для согласованной с получателем полной замены.

GET /connections/{connection}/structure/{export} показывает предлагаемую структуру. POST на тот же путь применяет её и требует отдельного права. Сначала изучите предложение, особенно при работе с существующей таблицей.

POST /deliveries/{id}/run ставит доставку в очередь. Состояние проверяйте в истории выгрузки. /reset-cursor сбрасывает отметку: следующая доставка может повторить весь набор. Получатель должен корректно обрабатывать повторные записи.

Просмотр S3

GET /connections/{id}/storage/objects: объекты, /storage/search: поиск, /storage/download: скачивание. Требуется право чтения хранилища. Эти методы работают в рамках доступного подключения; они не дают произвольный доступ к файловой системе платформы.

Качество данных

GET /quality/vocabulary возвращает виды правил, действия и параметры. GET /quality/rules: правила; GET /quality/findings: обнаруженные проблемы. Для настройки правила конкретного сайта передайте site_id, kind, name, params и при необходимости action в POST /quality/rules.

{"site_id":1,"kind":"row_count_drop","name":"Падение количества товаров","params":{"drop_percent":30,"min_previous":100},"action":"warn","is_active":true}

Значения kind/action перед отправкой сверяйте со справочником вашей установки. Общие правила без site_id действуют на всю платформу; внешний API не позволяет их менять. Изменение своего правила: PATCH /quality/rules/{id}, удаление: DELETE. Правило нельзя переносить на другой сайт. Находка качества не означает, что данные автоматически исправлены: проверьте источник и алгоритм сбора.