База знаний EMS-платформы PlatParts Руководство по настройке EMS-платформы PlatParts
Актуальная (latest)
API

API

На этой странице 9

API v1.*.*

Этот раздел описывает программный интерфейс PlatParts для интеграций с внешними системами. Здесь собраны стабильные методы версии v1.*.*, которые используются для:

  • интеграций учётных систем и обмена каталогом/остатками (например, 1С);
  • B2B‑доступа партнёров к вашим остаткам и брендам;
  • модульных интеграций (внешние сервисы через подключаемые модули и webhooks).

Общие принципы

  • Протокол: HTTPS, REST‑стиль, все данные в формате application/json.
  • Версионирование: текущая версия — v1.*.*. При несовместимых изменениях будут появляться новые версии (v2.0.0, v3.0.0 и т.п.).
  • Структура ответа:
    • как правило, все методы возвращают JSON с флагом результата и сообщением:
      • result / status: true|false;
      • message: человекочитаемое сообщение;
      • дополнительные поля (brands, parts, categories, errors и т.п.).
  • Ошибки валидации:
    • HTTP‑код 422 или 400;
    • тело может содержать подробный список ошибок по полям (стандартный формат Laravel).

Авторизация и безопасность

1С‑интеграция

  • Использует статический токен из админки (Настройки → Общие настройки → вкладка 1С интеграция).
  • Каждый запрос к /api/1c/* должен иметь заголовок:
    • Authorization: Bearer {ONEC_TOKEN}.
  • В настройках можно:
    • включить/выключить интеграцию;
    • указать склад/точку выдачи по умолчанию;
    • ограничить список IP‑адресов, с которых принимаются запросы 1С.

Подробности: см. 1С: каталог и остатки.

B2B‑API для партнёров

  • Отдельный B2B‑токен, настраиваемый там же, в блоке B2B API.
  • Все запросы к /api/b2b/* требуют заголовка:
    • Authorization: Bearer {B2B_TOKEN}.
  • При отключённом B2B‑API эндпоинты возвращают 503 Service Unavailable.

Подробности: см. B2B API для партнёров.

Интеграции через модульную систему

Для модульных интеграций используются:

  • события (хуки) платформы;
  • исходящие webhooks (PlatParts → ваш сервер);
  • входящий webhook (ваш сервер → PlatParts) — если поддерживается модулем.

Подробности: Интеграции и модульность (архитектура, хуки, REST, webhooks, отладка, типовые проблемы).

Среды и базовый URL

В примерах документации используется условный домен:

  • https://example.com

В рабочем окружении замените его на ваш боевой/тестовый домен:

  • Прод: https://ВАШ_БОЕВОЙ_ДОМЕН
  • Тест: https://ВАШ_ТЕСТОВЫЙ_ДОМЕН (если используется отдельная среда)

Рекомендуется проводить интеграцию и отладку сначала на тестовой среде.

Нюансы и рекомендации

  • Идемпотентность: методы для загрузки каталога и остатков (1С) реализованы через upsert по внешним ID (onec_id). Повторная отправка тех же данных не должна приводить к дублированию.
  • Производительность:
    • для 1С предусмотрены батч‑методы (batch-upsert, batch-update), используйте их вместо покомпонентных вызовов;
    • B2B‑методы get-brands и get-parts выполняют запросы к нескольким складам, поэтому важно не злоупотреблять слишком частыми вызовами в проде.
  • Безопасность:
    • не логируйте токены в собственной системе мониторинга;
    • при смене токена обязательно синхронизируйте его во всех внешних системах (1С, B2B‑клиенты).
  • Обратная совместимость:
    • новые поля в ответах API добавляются без удаления старых;
    • при необходимости удаления/изменения формата будет объявлена новая минорная/мажорная версия API.