API v1.*.*

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

• Управления каталогом и остатками со стороны учётной системы (1С и др.);
• B2B‑доступа партнёров к вашим остаткам и брендам.

---

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

• Протокол: 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 для партнёров.

---

Среды и базовый 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.

---

Навигация по API

• 1С: каталог и остатки
  Описание REST‑методов для загрузки категорий, товаров, атрибутов, остатков и цен из 1С.

• B2B API для партнёров
  Описание методов (get-pick-up-points, get-brands, get-parts) для подключения сторонних интернет‑магазинов.