Двусторонняя интеграция

Полное описание механизма двустороннего обмена данными между 1С и системой Цифра.

Если у вас Бухгалтерия 8.3, вы можете воспользоваться готовой интеграцией с 1С Бухгалтерия 8.3

1. Архитектура интеграции

Интеграция реализована как микросервис, который принимает и отдаёт данные через REST API. Основной принцип — система заданий (task queue).

Как это работает:

Когда в Цифре происходит событие (создан заказ, изменилась отгрузка и т.д. в зависимости от настройки) — система создаёт задание в очереди
1С со своей стороны регулярно опрашивает сервер Цифры (рекомендуется 1 раз в минуту), забирая новые задания методом check
1С обрабатывает задание и отправляет результат методом changeTaskStatus

Жизненный цикл задания

new → work → done / failed

new     — задание создано, ожидает обработки
work    — 1С забрала задание и обрабатывает
done    — задание выполнено успешно
failed  — ошибка

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

При создании интеграции в Цифре генерируется уникальный SecretKey. Он передаётся в каждом запросе от 1С как параметр. По нему система идентифицирует, от какого аккаунта и какой интеграции пришёл запрос.

2. Выгрузка данных из 1С в Цифру

Данные из 1С в Цифру поступают двумя способами:

2.1. Задания на выгрузку справочников (get-задания)

При первом подключении интеграции Цифра автоматически создаёт задания на получение всех справочников:

getCompanies — контрагенты
getProducts — продукция
getSpecifications — спецификации
getCars — транспортные средства
getDrivers — водители
getContracts — договора
getInvoices — счета

1С получает эти задания через check и должна выгрузить полный справочник по каждому типу.

2.2. Триггерные отправки при изменении сущностей

Помимо первоначальной загрузки, необходимо настроить автоматическую отправку данных из 1С при создании или изменении элементов в справочниках. Это нужно, чтобы данные в Цифре всегда были актуальными.

Настройте выгрузку по событиям создания / изменения в следующих справочниках:

Справочник	Метод API	Описание
Контрагенты	`POST /api/company/create`	Наименование, ИНН, менеджеры, адреса
Продукция	`POST /api/product/create`	Номенклатура, характеристики
Транспортные средства	`POST /api/car/create`	Госномер, марка, объём
Водители	`POST /api/driver/create`	ФИО водителя
Договора	`POST /api/contract/create`	Номер, дата, контрагент
Счета	`POST /api/invoice/create`	Номер, дата, контрагент
Зоны доставки	`POST /api/delivery_zone/create`	Наименование зоны

Важно: Без триггерных отправок интеграция будет работать только с теми данными, которые были загружены в момент первого подключения. Новые контрагенты, продукция и т.д., созданные в 1С после подключения, не попадут в Цифру автоматически.

2.3. Связь справочников (Guid)

В разделе справочников в Цифре пользователь может настроить связь между тем, как называется сущность в АСУ завода и в 1С.

Пример связи продукции:

В АСУ завода: М400Б В30W10П4F150
В 1С: БСТ М400БВ30W10П4F150 ГОСТ 7473-2010

Если связь установлена, то в данных, отправляемых в 1С, будет заполнен параметр Guid (идентификатор сущности в 1С) и наименование, соответствующее названию в 1С. Связи работают для:

Продукции
Контрагентов
Транспортных средств
Договоров
Счетов

3. Передача данных из Цифры в 1С

Данные из Цифры в 1С передаются через систему заданий. 1С опрашивает сервер и получает задания, которые нужно выполнить.

3.1. Порядок выдачи заданий

При вызове check задания выдаются в определённой последовательности:

Сначала: задания на получение данных из 1С (getCompanies, getProducts и т.д.)
Затем: задания на создание зависимых сущностей в 1С
- Если контрагент, участвующий в заказе, не имеет Guid в 1С — сначала придёт createCompany
- Аналогично для договоров (createContract) и ТС (createCar)
После: задания на создание реализаций или заказов (createApplication / createOrder)

Система автоматически проверяет зависимости. Если заказ содержит нового контрагента, которого ещё нет в 1С, — сначала будет создано задание createCompany, и только после его выполнения будет доступен заказ.

3.2. Типы заданий

Создание сущностей в 1С:

Задание	Описание	Когда создаётся
`createApplication`	Создание реализации (отгрузки)	По триггеру из настроек интеграции (см. раздел 4)
`createOrder`	Создание заказа целиком	По триггеру из настроек интеграции (см. раздел 4)
`createCompany`	Создание контрагента	Автоматически, если контрагент в заказе не имеет Guid
`createContract`	Создание договора	Автоматически, если договор в заказе не имеет Guid
`createCar`	Создание транспортного средства	Автоматически, если ТС в заказе не имеет Guid

Выгрузка справочников из 1С:

Задание	Описание
`getCompanies`	Выгрузка справочника контрагентов
`getProducts`	Выгрузка справочника продукции
`getSpecifications`	Выгрузка спецификаций
`getCars`	Выгрузка справочника транспортных средств
`getDrivers`	Выгрузка справочника водителей
`getContracts`	Выгрузка справочника договоров
`getInvoices`	Выгрузка справочника счетов

3.3. Триггеры создания заданий в Цифре

Задания createApplication и createOrder создаются автоматически на основе событий в системе Цифра:

Создание отгрузки (MixOrder) — при создании подтверждённой отгрузки
Изменение статуса отгрузки — при изменении статуса, подтверждения или данных отгрузки
Создание заказа (MixOrderGroup) — при создании заказа
Изменение заказа — при изменении статуса или при изменении данных заказа

Отправка задания зависит от настройки actionTrigger (см. раздел 4).

4. Настройки интеграции

Настройки задаются в Цифре: Настройки → Интеграции → 1С. При создании интеграции генерируется SecretKey и задаются следующие параметры:

Параметр	Значения	Описание
`secretKey`	Строка	Ключ аутентификации. Генерируется автоматически при создании интеграции. Передаётся в каждом запросе от 1С.
`mixIds`	Массив ID заводов	Список заводов (миксеров), для которых работает интеграция. Задания создаются только для отгрузок, привязанных к указанным заводам.
`mode`	`by_one` — поштучно `by_order` — заказом	by_one — для каждой отгрузки создаётся отдельное задание `createApplication`. Каждый рейс миксера — отдельная реализация в 1С. by_order — создаётся одно задание `createOrder` на весь заказ целиком.
`actionTrigger`	`orderCompletion` `applicationCompletion` `anyChanges`	orderCompletion — задание создаётся только когда весь заказ переходит в статус «Завершён». Самый консервативный вариант — данные уходят в 1С только по факту полного выполнения заказа. applicationCompletion — задание создаётся при завершении каждой отдельной отгрузки (статус `done`). Данные уходят в 1С по мере выполнения каждого рейса. anyChanges — задание создаётся при любом изменении заказа или отгрузки (создание, изменение статуса, редактирование). Данные в 1С актуализируются в реальном времени.
`paymentMethods`	Массив способов оплаты	Фильтр по способу оплаты заказа. Задания создаются только для заказов с указанными способами оплаты. Если массив пуст — задания не создаются.
`attributes`	Массив атрибутов	Дополнительные атрибуты, которые передаются в данных задания.
`companyId`	ID организации	Привязка интеграции к конкретной организации-продавцу.

Пример: как настройки влияют на создание заданий

Сценарий 1: mode: by_one, actionTrigger: applicationCompletion

Заказ на 5 миксеров. Каждый раз, когда отгрузка переходит в статус done, в очередь попадает отдельное задание createApplication с данными по этой конкретной отгрузке.

Сценарий 2: mode: by_order, actionTrigger: orderCompletion

Заказ на 5 миксеров. Задание createOrder создаётся один раз — когда весь заказ получает статус «Завершён». В задании будут данные обо всех отгрузках заказа.

Сценарий 3: mode: by_one, actionTrigger: anyChanges

При любом изменении заказа или создании/изменении отгрузки — создаётся задание createApplication для каждой подтверждённой отгрузки. Данные в 1С актуальны в реальном времени, но заданий будет много.

5. Мониторинг

Состояние интеграции можно отслеживать:

В Цифре: Настройки → Интеграции → 1С → карточка интеграции. Показывает последнюю активность, список последних запросов и заданий.
В микросервисе: страница /get/{SecretKey} — отображает статистику, активные задания, последние запросы и логи.