Техническая документация

Подключите заявки с сайта к MAX и email

Готовая схема интеграции для HTML-форм, JavaScript, CMS и CRM. Создайте форму в боте, получите ключ и отправляйте обращения единым POST-запросом.

POST /api/send.php
{
  "form_key": "YOUR_FORM_KEY",
  "comment": "Хочу консультацию"
}
Заявка сохранена
Быстрый старт

Три шага до первой заявки

01

Создайте форму в боте

В MAX отправьте команду /form Название формы. Бот вернёт уникальный form_key и ссылку Webhook.

02

Отправьте POST-запрос

Передайте данные формы на endpoint ниже. Обязательное поле только одно: form_key. Имя, телефон и email можно не указывать.

03

Проверьте уведомления

При активной оплаченной подписке команда получит заявку в MAX и по email. Ответ success: true подтверждает сохранение заявки.

Endpoint

Адрес для отправки

POST /api/send.php принимает JSON, application/x-www-form-urlencoded и multipart/form-data.

https://n.vlkstudio.ru/api/send.php
Примеры запросов

Выберите подходящий способ

HTML

Обычная форма

<form action="https://n.vlkstudio.ru/api/send.php" method="post">
    <input type="hidden" name="form_key" value="YOUR_FORM_KEY">
    <input name="name" placeholder="Имя">
    <input name="phone" placeholder="Телефон">
    <textarea name="comment" placeholder="Текст заявки"></textarea>
    <button type="submit">Отправить</button>
</form>

Форма откроет JSON-ответ. Для отправки без перехода используйте fetch или обработчик на своём сервере.

JS

JavaScript / JSON

Для другого домена сначала настройте разрешённый origin — подробности ниже.

const payload = {
    form_key: 'YOUR_FORM_KEY',
    comment: 'Хочу консультацию',
    idempotency_key: crypto.randomUUID()
}; // При повторе отправьте этот же payload и ключ.

async function sendLead(payload) {
    const response = await fetch('https://n.vlkstudio.ru/api/send.php', {
        method: 'POST',
        credentials: 'omit',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(payload)
    });
    const result = await response.json();
    if (!response.ok || !result.success) {
        throw new Error(result.message || 'Не удалось сохранить заявку');
    }
    return result;
}
sendLead(payload).then(console.log).catch(console.error);
Поля заявки

Какие данные можно отправлять

Поле Назначение
form_keyОбязательный ключ формы из команды /form.
nameИмя клиента. Все контактные поля необязательны.
phoneТелефон для связи.
emailEmail клиента; не используется как адрес доставки уведомлений.
messagecommentcommentsquestiontextсообщениекомментарийСвободный текст заявки. Можно отправить без name, phone и email; он попадёт в MAX и письмо дословно. Выбирается первое непустое поле в указанном порядке.
titleformНазвание заявки: приоритет у title, затем form; по умолчанию «Новая заявка».
sourceutm_sourceИсточник: приоритет у source, затем utm_source; по умолчанию site.
idempotency_keyexternal_idУникальный ID заявки для защиты от дублей; приоритет у idempotency_key. При повторе отправляйте тот же ID.
Другие поляПроизвольные поля и UTM-метки. Массивы превращаются в JSON-строки. Пробелы по краям обычных значений удаляются; свободный текст сохраняется полностью.
keycompany_idСохранены для совместимости. Для новой интеграции используйте form_key: компания, сайт и форма определятся по ключу.
200

Успешный ответ

{
    "success": true,
    "duplicate": false,
    "lead": {
        "id": "L-000001"
    }
}

Сокращённый пример. Полный ответ также содержит данные заявки, company и recipients. Получение success: true означает сохранение, а не гарантию доставки уведомлений.

Дубль: HTTP 200, duplicate: true и прежний lead. Повторной доставки нет. Без ID используется SHA-1 исходного payload — сохраняйте значения и порядок полей при повторе.

400

Ошибки приёма

{"success": false,
 "message": "Empty lead payload"}

{"success": false,
 "message": "Company or form key not found"}

HTTP 400: пустой payload/неразобранный JSON без других параметров либо неизвестная форма/компания. Ошибки MAX и SMTP записываются отдельно и не меняют успешный ответ сохранённой заявки.

  • Проверьте, что form_key скопирован полностью.
  • Отправляйте запрос методом POST.
  • Для JSON укажите заголовок Content-Type: application/json.
  • Откройте в боте команду /forms и убедитесь, что форма существует.
PHP

Серверный cURL

Отправьте заявку с сервера своего сайта. CORS не требуется. Сохраните external_id при повторе запроса и обрабатывайте ошибки на своём сервере.

<?php
$payload = [
    'form_key' => 'YOUR_FORM_KEY',
    'comment' => 'Хочу консультацию',
    'external_id' => 'order-123', // ID вашей заявки, сохраняется при повторе.
];
$ch = curl_init('https://n.vlkstudio.ru/api/send.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
$error = curl_error($ch);
curl_close($ch);
if ($body === false) {
    throw new RuntimeException('Ошибка соединения: ' . $error);
}
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($status !== 200 || empty($result['success'])) {
    throw new RuntimeException((string) ($result['message'] ?? 'Ошибка API'));
}
$leadId = $result['lead']['id'];
JS

Доступ с другого домена

Для браузерного fetch администратор добавляет точный origin стороннего сайта в integration_allowed_origins файла data/settings.json:

{
    "integration_allowed_origins": [
        "https://example.ru"
    ]
}

Укажите схему, домен и порт, без пути и завершающего слеша. По умолчанию список пуст. Запрос OPTIONS возвращает HTTP 204; CORS-заголовки выдаются только разрешённым доменам. Cookies не нужны.

Обычная HTML-форма и серверный cURL работают без CORS. Используйте действительный form_key во всех вариантах. CORS управляет чтением ответа браузером и не заменяет ключ формы.

MAX и email

Доставка команде компании

Получатели совпадают с MAX: активный владелец и сотрудники, с учётом доступа к сайту и форме. Нужна действующая оплаченная подписка. После оплаты отложенные заявки доставляет штатный механизм повторов.

@

Адреса получателей

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

Администратор задаёт резервные адреса по ID компании в data/settings.json:

{
    "company_notification_emails": {
        "1": "team@example.ru",
        "2": "sales@example.org"
    }
}

На общий адрес приходит одна копия заявки. Email клиента из формы не влияет на выбор получателей. Письмо в UTF-8 содержит тот же текст, что MAX: ID, компанию, источник, название формы, поля и блок «Сообщение».

Если адреса нет, в журнале будет skipped / email_missing; без SMTP — skipped / smtp_not_configured. После настройки недоставленные письма доступны для повторной доставки.

SMTP

Почта отправителя

Настройки задаёт администратор в data/settings.json. Они относятся к отправителю сервиса и не передаются сторонним сайтом в заявку.

  • smtp_host — SMTP-сервер; пустой адрес отключает отправку.
  • smtp_port — 587 по умолчанию; для SSL обычно 465.
  • smtp_username и smtp_password — учётные данные. Пустой username отключает авторизацию SMTP.
  • smtp_encryption — tls (STARTTLS), ssl (SMTPS) или пустая строка для сервера без обязательного шифрования; доступный STARTTLS используется автоматически.
  • smtp_from_email — корректный адрес отправителя; smtp_from_name — его имя, по умолчанию VLK FormBot.
  • smtp_timeout — таймаут операций SMTP, по умолчанию 10 секунд.

Ошибка email не мешает MAX и наоборот. Журнал хранит отдельные статусы каналов; повторяется только неудавшийся канал. Повторный POST с тем же ID не запускает повтор уведомлений.

Нужна наглядная инструкция?

Посмотрите настройку бота по шагам