Надёжность интеграции¶

Курсор списка¶

Используйте сортировку:

$orderby=updatedAt,id

Сохраняйте пару (updatedAt, id) последней успешно обработанной заявки. Следующий запрос выполняйте с небольшим перекрытием по времени и удаляйте дубли по id.

Если GetList или ReadQuery не содержит непустого $filter, сервер ограничивает выборку заявками, изменёнными за последние 30 дней. Любой непустой $filter отменяет это окно, поэтому для синхронизации задавайте явную границу updatedAt.

Пересчёт points[].estimatedEnterDate не изменяет updatedAt. Если партнёру нужна актуальная ETA, одного курсора изменений недостаточно: перечитывайте интересующие заявки по ID или подходящему текущему окну.

Идемпотентность создания¶

Для синхронного Bids/Apply повторяйте запрос с тем же externalId.

Для асинхронной очереди дополнительно используйте уникальный Idempotency-Key. Повтор с тем же ключом в течение 24 часов возвращает существующую задачу.

Повторные запросы¶

Ситуация	Поведение
Сетевая ошибка или timeout	Повтор с увеличивающейся задержкой
`401`	Один раз обновить токен и повторить
`400`	Не повторять без исправления данных
`403`	Не повторять без изменения доступа
`404`	Проверить ID заявки и права доступа; без изменений не повторять
`429`	Уважать `Retry-After`, снизить частоту
`5xx`	Ограниченный повтор с jitter и exponential backoff

Защита от устаревших событий¶

дедуплицируйте webhook по eventId;
сравнивайте updatedAt заявки;
не рассчитывайте на порядок доставки;
считайте webhook сигналом перечитать объект, а не полным журналом переходов;
храните обработку события и изменение локальных данных атомарно либо используйте собственную очередь.

Удаление и прекращение доступа¶

При удалении или прекращении трансляции CARGO.RUN отправляет изменение прежней аудитории. Последующий Read может вернуть объектную ошибку о недоступности. Поле isDeleted=true в краткой модели означает, что партнёр должен прекратить отслеживание заявки.

{
  "id": 12345,
  "externalId": "ORDER-2471970",
  "status": "Canceled",
  "isDeleted": true,
  "createdAt": "2026-10-06T10:00:00+03:00",
  "updatedAt": "2026-10-08T14:30:00+03:00"
}

Совместимость¶

Клиент должен:

игнорировать неизвестные JSON-поля;
не завершать весь процесс из-за неизвестного enum;
сохранять исходное неизвестное значение для диагностики;
не полагаться на порядок полей JSON;
учитывать, что в ответы могут добавляться новые необязательные поля.

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