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

Введение

Этот документ описывает правила интеграции с системой 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. Перейти к обзору сценариев интеграции:
    Сценарии интеграции