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

Обзор API CARGO.RUN

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

1. Стиль и структура API

API CARGO.RUN построен на REST и использует:

  • протокол HTTPS,
  • методы HTTP (GET, POST),
  • формат JSON,
  • авторизацию через токен.

Все структуры данных, обязательные поля и параметры приведены в соответствующих разделах API Reference. Если для метода нужна модель запроса или ответа, она описывается рядом с методом.

2. Авторизация

Большинство методов требует токен:

Authorization: Bearer <token>

Полное описание авторизации приведено в разделе:
Auth API

3. Модели и данные

Структуры объектов описаны в разделах конкретных методов: таблицах полей, примерах JSON и перечнях допустимых значений.

Объекты Заявки и Заказы содержат поле updatedAt, но официальная инкрементальная синхронизация реализована только методом:

GET /api/bids/GetListForExternal

API-методы по справочникам не поддерживают фильтрацию по updatedAt.

4. Правила работы с API

4.1. Формат данных

API принимает и возвращает JSON.
Подробные правила работы с форматами описаны в:
Форматы данных

4.2. Даты и время

В документации даты обозначаются типом:

string (date-time)

Это формат ISO 8601.
Используйте формат ISO 8601 со смещением часового пояса. В интеграционных примерах обычно используется UTC (Z или +00:00).

4.3. Пагинация и фильтрация

Поддерживаются параметры OData:

  • $filter
  • $orderby
  • $top
  • $skip

Они применимы только к методам, в описании которых явно указаны соответствующие query-параметры.

4.4. Регистрозависимость URL

API CARGO.RUN регистронезависим.
Однако для единообразия во всей документации используется нижний регистр URL.

4.5. Ошибки

Универсальная JSON-структура ошибок не используется для всех методов.

API возвращает:

  • HTTP 4xx при бизнес‑ограничениях,
  • текстовое пояснение причины ошибки.

4.6. Используемые HTTP‑методы

API CARGO.RUN использует только два HTTP‑метода:

  • GET — получение данных
  • POST — создание, обновление, удаление, отмена, восстановление, смена статусов

Методы DELETE, PUT, PATCH не используются.

Примеры POST-команд:

POST /api/bids/delete
POST /api/bids/restore
POST /api/truckingbids/revert
POST /api/truckingbids/setstatus
POST /api/truckingbids/forcecomplete

4.7. Общий паттерн создания и обновления объектов

Для большинства сущностей используется единый подход:

Создание объекта

POST /api/.../apply
{
  "id": 0,
  ...
}

Обновление объекта

POST /api/.../apply
{
  "id": <фактический идентификатор объекта>,
  ...
}

5. Сценарии интеграции

Заявка создаётся в CARGO.RUN

CARGO.RUN → учетная система

Заявка создаётся во внешней системе

Учетная система → CARGO.RUN

Общая синхронизация справочников и заявок:
Синхронизация данных

6. Дополнительные материалы