Сначала настройте линию в проекте службы и получите её идентификатор из каталога. API использует это подключение; адреса и пароли базы линии в теле запроса не передаются.

Все ID и номера в примерах условные. lineId в командах — поле lineId из списка линий, а не id записи. orderNumbers содержит номера заданий, а не их внутренние ID.

Выбрать операцию

Запрос Что передаёт Поддерживаемые базы
POST /api/v1/sync/orders/upload Параметры заданий на линию SQLite, PostgreSQL, Microsoft SQL Server для исходной и целевой БД
POST /api/v1/sync/results/download Результаты с линии в проект SQLite, PostgreSQL, Microsoft SQL Server для исходной и целевой БД
POST /api/v1/sync/staff Пользователей выбранной линии SQLite/PostgreSQL → PostgreSQL
POST /api/v1/sync/references Справочники без шрифтов PostgreSQL → PostgreSQL

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

Все четыре команды возвращают 202. Дождитесь конечного результата; HTTP-ответ о приёме не подтверждает запись в базу линии. Одновременно для одной линии принимается одна задача синхронизации.

Передать задания на линию

Команда передаёт параметры заданий. Она не передаёт коды маркировки и не закрывает задания в исходной базе. Для передачи кодов используйте сценарий обмена в GUI.

  1. Проверьте, что нужные задания открыты, не выполняются и назначены выбранной линии.
  2. Отправьте POST /api/v1/sync/orders/upload с lineId и непустым массивом orderNumbers.
  3. Прочитайте результат задачи.

Пример:

{"lineId": 7, "orderNumbers": [1001, 1002]}

Программа проверяет структуру целевой базы, занятость линии и повторяющиеся UUID. Уже имеющиеся задания пропускаются. В result проверьте requestedCount, skippedExistingCount, pendingUploadCount и uploadedCount.

sync_target_schema_upgrade_required означает, что базу линии нужно обновить отдельно. API не запускает диалог обновления структуры.

Загрузить результаты с линии

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

POST /api/v1/sync/results/download принимает lineId, непустой orderNumbers и необязательное replaceExisting, по умолчанию false:

{"lineId": 7, "orderNumbers": [1001], "replaceExisting": false}

Программа сопоставляет задания по OrderUUID, а не только по номеру. В проекте уже должно быть соответствующее задание. Задания, по которым нет результатов для переноса, пропускаются. Если результаты уже загружены, повтор с заменой требует явного replaceExisting=true.

В результате доступны downloadedOrderCount, skippedEmptyOrderCount, resultsCount, rejectsCount, boxesCount, palletsCount, boxCodesCount, а также lineId, requestedCount и replaceExisting. Сверьте итог с выбранными номерами. Затем прочитайте локальные счётчики задания.

Передать пользователей

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

POST /api/v1/sync/staff принимает только lineId:

{"lineId": 7}

Переносятся общие пользователи (LineID=0) и пользователи выбранной линии. Данные пользователей остальных линий в целевой базе сохраняются. Перед созданием задачи программа читает список пользователей из исходной базы и параметры подключения к целевой базе. Задача использует эти данные, даже если затем обновить проект.

Исходная база должна использовать SQLite или PostgreSQL, целевая — PostgreSQL. UUID пользователей должны быть заполнены и не повторяться. В целевой базе должна быть ровно одна запись выбранной линии. Линия должна быть свободна.

После успеха проверьте insertedCount, updatedCount, deletedCount и lineId. Пароли, значения полей пользователей и строки подключения в результат задачи не включаются.

Ошибка Что означает
sync_staff_invalid_source Проверьте пустые или повторяющиеся UUID пользователей в исходной базе
sync_staff_invalid_target, sync_staff_invalid_target_line Проверьте UUID пользователей и повторяющиеся записи выбранной линии в целевой базе
sync_line_busy Линия не свободна для обмена
sync_staff_admission_uncertain Перенос пользователей не начался, но в базе линия могла остаться помеченной как занятая. Проверьте её состояние
sync_staff_release_failed Данные могли сохраниться, а линия — остаться занятой. Проверьте данные и состояние линии до повтора
sync_staff_source_failed, sync_staff_failed Администратору нужно проверить подключение, права и журналы

Передать справочники

Команда заменяет справочники в целевой базе данными из исходной базы PostgreSQL. До запуска проверьте обе базы и сохраните резервную копию целевой. Шрифты не переносятся.

POST /api/v1/sync/references принимает lineId и необязательное includeFonts, которое должно быть false:

{"lineId": 7, "includeFonts": false}

Исходная и целевая базы PostgreSQL должны различаться. Для обоих подключений программа сравнивает пары значений: pg_catalog.pg_control_system().system_identifier и OID базы. Если пары совпадают, синхронизация не начинается. Учётной записи нужны права на чтение этих значений; без них продолжить нельзя. Программа начинает подготовку UUID только после проверки схемы исходной базы и подтверждения, что базы различаются.

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

В result возвращаются lineId, missingOrderCount и fontsUpdated=false. Запрос с includeFonts=true отклоняется с 501 sync_reference_fonts_not_supported.

При sync_reference_admission_uncertain, sync_reference_commit_uncertain или sync_reference_release_failed не повторяйте команду автоматически. Изменения могли сохраниться, а линия — остаться занятой. Перед повтором администратор должен проверить данные в целевой базе и состояние линии. Общей блокировки для остальных внешних программ у этой команды нет.