Перейти к содержанию

Для LLM и ИИ-агентов

Этот раздел предназначен для ИИ-ассистентов и автономных агентов, которые анализируют интеграцию, генерируют код или выполняют операции через API CARGO.RUN Логистика.

Машиночитаемые материалы

Используйте краткий индекс, если агент может открывать ссылки. Полный файл подходит для базы знаний, RAG-системы или среды без доступа к сайту.

Приоритет источников

Если описания расходятся, агент не должен угадывать контракт. Используйте такой порядок:

  1. описание конкретного метода в разделе API;
  2. общие форматы, статусы и минимальные требования;
  3. интеграционный сценарий;
  4. пример payload.

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

Правила выполнения операций

  1. Получите <baseUrl> и учётные данные из защищённой конфигурации. Не помещайте пароль, access token, refresh token и персональные данные в промпт, журнал или отчёт.
  2. Получите токен через GenerateToken, затем обновляйте его через RefreshToken. Не вызывайте GenerateToken перед каждым запросом.
  3. Перед созданием заявки сопоставьте справочники и проверьте все ...Id.
  4. Для новой заявки передайте id = 0; для обновления — фактический id CARGO.RUN.
  5. Сохраните связь локального первичного ключа с возвращённым id CARGO.RUN, а также значение updatedAt. externalId не уникален и не подходит как ключ обновления.
  6. После создания используйте возвращённый id для запуска, отмены или изменения заявки.
  7. Считайте операции создания, обновления, смены статуса и удаления изменяющими данные. Перед их выполнением агент должен показать целевой объект и получить разрешение, если такое разрешение не было явно дано в исходной задаче.
  8. После изменяющего запроса прочитайте объект повторно и проверьте результат.

Повторы и ошибки

Результат Действие агента
2xx Проверить тело ответа и сохранить идентификаторы/курсор синхронизации
400 Не повторять без изменений; разобрать текст или errorMessage, исправить payload
401 Обновить токен и повторить один раз
403 Остановиться и сообщить о нехватке прав
404 Проверить <baseUrl>, регистр пути и ID; не создавать замену автоматически
409 Повторно прочитать объект и разрешить конфликт с участием владельца данных
429, 5xx Ограниченные повторы с экспоненциальной задержкой и случайным сдвигом

Инкрементальная синхронизация

  • Для оперативного обмена используйте асинхронную очередь API 2.0 и подтверждайте обработанные версии через ReadConfirmation.
  • Вызывайте чтение API 2.0 чаще одного раза в час: текущее окно изменений намеренно ограничено одним часом, а несколько изменений объекта могут объединяться в последнее.
  • API 2.0 пока не гарантирует каждую смену статуса и удаление. Получайте заявки через GET /api/bids/GetListForExternal порциями по 50 записей для начальной загрузки и контрольной сверки.
  • Используйте фильтр по updatedAt и стабильную сортировку, поддерживаемую методом.
  • Не продвигайте сохранённую верхнюю границу синхронизации, пока не обработаны все страницы.
  • Делайте небольшое перекрытие временных окон и устраняйте дубликаты по id и updatedAt.
  • Обрабатывайте isDeleted: удалённая заявка также является изменением.
  • Периодически выполняйте контрольную сверку, а не полагайтесь только на последний курсор.

Подробный алгоритм: Синхронизация заявок API 2.0.

Минимальный контекст для агента

Перед генерацией или выполнением запроса передайте агенту:

  • целевой сценарий и допустимые изменяющие операции;
  • базовый URL среды без секретов;
  • описание конкретного метода;
  • таблицы полей и enum, используемых в запросе;
  • правила форматов и ошибок;
  • локальные соответствия внешних идентификаторов и ID CARGO.RUN.

Не передавайте агенту всю документацию, если достаточно одного метода и связанных моделей.