Skip to end of metadata
Go to start of metadata

Общие принципы

Основными предпосылками для интеграции являются:

  1. необходимость синхронизации данных внутренней системы учета предприятия (например, 1С) и данных по результатам проведенных торгов на портале ЛогистПро;
  2. автоматизация рутинных мероприятий по выставлению перевозок на торги и принятию решений, с целью минимизации вероятности человеческих ошибок и ограничения возможности злоупотреблений;
  3. создание системы "одного окна", когда сотрудники предприятия работают только со своей внутренней системой и не имеют необходимости дополнительно контролировать торги на портале.

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

  • 1С 8.3+ предоставляет все необходимые инструменты для совершения запросов и обработки данных (примеры базовых запросов можно изучить в публичном репозитории);
  • система публикации и опроса торгов может быть реализована средствами планировщика операционной системы и набора консольных скриптов на Bash, Windows CMD или Powershell (про особенности использования консольных утилит, можно прочитать в статье, а примеры для Powershell и CMD изучить в репозитории);
  • программный адаптер может быть написан на любом удобном языке программирования (умеющем совершать web-запросы по протоколу HTTP) самостоятельно или с использованием автоматически сгенерированных SDK библиотек (список доступных SDK можно увидеть в статье или изучить примеры для нескольких распространенных языков программирования).

Со стороны портала ЛогистПро участвуют: API (application programming interface - программный интерфейс приложения, доступный через сеть Интернет) и тестовые среды, предназначенные для отладки и проверки реализации алгоритмов интеграции.

Рекомендуемый алгоритм разработки и внедрения

  1. всю разработку и проверку алгоритмов, рекомендуется производить на тестовой среде https://testdev2.logistpro.su/ (все данные, необходимые для доступа к ней, находятся в статье);
  2. тестовая среда доступна как для запросов API, так и для интерактивного использования - все результаты работы механизмов интеграции можно проверять в интерфейсе вживую;
  3. для ознакомления с методами API без написания какого-либо кода, можно использовать интерактивную "песочницу", совмещенную с подробной документацией https://testdev2.logistpro.su/api/docs/ui/index;
  4. все вопросы по реализации, использованию API или уточнению алгоритмов, можно задавать в службу технической поддержки support@logistpro.su;
  5. после отладки алгоритмов на тестовой среде, необходимо:
    1. зарегистрировать личный кабинет компании на портале ЛогистПро (если личный кабинет ранее не был создан);
    2. запросить ключ доступа к API в службе технической поддержки support@logistpro.su;
    3. создать в личном кабинете уникального пользователя, которым будет осуществляться вход в систему со стороны приложения (мы не рекомендуем использовать для этих целей учетные записи реальных пользователей);
    4. изменить настройки своей системы интеграции, указав базовую точку входа https://lk.logistpro.su/api/v1/, полученный API Key и логин/пароль специального пользователя.
  6. при необходимости внешнего контроля своего сервиса интеграции, вы можете настроить регулярную проверку времени активности сервисной учетной записи в разделе Настройки интеграции.

Базовый алгоритм взаимодействия с сервисом

Рекомендуемая последовательность действий со стороны системы интеграции компании (в дальнейшем - "робот") для синхронизации данных между системами.

Для простоты, рассмотрим рекомендуемый алгоритм для случая регулярного запуска робота (например, раз в 5-10 минут) - работы сессиями.

Авторизация

Для авторизации в системе робот должен:

  1. передать на сервер учетные данные пользователя и API Key, вызовом метода POST /api/v1/account/login;
  2. из заголовков полученного ответа, сохранить значение cookie .AspNet.ApplicationCookie;
  3. передавать сохраненное значение cookie и API Key со всеми последующими вызовами.

Авторизацию можно принудительно производить один раз за сессию (период работы робота) или только в случае получения кода 401 в ответ на вызов любого метода.

Внимание!

Не рекомендуется производить авторизацию непосредственно перед вызовом каждого метода - это бесполезно и не дает гарантии успешной авторизации.

Публикация Запросов на перевозку

  1. робот находит новые сущности во внутренней системе (например, необработанные заказ-наряды в 1С);
  2. для каждой из них, создает запрос на перевозку, передавая в метод POST /api/v1/tender/create необходимые данные;
    1. если во внутренней системе не хранится часть данных, необходимых для создания (например, справочники юр.лиц, контрагентов, подрядчиков), то их можно предварительно получить вызовом GET /api/v1/tender/create;
    2. при выставлении на торги мы рекомендуем устанавливать следующие параметры:
      • длительность торгов в районе часа-полутора (параметры "StartDate" и "EndDate");
      • автоматический минимальный шаг торгов (параметр "MinStepReq": "Auto");
      • публично видимое лучшее предложение, чтобы перевозчики не торговались вслепую, а реально снижали стоимость (параметр "IsPublicBestOffer": true);
      • выставить стартовую цену торгов (параметр "InitCost").
        В противном случае перевозчики склонны завышать цену предложения по перевозке.
    3. в ответ получает идентификатор созданного запроса и сохраняет их для дальнейшей синхронизации во внутренней системе (например в том же документе 1С).

Опрос статусов торгов

После публикации новых запросов, робот может опросить текущее состояние ранее созданных торгов.
Это можно реализовать двумя способами:

  1. персональный опрос каждого запроса:
    1. найти во внутренней системе все документы, для которых ранее были созданы торги, но фактической перевозки еще не состоялось;
    2. для каждого из них, зная идентификатор торгов, запросить детальную информацию методом GET /api/v1/tender/{id} (предварительно подставив на место {id} идентификатор запроса).
  2. получение списка заведенных запросов по установленным критериям. Например:
    1. запросы, созданные в определенный день или период;
    2. запросы по перевозкам, исполняемым сегодня;
    3. запросы в определенном статусе (например, "Ожидает решения"=Proposed или "Просрочен"=Overdue);
    4. или любая комбинация этих критериев.

По полученному статусу торгов, роботу необходимо принять одно из следующих решений:

Завершение торгов принятием лучшего предложения

Если запрос находится в статусе "Просрочен" (параметр Status=Overdue) и у него есть действующее лучшее предложение (параметр BestProposal не пуст), то необходимо завершить торги принятием предложения.
Для этого необходимо:

  1. получить идентификатор лучшего предложения из параметра BestProposal.Id;
  2. подставить идентификатор в URL метода POST /api/v1/propose/{id}/confirm и выполнить его.

Продление неразыгранных торгов

Если запрос находится в статусе "Просрочен" (параметр Status=Overdue), но у него нет действующих предложений (параметр ProposalsCount=0 и BestProposal пуст), то робот может принять решение о продлении торгов с изменением стартовых данных для повышения привлекательности у перевозчиков.
Для этого необходимо:

  1. вызвать метод POST /api/v1/tender/{id}/start (предварительно подставив на место {id} идентификатор запроса);
  2. передавая в него следующие параметры:
    1. EndDate - новое время окончания торгов;
    2. InitCost - новая стартовая цена (обычно ставится выше предыдущей);
    3. Type=Hot - изменение типа торгов на "горящие" (первый же, сделавший предложение, забирает перевозку - используется для экстренного распределения).

Согласование завершенных торгов

После завершения торгов запрос переходит в статус "На согласовании"=Approving. После предоставления перевозчиком данных согласования запрос приобретает статус "Согласован"=Completed.
Данные согласования могут быть получены из детальной информации запроса и сохранены во внутреннюю систему для дальнейшей обработки (например, контроля очередности погрузки или оформления пропусков).
Для этого необходимо:

  1. вызвать метод GET /api/v1/tender/{id}/start (предварительно подставив на место {id} идентификатор запроса);
  2. получить данные из полей BestProposal.Driver и BestProposal.Vehicle.

Статус "Согласование просрочено"=ApproveOverdue означает, что перевозчик не успел предоставить данные согласования за установленный срок, что может являться основанием для срыва перевозки или перевыставления ее на новые торги.

Перевыставление отказных перевозок

Если запрос находился в статусе "Согласован"=Completed, но фактическая перевозка еще не была совершена, то возможен форс-мажорный вариант отказа со стороны исполнителя (поломка, ДТП и т.п.) - в этом случае, запрос переходит в статус "Отказ от выполнения"=DiscardedByOperator.

Если сама перевозка, при этом, еще актуальна, то можно перевыставить ее на торги, простым созданием нового запроса. В случае срочной необходимости, при создании можно указать параметр Type=Hot, что приведет к срочному распределению без торгов (первый же перевозчик, сделавший предложение, заберет такую перевозку).

При переборе запросов транспорта, с целью контроля ситуаций с отказами от выполнения согласованных перевозок, мы рекомендуем ограничиться перебором перевозок, запланированных на "сегодня" или на будущее дни.
В противном случае перебор может занимать длительное время и будет создавать излишнюю нагрузку на портал.

Расширенное взаимодействие с сервисом

Представленный выше алгоритм является базовым рекомендуемым для реализации типовых сценариев, но сервис так же предлагает много других возможностей для расширения взаимодействия.

Например:

  1. вы можете создавать отложенные (Status=Postponed) торги, указывая время начала торгов в будущем;
  2. управлять ходом торгов, вручную запуская отложенные или принудительно сокращая время ожидания запросов, уже получивших заинтересовавшее вас предложение;
  3. отменять торги и перевозки, а так же, фиксировать отказ от выполнения перевозчиком;
  4. напрямую назначать исполнителей для конкретных перевозок;
  5. получать и выводить во внутренней системе дополнительную информацию (например, количество просмотров/предложений, текущее лучше предложение, участников торгов и т.п.) в ходе торгов, пока статус равен Awaiting или Proposed;
  6. и т.п.

Полностью жизненный цикл запросов с привязкой к методам API можно изучить в соответствующей статье документации.