Пример интеграции CARGO.RUN и 1С¶

Этот пример описывает типовую схему интеграции между:

CARGO.RUN — система управления перевозками;
1С — учётная система Клиента.

Пример показывает, как:

настроить обмен справочниками и заявками;
организовать инкрементальную синхронизацию;
обрабатывать обновления заявок из CARGO.RUN в 1С;
решать конфликты изменений.

1. Общая архитектура интеграции¶

В 1С рекомендуется реализовать отдельный слой для интеграции со следующей логикой:

Создать дополнительную таблицу для интеграции, в которой хранить:
ссылки на элементы справочников (водитель, машина, прицеп, контрагент, организация);
ссылки на заявки;
идентификатор объекта в CARGO.RUN (id);
внешний атрибут externalId, если он нужен проекту, но не как уникальный ключ;
дату обновления объекта в CARGO.RUN (updatedAt);
дату обновления объекта в 1С.
При создании или обновлении:
элемента справочника,
заявки,

необходимо:

записывать запись в интеграционную таблицу;
при первом создании объекта в CARGO.RUN сохранять его id в 1С;
при последующих обновлениях — всегда передавать этот id в запросах к API CARGO.RUN.

externalId заявки не уникален. Первичный ключ интеграционной таблицы должен однозначно связывать локальный объект с id CARGO.RUN.

Периодически (например, раз в 15 минут):
выбирать из интеграционной таблицы все элементы справочников и заявки, созданные или изменённые за этот период;
отправлять их в CARGO.RUN через соответствующие методы (/api/driver/apply, /api/car/apply, /api/trailer/apply, /api/truckingbids/apply и т.д.).
В 1С у каждого элемента справочника и заявки рекомендуется хранить две даты:
«Дата обновления в CARGO.RUN»;
«Дата обновления в 1С».

Эти даты используются для анализа изменений и разрешения конфликтов.

2. Обновление данных заявок из CARGO.RUN в 1С¶

Если данные заявки могут изменяться в CARGO.RUN (например, фактические времена въезда/выезда, пробег, факт выполнения), 1С должна получать оперативные изменения через API 2.0 и периодически выполнять контрольную выборку GetListForExternal. Очередь API 2.0 не гарантирует каждую смену статуса и удаление. См. Синхронизация заявок API 2.0.

2.1. Основные шаги¶

При создании или обновлении заявки в 1С сохранять:
дату обновления заявки в 1С;
последнюю известную дату обновления заявки в CARGO.RUN (updatedAt).
В CARGO.RUN получать список заявок и их дату обновления updatedAt.
Для выполненных заявок особый интерес представляют:
статус заявки: status = "Done";
фактический километраж: factMileage;
по точкам загрузки/выгрузки:
- дата въезда в геозону: bidPoints -> autoEnteredAt;
- дата выезда из геозоны: bidPoints -> autoLeavedAt.

2.2. Пример запроса по выполненным заявкам¶

Пример OData-запроса (с фильтрацией по статусу и дате обновления):

GET /api/bids/GetListForExternal
  ?$filter=Status eq 'Done'
           and updatedAt gt 2019-11-20T06:00:00Z
  &$orderby=updatedAt,id
  &$top=50
  &$skip=0

После получения данных:

если дата обновления заявки в CARGO.RUN (updatedAt) более поздняя, чем дата обновления заявки в 1С — необходимо обновить данные заявки в 1С.

2.3. Пользовательские поля (extendedProperties)¶

При получении данных по заявке пользовательские поля передаются в массиве extendedProperties:

"extendedProperties": [
  {
    "propertyName": "Due_date",
    "value": "12"
  }
]

propertyName — имя пользовательского поля;
value — значение, заданное пользователем.

2.4. Пользовательские справочники (typeOptions)¶

Пользовательские справочники заявки описываются в массиве typeOptions:

"typeOptions": [
  {
    "id": 3795270,
    "entityOptionId": 3794317
  }
]

id — идентификатор справочника в организации клиента;
entityOptionId — идентификатор справочника в CARGO.RUN.

3. Варианты обновления данных заявки¶

При обновлении данных по заявке из CARGO.RUN в 1С возможны четыре базовые ситуации:

Заявка не изменилась в CARGO.RUN, не изменилась в 1С.
Заявка не изменилась в CARGO.RUN, изменилась в 1С.
Заявка изменилась в CARGO.RUN, не изменилась в 1С.
Заявка изменилась и в CARGO.RUN, и в 1С.

Для анализа используются три даты:

дата обновления заявки в CARGO.RUN;
дата обновления заявки в 1С;
дата последней синхронизации.

Ниже рассмотрены все варианты.

3.1. Заявка не изменилась в CARGO.RUN, не изменилась в 1С¶

Условия:

Дата последней синхронизации > Дата обновления заявки в CARGO.RUN.
Дата последней синхронизации > Дата обновления заявки в 1С.

Итог:

Обновление данных не требуется.

3.2. Заявка не изменилась в CARGO.RUN, изменилась в 1С¶

Условия:

дата последней синхронизации не меньше updatedAt заявки CARGO.RUN;
дата изменения заявки в 1С больше даты последней синхронизации.

Итог:

если 1С является владельцем изменённых полей, отправить изменения в CARGO.RUN;
перечитать заявку и сохранить новое updatedAt;
помнить, что Apply полностью перезаписывает заявку: перечитать объект, объединить изменения и не отправлять устаревшие значения полей, владельцем которых является CARGO.RUN.

3.3. Заявка изменилась в CARGO.RUN, не изменилась в 1С¶

Условия:

updatedAt заявки CARGO.RUN больше даты последней синхронизации;
дата изменения заявки в 1С не больше даты последней синхронизации.

Итог:

обновить запись 1С данными CARGO.RUN;
сохранить полученное updatedAt и время успешной синхронизации.

3.4. Заявка изменилась и в CARGO.RUN, и в 1С¶

Условия:

updatedAt заявки CARGO.RUN больше даты последней синхронизации;
дата изменения заявки в 1С больше даты последней синхронизации.

Это конфликт. Не выбирайте победителя только по более позднему времени: часы систем могут различаться, а системы могут владеть разными полями.

Рекомендуемый порядок:

Разделить поля по владельцу. Например, 1С может владеть номером первичного документа и данными оплаты, а CARGO.RUN — оперативным статусом, фактическими событиями и назначенной техникой. Конкретную матрицу утверждают до запуска.
Автоматически объединять только изменения в непересекающихся группах полей.
Если одно поле изменено с обеих сторон, создать запись конфликта и передать её ответственному сотруднику; не выполнять Apply автоматически.
После разрешения перечитать заявку, сохранить итоговое updatedAt и зафиксировать время успешной синхронизации.

3.5. Обязательная матрица владельцев данных¶

До внедрения двусторонней синхронизации зафиксируйте для каждой группы полей:

Группа	Владелец	Допустимое направление	Правило конфликта
Статус исполнения	CARGO.RUN	CARGO.RUN → 1С	Не перезаписывать из 1С
Фактические события точек	CARGO.RUN	CARGO.RUN → 1С	Не перезаписывать из 1С
Данные оплаты	Утверждается проектом	Одно направление	Ручное разрешение при расхождении
Пользовательские поля	Для каждого поля отдельно	По утверждённой схеме	По владельцу поля

Таблица выше — безопасный шаблон, а не универсальное распределение ответственности. Добавьте в неё все поля, которые интеграция разрешает изменять.