cargo.run-api-docs

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

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

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

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

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

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

    необходимо:

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

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

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

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

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

  1. При создании или обновлении заявки в 1С сохранять:
    • дату обновления заявки в 1С;
    • последнюю известную дату обновления заявки в CARGO.RUN (updatedAt).

  2. В CARGO.RUN получать список заявок и их дату обновления updatedAt.

  3. Для выполненных заявок особый интерес представляют:

    • статус заявки: 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

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

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

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

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

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

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

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

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

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

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

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

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

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

Условия:

Итог:

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

Условия:

Итог:

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

Условия:

Итог:

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

Условия:

Итог:

4. Разрешение конфликтов обновления

В случае конфликта (заявка изменилась в обеих системах после последней синхронизации) возможны два режима:

4.1. Автоматический режим

В этом режиме задаётся приоритетная система:

Если приоритет у 1С:

Если приоритет у CARGO.RUN:

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

4.2. Ручной режим

В ручном режиме при конфликте необходимо:

  1. Зафиксировать факт конфликтного обновления.
  2. Показать пользователю обе версии данных (из CARGO.RUN и из 1С).
  3. Предоставить возможность выбора:
    • принять данные из CARGO.RUN,
    • или принять данные из 1С,
    • или выполнить комбинированное ручное редактирование.

Реализация ручного режима полностью зависит от интерфейса и бизнес-процессов клиента, но общая идея — явное отображение конфликтующих данных и явный выбор источника истины.

5. Резюме по примеру интеграции

В примере интеграции CARGO.RUN и 1С: