ModernERP Logo ModernERP Pro
+7 952 493 39 71

Интеграция по API

Как подключать внешние системы (1С, CRM, оборудование) через открытый REST API ModernERP Pro. Обмен данными в реальном времени.

Зачем нужен API

API (Application Programming Interface) ModernERP Pro позволяет интегрировать систему с внешними приложениями и устройствами. Это даёт возможность:

  • Обмениваться данными с 1С — передавать заказы, отгрузки, выпуск продукции, ФОТ, справочники.
  • Синхронизировать заказы с CRM — автоматически создавать заказы в ModernERP Pro при поступлении новых заявок из CRM.
  • Подключать производственное оборудование (IIoT) — получать телеметрию со станков, автоматически фиксировать выработку и простои.
  • Выгружать данные в BI-системы — для построения кастомных дашбордов и отчётов.
  • Автоматизировать рутинные операции — массовое создание заказов, обновление остатков, импорт справочников.

API построен по принципам REST, использует JSON и защищён аутентификацией по токену. Все эндпоинты задокументированы в интерактивной спецификации Swagger (доступна по адресу /api/doc после авторизации).

ℹ️ Текущая версия API: v1 (стабильная). Изменения обратно совместимы в пределах мажорной версии.

Архитектура API

Базовый URL

Все запросы отправляются на адрес вашего сервера ModernERP Pro:

  • https://ваш-сервер.ru/api/v1/ — для защищённых эндпоинтов.

Аутентификация

Для доступа к API требуется API-токен, который генерируется в личном кабинете пользователя с правами администратора.

  • Токен передаётся в заголовке Authorization: Bearer <ваш-токен>.
  • Токен можно аннулировать и перегенерировать в любой момент.

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

  • Запросы и ответы — JSON.
  • Кодировка — UTF-8.
  • Даты и время — в формате ISO 8601 (YYYY-MM-DDTHH:mm:ssZ).

Ошибки

При ошибках API возвращает стандартные HTTP-коды:

  • 200 — успешный запрос.
  • 400 — неверные параметры запроса.
  • 401 — неверный или отсутствующий токен.
  • 403 — недостаточно прав для выполнения операции.
  • 404 — ресурс не найден.
  • 422 — ошибка валидации данных.
  • 500 — внутренняя ошибка сервера.

В теле ответа всегда присутствует поле status (success или error) и, в случае ошибки, поле message с описанием.

Основные группы эндпоинтов

API ModernERP Pro разделён на логические группы для удобства работы:

📦 Товары (Products)

GET /products — список товаров.

POST /products — создание нового товара.

GET /products/{id} — детали товара.

PUT /products/{id} — обновление товара.

📄 Заказы (Sale Orders)

GET /sale-orders — список заказов клиентов.

POST /sale-orders — создание нового заказа.

GET /sale-orders/{id} — детали заказа.

PUT /sale-orders/{id} — обновление заказа.

GET /sale-orders/{id}/status — текущий статус заказа.

⚙️ Производство (Production)

GET /production-orders — список заказов на производство.

GET /production-orders/{id} — детали заказа.

PUT /production-orders/{id}/status — обновление статуса производства.

POST /production-orders/{id}/complete — завершение заказа.

🏭 Склад и остатки (Stock)

GET /stock — остатки по всем товарам.

GET /stock/{product_id} — остатки конкретного товара.

POST /stock-movements — создание складской операции (приход/расход).

🚚 Отгрузки (Shipments)

GET /shipments — список отгрузок.

POST /shipments — создание отгрузки.

PUT /shipments/{id}/status — обновление статуса отгрузки.

👤 Контрагенты (Clients & Suppliers)

GET /clients — список клиентов.

POST /clients — создание клиента.

GET /suppliers — список поставщиков.

Полная спецификация доступна по адресу /api/doc (только для авторизованных пользователей).

Скриншот: страница Swagger UI с интерактивной документацией API

Примеры запросов

Получение списка заказов

GET /api/v1/sale-orders HTTP/1.1
Host: ваш-сервер.ru
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Ответ:

{
  "status": "success",
  "data": [
    {
      "id": 1001,
      "orderId": "SO-2603-0042",
      "client": "ООО ИндорТех",
      "amount": 2500000,
      "status": "PROCESSING",
      "createdAt": "2026-03-15T10:30:00Z"
    },
    ...
  ]
}

Обновление статуса заказа в производстве

PUT /api/v1/production-orders/123/status HTTP/1.1
Host: ваш-сервер.ru
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "status": "COMPLETED",
  "qty": 100
}

Ответ:

{
  "status": "success",
  "data": {
    "id": 123,
    "orderId": "PRD-2603-0012",
    "status": "COMPLETED"
  }
}

Создание складского движения (приход)

POST /api/v1/stock-movements HTTP/1.1
Host: ваш-сервер.ru
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "product_id": 567,
  "warehouse_id": 1,
  "type": "IN",
  "qty": 500,
  "comment": "Поступление от поставщика ООО Металл"
}

Как получить API-токен

Токен генерируется в личном кабинете пользователя с ролью ROLE_ADMIN или ROLE_DIRECTOR. Для этого:

  1. Войдите в систему под учётной записью с правами администратора.
  2. Перейдите в раздел «Администрирование» → «Пользователи».
  3. Отредактируйте профиль нужного пользователя или создайте нового (специально для интеграции).
  4. Нажмите кнопку «Сгенерировать API-токен».
  5. Скопируйте токен и сохраните его в безопасном месте. Повторный показ токена невозможен, при утере нужно сгенерировать новый.
Скриншот: страница редактирования пользователя с кнопкой генерации токена
⚠️ Важно: Храните токен в секрете. Не передавайте его третьим лицам. Для интеграций используйте отдельную учётную запись с минимальными необходимыми правами, а не личный аккаунт администратора.

Рекомендации по использованию

  • Соблюдайте лимиты запросов — по умолчанию не более 100 запросов в минуту. При превышении вы получите HTTP 429 (Too Many Requests). Для пакетных операций используйте метод batch или увеличивайте интервал.
  • Используйте идемпотентные операции — если операция не должна повторяться (например, создание заказа), используйте заголовок Idempotency-Key с уникальным ключом.
  • Обрабатывайте ошибки — всегда проверяйте HTTP-статус и поле status в ответе. При ошибках 4xx и 5xx повторяйте запрос с экспоненциальной задержкой.
  • Используйте webhooks — для получения уведомлений об изменениях (например, завершение производства, отгрузка) вместо постоянного опроса API. Настройка webhooks доступна в разделе «Настройки интеграции».
  • Тестируйте в песочнице — если у вас есть тестовый контур, сначала отработайте интеграцию там, чтобы не нарушать работу основной системы.

Часто задаваемые вопросы

Какие форматы данных поддерживает API?

На данный момент поддерживается только JSON. В будущем планируется поддержка XML для совместимости с некоторыми устаревшими системами.

Можно ли получить доступ к API из внешней сети (не локальной)?

Да, если ваш сервер ModernERP Pro доступен из внешней сети (публичный IP или через VPN). Рекомендуется использовать HTTPS и ограничить доступ по IP-адресам для повышения безопасности.

Как узнать, какие данные можно передавать через API?

Полный список эндпоинтов и моделей данных доступен в интерактивной документации Swagger по адресу /api/doc (требуется авторизация). Там же можно выполнять тестовые запросы прямо из браузера.

Можно ли подключить 1С через API?

Да, для этого у нас есть готовый модуль-расширение для 1С, который работает через наш API. Вы можете настроить обмен заказами, клиентами, отгрузками и ФОТ. Подробнее см. раздел Интеграция с 1С:Бухгалтерия.

Связанные разделы документации