Синхронизация по API

API — это способ связать PlanPlace с другими вашими программами (1С, CRM, складскими системами), чтобы данные обменивались автоматически, без ручного труда. Это инструмент для средних и крупных компаний, где номенклатура большая, а цены меняются часто. В этой статье разберём, что даёт API и для кого он нужен.

Полный справочник методов API (для разработчиков) — в разделе «Публичное API»: цены, заказы, каталог. Эта статья — вводная, для понимания возможностей.

Что такое API простыми словами

API — это «канал связи» между программами. Через него ваша учётная система может сама передавать в PlanPlace актуальные цены, а PlanPlace — отдавать обратно данные о заказах. Человеку не нужно вручную переносить цифры из таблицы в таблицу: программы договариваются напрямую.

Что можно автоматизировать

• Обновление цен. Цены из 1С или другой системы автоматически попадают в прайс-лист PlanPlace, а оттуда — на все материалы, привязанные по артикулу. Обновили закупочные цены в 1С — через минуту они актуальны в конструкторе.
• Получение заказов. Заявки и проекты можно автоматически передавать в вашу CRM или учётную систему.
• Управление видимостью по складу. Можно автоматически обновлять признак видимости декоров и материалов в зависимости от наличия на складе — закончился декор, он скрылся из выбора.

С чем интегрируется

PlanPlace через API связывается с:

• 1С — учёт, цены, номенклатура;
• CRM-системами — заявки и клиенты;
• складскими программами — остатки и наличие;
• другими учётными системами.

Важное ограничение: только режим дилера

Автоматическая синхронизация цен работает только в режиме дилера. Это прямо указано в самом разделе синхронизации в личном кабинете. Если у вас не дилерский режим, цены обновляют вручную через импорт Excel/CSV — это тоже быстро, просто требует участия человека. Про дилерский режим — в статье «Управление дилерами».

Когда API действительно нужен

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

Если ассортимент небольшой и цены меняются редко, API может и не понадобиться — хватит ручного импорта прайс-листа.

Как подключить

Настройка API — техническая задача, которую обычно решает программист на стороне вашей компании по документации PlanPlace. Ниже — основные технические детали, а полная документация и примеры запросов доступны по ссылке в конце статьи. Если нужна помощь, обращайтесь в поддержку.

Как работает синхронизация цен

Формат данных. Цены передаются JSON-массивом, где у каждой позиции два обязательных поля: code (артикул) и price (цена).

[
  {"code": "КП-0014", "price": "3645.60"},
  {"code": "КП-0016", "price": "4800.42"},
  {"code": "НР-0018", "price": "545.25"}
]

Способы отправки:

• Вручную — вставить JSON прямо в поле в личном кабинете.
• Автоматически (POST-запрос) — передать данные программно с двумя параметрами:
  • data — JSON с ценами и артикулами;
  • sync_key — ключ синхронизации (в личном кабинете он называется «Ключ для автоматической синхронизации»).

В ответ сервер возвращает массив артикулов, которые успешно синхронизировались.

Эндпоинт. POST-запрос отправляется на адрес вашего собственного кабинета, а не на общий planplace.ru. Точный URL не нужно придумывать — он показан прямо в разделе синхронизации в поле «Url для автоматической синхронизации» (вида https://ваш-домен/config/index.php/sync/prices_input). Там же, в поле «Основной URL», виден базовый адрес кабинета, а в поле «Ключ для автоматической синхронизации» — ваш sync_key. Берите значения из кабинета — так вы не ошибётесь с доменом.

Расписание. Чтобы цены обновлялись сами, настройте ежедневный запуск синхронизации (например, в 00:00) через задачу CRON на стороне вашей системы. Для 1С есть готовый пример процедуры, которая формирует HTTPS POST-запрос (ссылка на пример — прямо в разделе синхронизации кабинета).

Передача заявки из PlanPlace 2 во внешнюю систему

Для отправки заявки со сцены PlanPlace 2 используйте APIv2. В этом режиме обычные поля формы передаются строками, а вложения — отдельными файлами multipart/form-data:

• проект — файл .dbx;
• скриншот — screen.png;
• спецификация — PDF;
• табличные документы — Excel или CSV, если их формирование включено.

Режим включается в разделе «Настройки конструктора» переключателем «Использовать API 2 версии». Там же указывается адрес внешнего обработчика. Полный состав полей, названия файлов и порядок проверки описаны в статье «Публичное API: отправка заявки (APIv2)».

Не путайте два направления обмена. APIv2 отправляет заявку во внешнюю систему сразу при оформлении на сцене. Если ваша система сама периодически запрашивает уже созданные заявки, используйте методы получения заказов.

Синхронизация комплектующих

Кроме цен, через API можно синхронизировать комплектующие (отдельный метод). Запрос принимает данные комплектующих и тот же sync_key, а в ответ возвращает, сколько позиций обновлено и сколько добавлено. Это удобно, чтобы автоматически поддерживать актуальный список фурнитуры и крепежа из вашей учётной системы. Точные параметры — в документации (ссылка ниже).

Полная документация

Подробное техническое описание методов, параметров и примеров — в документации, ссылка на которую есть прямо в разделе синхронизации вашего кабинета (пункт «Документация», открывает /docs/index.php на вашем домене).

Коротко

API автоматизирует обмен данными между PlanPlace и вашими системами (1С, CRM, склад): цены и комплектующие обновляются автоматически, а заявки PlanPlace 2 можно отправлять вместе с проектом, изображением и документами через APIv2. Автоматическая синхронизация цен работает только в режиме дилера. URL для запросов и ключ берутся из самого кабинета (раздел синхронизации), а не придумываются. Подключение выполняет программист по документации, ссылка на которую тоже есть в этом разделе.