cargo.run-api-docs

Введение

Этот документ описывает правила интеграции с системой CARGO.RUN Логистика через REST API.
API предназначен для обмена данными между CARGO.RUN и внешними учётными системами (1С, ERP, WMS, мобильными приложениями, внешними сервисами и т.д.).

Документация разделена на три большие части:

1. общие правила и форматы данных;
2. сценарии интеграции;
3. API Reference (справочник методов).

---

1. Назначение API CARGO.RUN

API предоставляет доступ к данным и функциям системы:

• создание и редактирование заявок и заказов,
• работа с маршрутами,
• синхронизация справочников (контрагенты, водители, техника, организации),
• управление статусами заявок, титулов и ЭТРН,
• получение событий и информации о ходе перевозок,
• работа с данными сотрудников, трекеров и мобильных клиентов.

API предназначено для систем:

• 1С и её конфигураций,
• собственных ERP клиентов,
• CRM,
• внешних логистических платформ,
• сервисов телематики,
• приложений мобильных водителей,
• корпоративных интеграционных решений.

---

2. Архитектура интеграции

Архитектурно API CARGO.RUN устроено как REST API:

• обмен данными осуществляется по HTTPS;
• запросы и ответы передаются в формате JSON UTF-8;
• каждый метод соответствует ресурсу или действию;
• авторизация выполняется через токен.

REST-подход обеспечивает простоту интеграции, предсказуемость и совместимость с клиентскими библиотеками.

---

3. Версионирование

API имеет стабильный контракт.
Обновления вносятся в соответствии с принципами:

• новые поля добавляются без нарушения обратной совместимости;
• изменение обязательности полей всегда оговаривается заранее;
• разрушительные изменения выносятся в отдельные версии API.

Версия API отражается в URL и документации.

---

4. Базовый URL API

Фактический адрес API предоставляется при подключении интеграции.
Обычно формат: https://app.cargorun.ru/api/

Примеры формирования URL:

• GET https://app.cargorun.ru/api/bids
• POST https://app.cargorun.ru/api/orders

---

5. Формат запросов и ответов

• Все запросы — JSON.
• Все ответы — JSON.
• Кодировка — UTF-8.
• При необходимости передавать вложенные структуры используются стандартные JSON-объекты и массивы.

Во всех примерах документации используется форматирование, совместимое с JSONLint.

---

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

Доступ к API выполняется через выдачу токена.
В интеграции используется схема: Authorization: Bearer

Токен выдаётся методом авторизации и имеет срок действия.
Обновление токена (refresh) выполняется через соответствующий метод API.

Все методы, взаимодействующие с данными клиента, требуют авторизации.

---

7. Ограничения и квоты

API может вводить ограничения:

• лимиты на количество запросов в единицу времени (rate limit),
• ограничения на размер запросов,
• требования к обязательным полям,
• набор допустимых статусов и переходов для сущностей.

Эти ограничения фиксируются по мере необходимости в описаниях методов.

---

8. Следующие шаги

Для дальнейшей работы рекомендуется:

1. Ознакомиться с форматами данных:
   Форматы данных

2. Изучить статусные модели:
   Статусы сущностей

3. Посмотреть минимальные требования к обязательным полям:
   Минимальные требования

4. Перейти к обзору сценариев интеграции:
   Сценарии интеграции