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

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

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

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

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

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

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

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

необходимо:

записывать запись в интеграционную таблицу;
при первом создании объекта в CARGO.RUN сохранять его id в 1С;
при последующих обновлениях — всегда передавать этот id в запросах к API 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С должна периодически запрашивать обновления.

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
  &$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С.

Итог:

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