Recca Разработчикам
Меню

Creatium

Блок «Код» и вход без второго логина на сайте Creatium.

Creatium — конструктор сайтов без собственного бэкенда. Recca работает с ним тремя дверями: приём заявок с формы, мост идентичности (человек вошёл на сайте Creatium, а в Recca для него заводится участник) и источник данных для таблицы «Пользователи» с соответствием member.id → recca_id. Ниже — что делает каждая и в каком порядке подключать.

Что нужно

  • Интеграция типа Creatium в кабинете сети («Интеграции» → «Подключение сайта»; доступно на тарифе с продуктом «Витрина Pro» и выше). При создании выбирается провайдер Creatium и показывается токен вида rec_creatium_…. Токен показывается один раз: потерянный только перевыпускается. В базе хранится его хеш.
  • Токен привязан к одной интеграции и одной организации. Организация всегда определяется по токену, а не по телу запроса, поэтому чужие данные недоступны.
  • Токен передаётся в заголовке X-Recca-Token: <токен> или Authorization: Bearer <токен>. Передавать токен в адресе (?token=…) не нужно: адрес целиком попадает в журналы серверов.

Заявки с формы: POST /hooks/leads

Адрес приёма заявок — https://api.recca.ru/hooks/leads. Тело — стандартное тело вебхука формы Creatium (поля формы, form_name, данные сайта). Recca распознаёт поля по именам на русском и английском: имя (name, «Имя», «Представьтесь», «ФИО»), телефон (phone, «Номер телефона», «Телефон»), почта (email, «Электронная почта», «Почта», «E-mail»), комментарий (comment, «Комментарий», «Сообщение»).

⚠ Ограничение: дверь /hooks/leads принимает токен только в заголовке. У вебхука Creatium, по нашим данным, поля для заголовков нет, поэтому подключить форму Creatium к этой двери сейчас нельзя; обходных путей мы не предлагаем. Заявка с токеном в адресе отклоняется с 401 MISSING_TOKEN.

Чтобы заявка привязывалась к привёдшему партнёру, на сайт ставится скрипт, который сохраняет код из ?recca= в localStorage и подкладывает его скрытым полем recca в каждую форму. Скрипт вставляется в «Настройки сайта → Код в head»:

<script>
(function(){
  var c = new URLSearchParams(location.search).get('recca');
  if (c) localStorage.setItem('recca_code', c);
  document.addEventListener('submit', function(e){
    var code = localStorage.getItem('recca_code');
    if (!code) return;
    var f = e.target;
    if (!f.querySelector('[name="recca"]')) {
      var h = document.createElement('input');
      h.type = 'hidden'; h.name = 'recca'; h.value = code;
      f.appendChild(h);
    }
  }, true);
})();
</script>

Проверять на настоящей ссылке участника: придуманный код Recca не узнает, и заявка придёт без партнёра.

Мост идентичности: POST /hooks/creatium/identity

Для сайтов, где человек регистрируется и входит средствами Creatium. На событие «Регистрация + Заявка» Recca:

  1. проверяет токен и что интеграция типа Creatium;
  2. берёт из тела member.id — идентификатор вошедшего пользователя Creatium — и контакт (почту и/или телефон) и имя;
  3. заводит или находит участника в вашей сети и считает суррогат tenant_recca_id;
  4. запоминает связь member.id → tenant_recca_id;
  5. по возможности записывает суррогат во внешнюю таблицу (если для интеграции настроен адаптер записи).

Ответ: tenant_recca_id, is_new, ref_url, writeback. Creatium ответ вебхука не читает, поэтому суррогат на сайт попадает не ответом, а через таблицу данных (см. ниже). Ссылка ref_url сейчас не заполняется (всегда null).

Отказы моста:

КодСтатусСмысл
MISSING_TOKEN401токен не передан
INVALID_TOKEN401токен не найден
TOKEN_REVOKED401интеграция отозвана
WRONG_PROVIDER400интеграция не типа Creatium
MISSING_MEMBER_ID422гостевая отправка без member.id: связывать некого (анонимные заявки идут через /hooks/leads)
MISSING_IDENTITY422в форме нет ни почты, ни телефона
EMAIL_BELONGS_TO_DIFFERENT_USER, PHONE_BELONGS_TO_DIFFERENT_USER409контакт уже принадлежит другому человеку; защита от угона аккаунта

Если фамилия и имя пришли одной строкой, Recca делит её на имя и фамилию. Почта считается подтверждённой по умолчанию, потому что регистрацию поручился ваш сайт; это можно отключить в настройках адаптера записи.

Таблица «Пользователи»: GET|POST /hooks/creatium/users

Источник данных для функции Creatium «Импорт таблицы по API». Ответ — { columns, rows, totalCount }, колонки по порядку: member_id, recca_id, status. Первая колонка — ключ привязки к вошедшему пользователю.

  • Полный импорт: тело { "properties": {}, "sort": …, "limit": …, "skip": … } возвращает строки организации, у которых известен member_id.
  • Привязка конкретного человека: { "properties": { "member_id": "<member.id>" } } возвращает одну строку.
  • Для проверки из браузера работает GET с ?member_id=.

Токен — тот же токен интеграции Creatium; организация определяется по токену. Неверный токен даёт 401, отозванный — тоже 401, интеграция другого провайдера — 403 WRONG_PROVIDER.

Эти две двери принимают токен и в строке запроса ?token=, но используйте только заголовок: адрес оседает в журналах.

Кабинет участника на сайте

После привязки у каждого вошедшего пользователя Creatium есть recca_id — тот же tenant_recca_id. Он нужен для встраивания личного кабинета и виджетов: iframe-страницы https://api.recca.ru/embed/v1/cabinet/{tenant_recca_id}?tenant=<слаг сети> и компоненты из раздела «JS и виджеты» принимают именно его. Реальные данные показываются только с токеном, который выписывает метод POST /federation/v1/users/{id}/embed-session (право users:impersonate) — с серверной стороны. У сайта Creatium без собственного бэкенда своего сервера нет, поэтому способ получения токена для встроенного кабинета нужно согласовать отдельно; без токена кабинет показывает демонстрационное содержимое.

Порядок подключения

  1. Создайте интеграцию Creatium в кабинете и сохраните токен.
  2. Подключите источник данных «Импорт таблицы по API» на https://api.recca.ru/hooks/creatium/users с заголовком токена, если ваша версия Creatium позволяет задать заголовок запроса.
  3. Подключите вебхук регистрации на https://api.recca.ru/hooks/creatium/identity — по тем же условиям.
  4. Проверьте: зарегистрируйте тестового пользователя на сайте и убедитесь, что POST /hooks/creatium/users с его member_id возвращает строку с recca_id.

Если в вашей версии Creatium нет поля для заголовка запроса, подключить соответствующую дверь нельзя; токен в адресе мы не рекомендуем.

См. также