Перейти к содержимому

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

Обновлено:

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

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

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

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

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

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

API доступен в основном аккаунте на всех вариантах тарифов PRO и Business. Включать режим дилера для автоматической синхронизации цен не требуется.

  • большой ассортимент (сотни и тысячи позиций);
  • частые изменения цен;
  • желание исключить ручные ошибки переноса;
  • уже есть 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. Берите значения из кабинета — так вы не ошибётесь с доменом.

Как работать с ключом автоматической синхронизации

Заголовок раздела «Как работать с ключом автоматической синхронизации»

Ключ подтверждает, что запрос к API отправляет ваша система. Считайте его паролем: не публикуйте ключ, не передавайте его в открытых сообщениях и храните только в настройках подключённых программ.

Ключ находится в личном кабинете, в разделе «Синхронизация», в поле «Ключ для автоматической синхронизации». По умолчанию значение скрыто точками.

  1. Откройте раздел «Синхронизация» в личном кабинете.
  2. Нажмите значок глаза рядом с полем ключа, чтобы временно показать его. Повторное нажатие снова скроет значение.
  3. Чтобы передать ключ в настройки интеграции без ручного выделения, нажмите кнопку копирования рядом с полем.

Показывайте ключ только там, где его не смогут увидеть посторонние. После проверки снова скройте значение.

Замена нужна, если ключ мог попасть к посторонним, сотрудник с доступом покинул компанию или вы хотите планово обновить данные доступа. Кнопка «Перегенерировать ключ» доступна владельцу кабинета и пользователям с административными правами.

  1. Нажмите «Перегенерировать ключ».
  2. Прочитайте предупреждение и подтвердите замену.
  3. Скопируйте новый ключ.
  4. Замените старый ключ во всех программах и интеграциях, которые обращаются к API PlanPlace.
  5. Запустите тестовую синхронизацию и убедитесь, что данные передаются.

Важно: сразу после подтверждения старый ключ перестаёт работать. Пока новый ключ не указан в подключённых системах, автоматическая синхронизация из них будет отклоняться. Если один ключ используют несколько интеграций, обновить его нужно в каждой из них.

Сам по себе ключ не меняется: действующее значение продолжает работать, пока пользователь с нужными правами не запустит перегенерацию.

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

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

Заголовок раздела «Передача заявки из 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. Функция доступна в основном аккаунте на всех вариантах тарифов PRO и Business. URL для запросов и ключ берутся из самого кабинета (раздел синхронизации), а не придумываются. Ключ по умолчанию скрыт: его можно временно показать, скопировать или заменить. После замены старый ключ сразу перестаёт работать, поэтому новый нужно указать во всех интеграциях. Подключение выполняет программист по документации, ссылка на которую тоже есть в этом разделе.