Цифра ↔ 1С

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

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

Для ускорения разработки и большего понимания как устроен обмен в разделе «Примеры расширений» вы найдёте уже готовые расширения для разных версий 1С.

Как работает интеграция

Интеграция работает через REST API. Есть два принципа отправки данных:

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

Помимо заданий, 1С может инициировать отправку изменений в Цифру самостоятельно — без ожидания задания из очереди. Это используется для справочников и оперативных данных: при создании или редактировании элемента в 1С расширение сразу вызывает соответствующий метод API Цифры и передаёт изменения.

Благодаря этому данные в Цифре остаются актуальными в реальном времени, даже если Цифра не запрашивала их явно.

Принцип 3. Инициатор запросов — всегда 1С

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

Это упрощает сетевую настройку: достаточно, чтобы 1С имела исходящий доступ к серверу Цифры.

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

new
Создано
Задание в очереди, ожидает обработки 1С.
1С забирает check
work
В работе
1С забрала задание и выполняет его на своей стороне.
Результат changeTaskStatus
исход
done
Успех
Задание выполнено, данные приняты 1С.
failed
Ошибка
При выполнении произошла ошибка, в ответе — её описание.

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

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

Мониторинг и отладка

Просмотреть какие задания созданы для вашей 1С от Цифры, какие запросы были из 1С в Цифру, какие ответы были получены и другие данные, необходимые для отладки интеграции, вы можете на специальной странице мониторинга:

/get/{SecretKey}

Открыть страницу мониторинга

Вместо {SecretKey} подставьте ключ вашей интеграции из настроек в Цифре.

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

Задания на выгрузку справочников

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

getCompaniesКонтрагенты
getProductsПродукция
getSpecificationsСпецификации
getCarsТранспортные средства
getDriversВодители
getContractsДоговора
getInvoicesСчета

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

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

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
Зоны доставки
Наименование зоны

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

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

Пример связи продукции
  • В АСУ завода: М400Б В30W10П4F150
  • В 1С: БСТ М400БВ30W10П4F150 ГОСТ 7473-2010

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

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

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

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

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

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

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

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

Create
createApplication

Создание реализации (отгрузки).

По триггеру из настроек интеграции (см. вкладку «Настройки»)
Create
createOrder

Создание заказа целиком.

По триггеру из настроек интеграции (см. вкладку «Настройки»)
Create
createCompany

Создание контрагента.

Автоматически, если контрагент в заказе не имеет Guid.
Create
createContract

Создание договора.

Автоматически, если договор в заказе не имеет Guid.
Create
createCar

Создание транспортного средства.

Автоматически, если ТС в заказе не имеет Guid.

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

Export
getCompanies

Выгрузка справочника контрагентов.
Export
getProducts

Выгрузка справочника продукции.

Export
getSpecifications

Выгрузка спецификаций.

Export
getCars

Выгрузка справочника транспортных средств.

Export
getDrivers

Выгрузка справочника водителей.

Export
getContracts

Выгрузка справочника договоров.

Export
getInvoices

Выгрузка справочника счетов.

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

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

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

Отправка задания зависит от настройки «Когда создавать задание на реализацию» (см. вкладку «Настройки»).

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

Параметры интеграции

Ключ string
Ключ аутентификации. Генерируется автоматически при создании интеграции. Передаётся в каждом запросе от 1С.
Модули бетонных заводов array<int>
Список заводов (миксеров), для которых работает интеграция. Задания создаются только для отгрузок, привязанных к указанным заводам.
Способ добавления реализации По каждой отгрузке, без заказа С объединением в заказы
Режим группировки заданий при создании реализаций.
По каждой отгрузке, без заказа для каждой отгрузки — отдельное задание createApplication. Каждый рейс миксера — отдельная реализация в 1С.
С объединением в заказы одно задание createOrder на весь заказ целиком.
Когда создавать задание на реализацию По завершению заказа По завершению каждой отгрузки При любых изменениях
Условие, при котором создаётся задание на отправку в 1С.
По завершению заказа задание создаётся только когда весь заказ переходит в статус «Завершён». Самый консервативный вариант — данные уходят в 1С только по факту полного выполнения заказа.
По завершению каждой отгрузки задание создаётся при завершении каждой отдельной отгрузки (статус done). Данные уходят в 1С по мере выполнения каждого рейса.
При любых изменениях задание создаётся при любом изменении заказа или отгрузки (создание, изменение статуса, редактирование). Данные в 1С актуализируются в реальном времени.
С каким типом оплаты выгружать данные array
Фильтр по способу оплаты заказа. Задания создаются только для заказов с выбранными способами оплаты. Если не выбран ни один способ оплаты — задания не создаются.
Обязательные поля array
Дополнительные атрибуты, которые передаются в данных задания.
К какой компании привязана интеграция integer
Привязка интеграции к конкретной организации-продавцу.

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

Три характерных сценария, показывающих взаимодействие настроек «Способ добавления реализации» и «Когда создавать задание на реализацию».

Сценарий 1 · Поштучно по завершении
Способ добавления реализации: По каждой отгрузке, без заказа Когда создавать задание: По завершению каждой отгрузки

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

Сценарий 2 · Заказом по завершении
Способ добавления реализации: С объединением в заказы Когда создавать задание: По завершению заказа

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

Сценарий 3 · Поштучно в реальном времени
Способ добавления реализации: По каждой отгрузке, без заказа Когда создавать задание: При любых изменениях

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

См. также

Метод check
Проверка заданий
changeTaskStatus
Смена статуса задания
Просмотр данных из 1С
Как посмотреть переданные данные
Интеграция с 1С Бухгалтерия 8.3
Готовое решение
Объекты строительства
Справочник construction_object