Публичное API: обзор и аутентификация

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

Не путайте с внутренним JS-API сцены (раздел «Разработчику») — то для кастомизации интерфейса в браузере. Здесь — серверное HTTP-API для интеграций.

Как устроено

• Протокол: REST поверх HTTP.
• Формат: все ответы приходят в виде JSON.
• Методы: чтение — GET, изменение — POST.

Базовый URL

Все запросы идут на основной URL вашего кабинета — он указан в личном кабинете, в разделе API (и в разделе синхронизации). В этой документации он обозначается как ОсновнойURL. То есть полный адрес метода выглядит так:

ОсновнойURL/api/<метод>

Базовый URL индивидуален для вашего аккаунта (ваш домен), не общий planplace.ru. Берите его из кабинета, не придумывайте.

Аутентификация: ключ sync_key

Каждый запрос должен содержать sync_key — ключ синхронизации из личного кабинета (поле «Ключ для автоматической синхронизации»). Без верного ключа запрос отклоняется.

• для GET-запросов ключ передаётся в параметрах строки запроса: ?sync_key=ВАШ_КЛЮЧ;
• для POST-запросов ключ передаётся в теле запроса вместе с данными.

Ключ индивидуален. Храните его в секрете и берите из кабинета.

Общие правила запросов

• POST-методы изменения данных принимают два поля: data (полезная нагрузка в формате JSON) и sync_key.
• GET-методы чтения принимают sync_key как параметр запроса.
• Ответ — JSON. Для операций изменения это обычно строка статуса ("success" / "error"), для чтения — массив объектов или объект данных.

Применение изменений: apply_data

Многие операции записи не вступают в силу на сцене сразу — их нужно «применить» (аналог кнопки «Выгрузить настройки в конструктор» в кабинете). Для этого есть отдельный метод:

GET  ОсновнойURL/api/apply_data?sync_key=ВАШ_КЛЮЧ

Вызывайте его после серии изменений (например, после массового обновления цен или материалов), чтобы новые данные попали в планировщик.

Карта разделов API

Раздел	Что делает	Статья
Цены	синхронизация цен корпуса, фасадов, столешниц, цоколя, витрин и прайс-листа	«API: цены»
Заказы	получение заявок клиентов (для CRM)	«API: заказы»
Материалы и декоры	чтение, добавление, обновление, удаление материалов и их категорий	«API: каталог»
Фасады, ручки, модули, наборы модулей, модели, комплектующие, модели кухонь	управление элементами каталога	«API: каталог»

Типовой сценарий интеграции с 1С

1. В 1С по расписанию (CRON) формируется JSON с актуальными ценами.
2. Отправляется POST на нужный метод раздела «Цены» с data и sync_key.
3. Вызывается GET api/apply_data, чтобы изменения попали на сцену.
4. (Опционально) периодически читаются новые заказы через GET api/get_items/orders и заводятся в CRM.

Готовый пример реализации запроса для 1С есть в разделе синхронизации вашего кабинета.

Коротко

Публичное API PlanPlace — это REST поверх HTTP с JSON-ответами. Базовый URL и ключ sync_key берутся из раздела API в кабинете. GET — чтение (ключ в строке запроса), POST — изменение (data + sync_key в теле). После записи вызывайте apply_data, чтобы применить изменения. Подробности по разделам — в статьях «Цены», «Заказы» и «Каталог».