Как принимать заявки с сайта в CRM

Входящие заявки позволяют передавать данные формы с вашего сайта в CRM balvanchik. Сервер сайта отправляет JSON, а balvanchik сохраняет заявку как лид. После этого её можно просмотреть и обработать вручную или отдельной автоматизацией.

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

#1. Создайте источник заявок

1. Выберите нужное пространство организации.
2. Откройте «Настройки» → «Интеграции» → «Источники заявок».
3. Нажмите «+» и задайте название, например «Форма обратного звонка».
4. При необходимости добавьте «Дополнительные JSON-поля» и заполните «IP allowlist».
5. Создайте источник и сохраните реквизиты из окна «Сохраните реквизиты».

URL и Bearer secret показываются после создания. Секрет с префиксом bvi_ доступен только в этом окне: передайте его разработчику по защищённому каналу и сохраните в серверном хранилище секретов или переменной окружения. Обычный токен интеграции с префиксом bvk_ для отправки заявки не подходит.

Не помещайте секрет в HTML, браузерный JavaScript, публичный репозиторий или custom. Посетитель отправляет форму вашему серверу; ваш сервер обращается к balvanchik.

«IP allowlist» принимает IPv4, IPv6 и CIDR, по одному значению на строку. Укажите фактический внешний IP сервера, с которого отправляется запрос, с учётом NAT или прокси. Поле JSON client_ip относится к посетителю и не используется для этой проверки. Пустой список разрешает запросы с любых IP, но Bearer secret остаётся обязательным.

Источник определяет, куда поступают заявки и какие дополнительные поля разрешены. Выбор создаваемых контактов, сделок, задач и заметок настраивается в автоматизации.

#2. Отправьте JSON с сервера сайта

Используйте URL из реквизитов:

POST https://api.balvanchik.ru/api/v1/intake/<sourceId>
Authorization: Bearer <секрет_источника_bvi_...>
Content-Type: application/json

Минимальное тело запроса содержит пять обязательных строковых полей:

{
  "request_id": "example-form-0001",
  "name": "Тестовый заявитель",
  "phone": "+7 (000) 000-00-00",
  "service": "Консультация",
  "source_page": "https://example.com/contact"
}

Данные в примере фиктивные. Для каждой новой отправки формы создавайте новый request_id и сохраняйте его вместе с JSON на сервере сайта. source_page должен быть абсолютным HTTPS URL страницы формы.

Необязательные поля:

Передавайте только необходимые данные посетителя. client_ip и user_agent необязательны и удаляются из сохранённой заявки через 90 дней. Не дублируйте их в custom.

#Дополнительные поля

В источнике для каждого поля задайте название, ключ JSON, тип и признак «Обязательное». Например:

Для такого источника полный запрос может выглядеть так:

{
  "request_id": "example-order-0002",
  "name": "Тестовый заявитель",
  "phone": "+7 (000) 000-00-00",
  "service": "Консультация",
  "source_page": "https://example.com/order",
  "custom": {
    "order_number": "DEMO-002",
    "budget": 50000,
    "urgent": false
  }
}

Типы должны совпадать точно: 50000 — число, "50000" — строка; false — boolean, "false" — строка. Значения 0 и false подходят для обязательных полей своих типов. Обязательная строка не может быть пустой или состоять из пробелов.

В custom разрешены только объявленные ключи. Вложенные объекты, массивы и null не принимаются. Ключ начинается с латинской буквы, далее допускаются латинские буквы, цифры и _; длина — до 64 символов. Ключи constructor, prototype, __proto__, client_ip и user_agent запрещены.

Изменение дополнительных полей источника действует на новые заявки. У ранее принятых заявок сохраняются прежние значения и названия полей.

#3. Проверьте ответ и настройте повторы

Успешный ответ — HTTP 202:

{
  "accepted": true,
  "receipt_id": "12345678-1234-4123-8123-123456789abc",
  "duplicate": false
}

receipt_id — идентификатор сохранённой заявки. Ответ подтверждает её сохранение; результат выполнения автоматизаций проверяется отдельно.

Рекомендуемый таймаут запроса на сервере сайта — 5 секунд. Если соединение оборвалось или ответ не получен, повторите запрос с тем же request_id и тем же JSON, включая дату и дополнительные поля. Это позволяет безопасно повторить отправку, даже если первый запрос уже был принят.

Для того же источника повтор принятой заявки вернёт 202, тот же receipt_id и duplicate: true. Нового лида и новых запусков правил такой повтор не создаёт. Другой JSON с уже использованным request_id приводит к 409.

Заголовок Idempotency-Key необязателен. Если отправляете его, значение должно точно совпадать с request_id. Не создавайте новый идентификатор для технического повтора: он будет означать новую заявку.

#Ограничения и ошибки

Неизвестные поля верхнего уровня отклоняются. Сверяйте код ответа и сообщение ошибки:

При временной серверной ошибке или сетевом сбое повторяйте сохранённый запрос с задержкой. Ошибки данных и доступа сначала исправьте: немедленные повторные отправки их не устранят.

#4. Найдите заявку и проверьте подключение

Откройте «CRM» → «Заявки» либо нажмите «Показать заявки» у источника в настройках интеграций. Список можно отфильтровать по источнику и статусу.

В карточке доступны данные обращения, страница формы, ID запроса, время получения, дополнительные поля и журнал автоматизаций с результатами или ошибками. Статус можно изменить на «Новая», «Квалифицирована» или «Отклонена».

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

• первый запрос вернул 202, и заявка появилась в CRM;
• повтор с тем же ID и JSON вернул duplicate: true, а второй лид не появился;
• дополнительные поля отображаются с нужными названиями и значениями.

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

#5. При необходимости подключите автоматизацию

В меню пользователя откройте «Автоматизации», нажмите «+» и выберите событие «Получена новая заявка». Настройка доступна владельцу и администраторам организации с включённым CRM.

Выберите источники явно, при необходимости задайте условия по стандартным или дополнительным полям и связи «И» / «ИЛИ». Без условий подходят все новые заявки выбранных источников. «И» выполняется раньше «ИЛИ».

Укажите обязательного ответственного из участников организации и добавьте действия: «Найти или создать контакт», «Создать сделку», «Создать задачу», «Создать заметку» или «Уведомить ответственного». Для задач и заметок в организации должен быть включён модуль «Задачи и заметки»; для сделки выберите воронку и рабочий этап.

Дополнительные поля можно использовать в условиях и названиях действий, например {custom.order_number}. Boolean в условиях сравнивайте с true или false. Условие по отсутствующему полю не срабатывает; в названии отсутствующее значение заменяется пустой строкой.

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

Отправьте новую тестовую заявку после сохранения правила и проверьте раздел «Автоматизации» в её карточке. Для правил рабочего сайта выбирайте его источник, чтобы тестовые заявки не запускали рабочие действия.

Полный технический контракт доступен в OpenAPI balvanchik.