Forms, leads and CRM boards

Статус: current · проверенный: 2026-10-25, source обзор; нет live представления · владелец: откидной Служить: GET /docs/forms

1.Что вы можете сделать здесь

Создать form, вставить его widget или открыть его из button, submit а custom викторина через платформу и управлять leads в CRM Это совет директоров. forms ранее заключенный договор /docs/webcoding §§13-14.2 Конечная точка schema и field ограничения доступны в /openapi.json?scope=forms,leads; соседний контракты: /docs/widgets-area, /docs/own-markup, /docs/tasks и /docs/webhooks.

2. Решать first (вилки)

А. CRM sandbox является общим ведущим советом; а dev contour это form/design draft; ан каркас sandbox Изолированные авторами JS. Это разные вещи.. Создание веб-хука не создает ни доски, ни test окружающая среда.

Уровень 1 удаляется <form>, <input> и <select>; использовать widget или form link там. vz-lead Не ставь на место и не ставь на место. PAT, веб-хук secret или уведомительный учет в HTML или public schema.

3. Объекты и где они находятся live

3.1 Разрешения, право собственности и транспорт

Читать /docs/authentication и key паспорт before писать. forms:read читать forms и доски; forms:write редактировать forms и ведущие доски. leads:read reads/exports leads и история; leads:write edits/deletes leads. Оба leads:* scopes чувствительны: ни то, ни другое forms:* ни catalog:* Недостающие безвозмездно. scope дарить PAT_SCOPE_MISSING; несовместимый contour дарить PAT_CONTOUR_MISMATCH. Использовать /docs/scopes.json для сгенерированной карты метода. Конечные точки также принимают tasks:* для рабочих досок; обработчики проверяют доску kind, так forms Права не открывают задачи content Права на выполнение задач не открываются leads.

Частные методы выводят shop от аутентифицированного абонента. company_id cannot Общественное потребление происходит от переключателей. form. Unavailable/foreign Ресурсы используют ту же не найденную маску.

Формы являются contour-сознавать content. Свинец, CRM Интерьеры и переходы являются live operational data, снаружи draft Издание. А. dev PAT читать /sandboxes и редактировать его draft forms; читать и live операций, включая правление Пишет и пишет test-lead) Проверь, что действительно capabilities, не предустановленная name.

Пути ниже имеют нет `/v1` prefix. schema, values, utm, snapshot, board/column settings, и экспортируется csv Прото является bytes: JSON перевозить 64-я основа сырого JSON, или базовой 64 file Содержимое для CSV. Не посылайте вложенных объекты в этих проводах fields. Идентификаторы Int64 являются строками в JSON ответы; счетчики, такие как fields_count, new_leads, total и rows Это цифры.

3.2. Read/write маршруты и конверты ответов

DELETE запросы, направляемые через gateway Нужны хотя бы {} как их body. Статический /form-leads/export маршрут matched before /{id}. Form включает id,name,code,schema,is_active,sandbox_id,created_at,updated_at. Список items опустить schema и добавить fields_count,new_leads; ведущий count это от live столик в любом contour. FormLead включает id,form_id,form_name, values,snapshot,status,page_url,referer,utm,ip,user_agent,is_test,created_at и board/card fields. form_name поступает из хранимых snapshot, выживший form rename/deletion.

Входные ключи карты: title, amount_kop, assignee_user_id; Опущенные ключи остаются Неизменно. clear_amount:true или clear_assignee:true Чтобы их очистить. amount В небольших единицах (в _kop field), Не каталог price единица.

Ведущий list/export фильтры: filter.form_id, filter.status (new|in_progress|done|spam), filter.from/filter.to (RFC3339), filter.include_test (default false), filter.sandbox_id, filter.column_id, filter.is_spam, filter.utm_source, filter.utm_medium. UTM соответствие является exact, нечувствительный к делу, только на плоских клавишах; source и medium сочетать с AND. пустой filter = отсутствие; отсутствие атрибута не соответствует source filter. ценности являются продавцом, а не выбираемыми API Словарь. Списки самые новые. first; forms default до 50 на человека page, leads до 20; page.number Начало в 1 и далее максимальный page size 100. Экспорт не перегружен, до 10 000 rows.

CSV это UTF-8 с прим. BOM, полуколоно-ограниченный и CRLF. Колонны являются created_at,stage,form,page_url, Тогда алфавитный союз field ключи, Затем ключи атрибуции и их first_ Ненадежные формулы, похожие на values Избегать как text.

3.3.The form schema

forms.schema держать fields, внешний вид, banner, button, consent и уведомление конфигурация. widget Только держит form Схема обновления заменяет Вся эта schema: Read-modify-write и сохранить unknown ключи, которые сервер Опущенный, незавершенный schema создает empty {} для owner закончить.

Неизвестные рендеринговые числа безопасно возвращаются и имеют числовой вид settings есть зажатый в widget Нормализатор. hidden field несёт калькулятор values; fields[].hidden:true Вместо этого он скрывает элемент от рендеринга. file kind существует в schema но вложения не принимаются при приеме v1.

подтверждать before писать с POST /docs/validate {"form_schema":{…}} (здесь Валидатор ожидает необработанный объект, а не транспортную базу64. return unknown Результаты с помощью reason. Дублирующие визуальные названия return ignored Предупреждение о результатах, даже если запись разрешена.

4. Рецепты

4.1. создавать или редактировать без дублирования form

Первое чтение /forms и /forms/{id}/usage; Повторно использовать совпадающую цель. второй form только тогда, когда schema должны отличаться от существующих вставок. schema before База64 кодирование:

{
  "v": 1,
  "fields": [
    {"id":"f1","kind":"text","key":"message","label":"Message","required":true},
    {"id":"f2","kind":"consent","key":"consent","required":true},
    {"id":"f3","kind":"submit"}
  ],
  "texts":{"title":"Contact us","success":"Thank you"},
  "consent":{"enabled":true,"link":{"type":"url","url":"/legal/privacy"}}
}

Отправить POST /forms {"item":{"name":"Contact","code":"contact", "is_active":true,"schema":"<base64 of the JSON above>"}}. Это пояснительные Заполните локацию; замените фактическое кодирование. is_active Дефолты для true на Создавать, но отправлять явно., PUT /forms/{id} Изменения только поставляемые ключи; "code":"" Очистить машину code. Прочти form назад, декодировать schema, и compare предназначенный fields и is_active before Чтобы отключить его. прием, обновление is_active:false; Проверить использование before удаление.

4.2 Включить а) form widget или открывающий

Создайте нормальную content block с этим section:

{"type":"text","payload":{"v":2,"kind":"form","props":{"form":{"formId":7}}}}

Используйте возвращенный block id в page Обязательные: The attachment/replace-set Рецепт есть /docs/webcoding §6, wrapper settings есть /docs/widgets (JSON). The form Внешность принадлежит к его schema, Не в том block props. Пропавший или ноль formId делает widget empty и отсутствует в магазине.

Для платформы button выбрать form target {type:"form",id:7}. собственный level-1 HTML может использовать <a href="form:7">Open form</a>; канонический номер-id схема form:<id> Выживут после санации. Неправильные цели будут удалены. Не зависите от data-* или в режиме Click Handlers in level 1.Откройте витрину магазина page и щелкните button; проверить ожидаемое form и fields Появился, а не только спасся block.

4.3. читать или export leads

С помощью live key и leads:read, запросить GET /form-leads?filter.form_id=7&page.number=1&page.limit=50. Декодировать values, snapshot и utm; Не копируйте клиента data в журналах или отчетах. PATCH /form-leads/{id} {"status":"in_progress"} потребности leads:write. Прочитайте зацепку, чтобы проверить ее status. Экспортировать то же самое filter через GET /form-leads/export?filter.form_id=7, декодировать csv, и compare row считать Названия колонок без публикации row Содержание. leads требовать filter.include_test=true; меняет чтение, а не подчинение mode.

4.4 Общественное потребление и самостоятельное site папки

GET /forms/{id}/public возвращает обратно schema с submit удалять; code не является в public Ответ: Прочие. unknown schema Ключи остаются public, Так что не ставьте Секреты там. banner_url решается вопрос о собственном banner.fileId; чужой или мертвый СМИ деградируют до empty URL. Missing/deleted forms и hidden магазины это маскируется как FORM_NOT_FOUND; нормальный resource-Проверки доступа все еще применяются. public Проекция не нуждается в токене. owner's dev Проекция требует аутентифицированный контекст и для PAT, forms:read.

Форма провода публичного представления:

{
  "form_id": 7,
  "values": "<base64 JSON object of schema-key to string value>",
  "page_url": "https://shop.example/contact",
  "referer": "https://source.example/",
  "utm": "<base64 JSON attribution object, or omit>",
  "hp": "",
  "elapsed_ms": 8400
}

Отправьте как JSON то POST /form-leads. Все required fields и enabled consent

• должен быть предоставлен посетителем. consent в code. Электронная почта имеет

Проверка мягкого формата (@ и точка); phone Требуется не менее семи цифр. Недействительные реальные представления получают FORM_VALIDATION_FAILED. Ответом является {ok:true,success_text:"…"} Без лидирования id. Возврат инвалидов {ok:false} И ничего не хранит, успех text исходит из form, не Выдуманная сервером фраза. Проверить хранение через selected test mode в §4.7; ok:true И только одно не является доказательством того, что new row.

отдельно site папки не имеют родителей form хост, cookies или хранилище браузера. Используйте эти public маршруты с credentials:"omit". Для буквальных Origin:null, узкий CORS Разрешение на въезд только GET /forms/{positive-id}/public и POST /form-leads, с Accept/Content-Type предполетный. Authorization, печенье, X-Vizen-Contour X-Vizen-Draft запрещена присутствием. Origin:null не предоставляет доступ арендаторам и cannot обеспечить required resource-Доступ к cookie Грант. /docs/file-storage для isolation/CDN контракт.

Сервер Whitelists string values путем сбора field ключи, исключая обслуживание и file fields, усечение длинной values, фильтры маркетинговых ключей к utm_source,utm_medium,utm_campaign,utm_content,utm_term,gclid,yclid,fbclid,ysclid,ttclid и те же ключи под first. URL fields только сохранить HTTP(S) URL. непустотный hp или elapsed_ms С 1 по 1999 год дает обычный ответ на успех. Но спам в магазинах. Измерьте время честно, не submit на page load. Идентичное непустое values В течение одной минуты обычно сжимается до одной Ведущий и один set уведомления. Check/insert Не атомарно: одновременно У повторных попыток нет гарантии один раз и нет идемпотентности-key контракт. Над пером-form Ежедневный лимит, успех возвращается без хранения или delivery. IP это truncated Время написания (IPv4) /24, IPv6 /48); consent snapshot включает его text/link - время приема. По умолчанию срок хранения составляет 365 дней, а затем Немедленно удалите свинец, чтобы очистить его..

4.5. iframe bridge 2-го уровня

The HTML-block iframe отправляет родителям target происхождение '*' Потому что его Происхождение непрозрачно. Этот мост принадлежит встроенному HTML block; отдельно стоящий site папка не приобретает его автоматически.

parent.postMessage({
  type: 'vizen-form-open', id: 7,
  prefill: { calc_total: String(124500), calc_config: 'Example configuration' }
}, '*');

// After the visitor supplies required fields and consent:
parent.postMessage({
  type: 'vizen-form-submit', id: 7,
  values: { message: 'Example request', consent: 'true' }, reqId: 'request-1'
}, '*');

addEventListener('message', (event) => {
  if (event.source !== parent || event.data?.type !== 'vizen-form-result') return;
  // Match event.data.reqId; use ok, success_text and error in your UI.
});

vizen-form-open отображает всплывающие окна платформы и префиксы schema fields; калькулятор data должен был объявить hidden schema fields. Согласие не является предварительно заполненный. vizen-form-submit Сохраняет ваш UI и подается без всплывающего окна; тот page принимающая продукция page URL, атрибуция, медовый горшок и истекшее время. это {type:'vizen-form-result',reqId,ok,success_text} или {type:'vizen-form-result',reqId,ok:false,error:'validation'|'network'}. Правильно data before повторный validation; Сбои в работе сети могут быть устранены дедупликация limits Неактивный form может return ok:false без ан error code, с закрытым вводом text предоставленный хозяином.

id должно быть положительным целым числом number, Не струна. values это required для submit. Ключи следуют schema-key грамматика; values Это струны, недействительные пары Удалены и объявлены только form fields - негабаритные грузы или недействительный ids drop тот message, с консолью warnings. А. bad/oversized reqId не является недействительным, а не опущено из ответа. limits 6.Отправка before Две секунды — спам под водой. public прием rule. Проверьте, что реальный клик открывает всплывающее окно с ожидаемым предварительным заполнением, а затем проверьте storage/delivery через явно выбранный test path, §4.7.

4.6. CRM Доски, этапы и история

А. form's optional sandbox_id Выберите свой совет; absent/zero использует default Совет. leads Введите его единый впускной столбец. UI → form → совет Вводный механизм - webhook.Lead operations require a live contour.

Не удаляйте a board/column только для test Взять. cannot удалять; Удаление платы перемещает ее leads в default борт, удаление колонки до впуска, маркировка спама обратима; удаление не является. Перечитывайте form и /sandboxes after Проверить лидерство (Vericate the Lead)'s sandbox_id, column_id, column_label, is_spam и история after уполномоченный move.

Board/column settings Базовый 64 JSON предметы на проводе. Omitted/empty bytes уходить settings неизмененный; кодируется {} перезагрузить их. name/label оставаться required. Неизвестные ключи, типы или диапазоны дают SANDBOX_BAD_SETTINGS.

Правила применяются к UI, PAT и объемный: борт mode → source no_return → target limit → target require_comment. Финал (success|failure) колонка является Добраться до любой колонны, несмотря на forward/strict mode, Но другие правила Оставить последнюю колонку после доски mode. Вместимость - это твердая одновременная кепка.: LEAD_TRANSITION_FORBIDDEN, COLUMN_LIMIT_REACHED, LEAD_COMMENT_REQUIRED. Отчет о насыпных операциях {affected:N,skipped:[{id,reason}]}; неправильно board/ownership может быть FORM_LEAD_NOT_FOUND.

События include id,kind,from_column_id,to_column_id,from_label,to_label,comment, actor_user_id,actor_role,at,is_spam. Типа того created,moved,column_deleted, sandbox_deleted,spam; Актёрские роли 1 staff сессия, 2 PAT owner, 3 system. is_spam Присутствует только на спаме events. Ярлыки - это снимки; история - это Удаленный с помощью свинца. column_entered_at поддержка overdue проверки против deadline_days; старше leads может не хватать.

Для использования табло /docs/tasks: GET /sandboxes?view=tasks Выберите тот, который kind, который never получающие form leads. по умолчанию view это leads.

4.7 Выберите test mode явно

1. Читать /sandboxes, Затем назначить form Предназначенный совет. Доска по-прежнему делится live CRM, Не изолированный test окружающая среда.
2. Нет. external delivery: использовать owner's удостоверенный JWT dev сессия их dev form. Эти магазины is_test:true и блокирует уведомления. Проверить его в кабинете с test rows enabled; dev PAT cannot читать leads.
3. Доставка test: с уполномоченным live доступ и forms:write, звонить POST /forms/{form_id}/test-lead {form_id}. Он хранит test Ведущий и действительно Отправка уведомлений с меткой [ТЕСТ] и веб-хук с test:true. Проверьте фактического получателя и проверьте доску с помощью filter.include_test=true. /webhooks/{id}/test Также контактирует с реальным ни один из них не является сухим;.

Не надо. test а dev form Просто добавляя dev PAT то POST /form-leads. Это public метод понижения PAT анонимного контекста и разрешает live form. Это не гарантирует is_test или подавленный delivery. Нет полного безопасный PAT-dev submit/read/delete петля; использовать изолированную локальную среду или подтверждено owner's dev сессия. include_test только изменить список фильтрации.

4.8 Уведомления, веб-хуки и акцепты

Принято реально leads (не спам, не дедуктивные повторы или dev-preview испытания) notify submit.targets: email цели, или owner's email Когда цели не set; Telegram использует чат ids или названия каналов. Соединение ботов принадлежит тот shop и конфигурируется через owner/admin только сеансовая орг Telegram settings, не через PAT и never в form schema. Пропавший бот молча Предотвратить Telegram delivery; Свинец остается принятым. Сбои доставки не склад.

confirmToSender:true Электронные письма, представленные email field Если есть, то промах. email не дает никаких подтверждений и не принимает error. Ежедневный лимит подтверждения limits только письмо с подтверждением, а не уведомление о лидере или продавце.

lead.created payload содержит lead_id,form_id,form_name,values,page_url,utm, created_at; values/UTM Здесь уже есть объекты, а не транспортная база64. явно test-lead path Также испускает это event, с test:true и нет page URL. Получатель не должен создавать реальную сделку от test event. Контроль подписки только сеанс; PAT cannot Управление подписками с forms/leads scopes. Подпись, повторы и дедупликация приемника event id: /docs/webhooks.

Прием: перечитывать schema и active Проверить, что сделано widget/opener, required fields посетитель consent; проверить анонимность public прогноз after авторизованная публикация (a) new dev-только form Правильное использование анонимного 404); Выберите и проверьте test storage/delivery Расскажи отдельно. owner который CRM Совет по проверке и что test leads есть hidden через default. голый HTTP 200 или ok:true не доказывают ни хранение, ни уведомление delivery.

5.Безмолвно ignored

неизвестный schema Ключи выживают при хранении, но могут не иметь рендеринга effect; сохранять Неизвестные рендеринговые числа возвращаются, числовая внешность values зажаты. Unknown/non-string/service/file свинец values и неподдерживаемый UTM Ключи отбрасываются. Foreign/dead banner files Решимость в отношении empty URL. пустой widget form ids render нет widget; зарезервированный vz-lead У него нет хозяина. schema title и а heading field render Дважды. Инвалид forms return ok:false; antispam, Ежедневные и последовательные дублирующие пути могут return Успех без успеха а new Недействительные сообщения с моста drop с warnings; недействительные пары и reqId фильтруется, как описано в § 4.5. Пропущенное соединение Telegram или подтверждение email Предотвращает только это уведомление.

6. Пределы

Ниже приведены существующие контракты limits, не подняты в этой документации. План на время выполнения limits такой как forms_max Пришел из того, shop's План; а draft делать не обходить стороной form Ограничение уровня потребления в общественных местах отделено от нормы API limits: уважение RATE_LIMITED и Retry-After.

{
  "schema_bytes":65536,"fields":64,"field_key_bytes":64,
  "field_text_bytes":255,"options_per_field":64,
  "lead_body_bytes":65536,"lead_value_characters":4096,
  "utm_value_bytes":200,"page_url_characters":2048,"user_agent_characters":512,
  "notification_targets":10,"target_bytes":255,"confirmation_text_bytes":2000,
  "forms_page_default":50,"leads_page_default":20,"page_limit_max":100,
  "export_rows":10000,"settings_bytes":4096,
  "deadline_days":[1,365],"column_limit":[1,1000],"auto_hide_days":[1,365],
  "bridge_pairs":64,"bridge_value_utf16_units":4096,"bridge_payload_bytes":65536,
  "bridge_req_id_utf16_units":128,"spam_elapsed_ms":[1,1999],
  "dedup_window_seconds":60,"daily_leads_default":500,
  "daily_confirmation_emails":200,"retention_days_default":365
}

Маркеры ошибок: FORM_SCHEMA_INVALID, FORM_VALIDATION_FAILED (400); FORM_NOT_FOUND, FORM_LEAD_NOT_FOUND (404); FORM_CODE_TAKEN (409); FORM_LIMIT_REACHED, RATE_LIMITED (429) Недействительные статусы или транспорт sizes неудачный validation. Пропавший scopes и contour провальный before операции.

7.Как это было проверено

Источник: 2026-10-25: API заявления, scope whitelist/sensitive scopes, Методы охраны и PAT контуры; form schema валидатор; create/edit/list/public form управляющие; public прием, test представление, export и CRM переходный период управляющие; HTML дезинфицирующее средство и form Проверил внутренний мост. forms рабочий процесс против этих исполняемых контрактов; нет внутреннего рабочего процесса path является частью из этого public API. Общественные маршруты, source/copy Синхронизация, регистрация территории и паспортные ссылки покрываются тестами на обнаружение., уведомления, публикации или production были написаны для этого обзора.