Публичное API: отправка заявки (APIv2)

APIv2 — это дополнительный формат отправки заявки из конструктора во внешнюю систему. Он не заменяет основное публичное API: чтение заявок через GET api/get_items/orders, синхронизация цен, каталогов и другие методы продолжают работать как раньше.

Используйте APIv2, когда внешней CRM или вашему обработчику нужны не только текстовые поля заявки, но и файлы: проект, скриншот сцены, PDF-спецификация, Excel или CSV.

Важно. APIv2 описывает именно отправку заявки в момент оформления заказа на сцене. Если CRM должна периодически забирать уже созданные заявки из PlanPlace, используйте основную статью «Публичное API: заказы».

Когда нужен APIv2

APIv2 полезен, если вы:

• передаёте заявку сразу во внешнюю CRM или собственный обработчик;
• хотите получать файл проекта в формате .dbx;
• хотите принимать скриншот сцены отдельным файлом screen.png, а не строкой внутри формы;
• обрабатываете PDF, Excel или CSV как обычные файлы multipart-запроса;
• хотите отделить новый формат обработки заказов от уже работающей старой интеграции.

Если текущая интеграция уже стабильно забирает заявки через api/get_items/orders или принимает старый формат отправки, её не нужно переносить на APIv2 без отдельной причины.

Как включить

Режим включается в личном кабинете, в настройках конструктора:

1. Откройте раздел «Настройки конструктора».
2. Включите переключатель «Использовать API 2 версии».
3. Укажите или проверьте URL для отправки заявки во внешнюю систему.
4. Выгрузите настройки в конструктор и проверьте отправку тестовой заявки.

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

Формат данных

APIv2 использует multipart/form-data. Текстовые поля заявки передаются строками, а вложения — файлами.

Основные поля:

Поле	Что содержит
name	имя или название заявки из формы
client_name	имя клиента, если такое поле есть в форме
email	email клиента
phone	телефон клиента
comments	комментарий клиента
price	стоимость проекта, если расчёт цены включён
dealer_sub_catalog	подкаталог дилера, если заявка пришла из дилерского режима
order_number	номер заявки в PlanPlace
client_order_filename	имя файла проекта, сохранённого в PlanPlace
project_link	ссылка на открытие сохранённого проекта

Состав текстовых полей зависит от настроек формы заявки. Если вы добавили свои поля в форме, они тоже приходят в запросе с заданными идентификаторами.

Файлы

В APIv2 файлы передаются как обычные части multipart-запроса:

Поле	Файл
save_dbx	файл проекта .dbx
screen	скриншот сцены screen.png
pdf_file_blob	PDF-спецификация, если её отправка включена
xlsx_file	Excel-файл, если он формируется для заявки
csv_file_order	CSV-файл, если в проекте доступна выгрузка CSV

Пользовательские файлы из формы заявки также передаются как файлы multipart-запроса.

Отличие от старого режима. При APIv2 скриншот и проект не кладутся в скрытые поля формы как строки. Скриншот создаётся отдельным PNG-файлом, а проект передаётся как .dbx.

Что должен принять внешний обработчик

Ваш обработчик должен принимать POST multipart/form-data и уметь читать:

• обычные поля формы из тела запроса;
• файлы из multipart-разделов;
• имя проекта из client_order_filename;
• ссылку на проект из project_link;
• номер заявки из order_number.

Пример минимальной логики на стороне внешнего обработчика:

$orderNumber = $_POST['order_number'] ?? '';
$clientName = $_POST['client_name'] ?? ($_POST['name'] ?? '');
$projectLink = $_POST['project_link'] ?? '';

if (isset($_FILES['save_dbx'])) {
    // Сохраните файл проекта.
}

if (isset($_FILES['screen'])) {
    // Сохраните скриншот сцены.
}

Конкретные названия дополнительных полей зависят от вашей формы заявки. Поэтому перед настройкой CRM отправьте тестовую заявку и посмотрите фактический набор полей и файлов, который приходит на ваш URL.

Ответ и ошибки

PlanPlace отправляет данные на внешний URL и возвращает ответ обработчика. Для пользователя на сцене успешной считается отправка, при которой внутренний запрос формы завершился HTTP-статусом 200.

Если внешний URL недоступен, долго отвечает или отклоняет файлы, заявка может не попасть во внешнюю систему. В таком случае проверьте:

• доступность URL из серверной среды PlanPlace;
• поддержку multipart/form-data;
• ограничения по размеру файлов на стороне CRM или обработчика;
• логи внешнего обработчика;
• включён ли режим «Использовать API 2 версии» после выгрузки настроек.

Безопасность

Не полагайтесь только на то, что запрос пришёл из PlanPlace. На стороне внешнего обработчика добавьте собственную проверку: секретный параметр в URL, токен, Basic Auth или другой механизм, который принят в вашей инфраструктуре.

Также заранее задайте ограничения на размер файлов и список разрешённых типов. В заявке могут приходить проект, изображения и документы, поэтому обработчик должен сохранять их в безопасное место и не выполнять содержимое файлов как код.

Коротко

APIv2 — это отдельный режим отправки заявки из конструктора во внешнюю систему через multipart/form-data. Он передаёт проект .dbx, скриншот screen.png, PDF, Excel, CSV и поля формы как отдельные части запроса. Основное публичное API при этом остаётся рабочим: заявки по-прежнему можно читать через «API: заказы», а цены и каталог синхронизировать через существующие методы.