Подключите сайт, не раскрывая его ключ.

Установите современный ESM-пакет

leadpending-web работает только как ESM, не имеет runtime-зависимостей и рассчитан на современные сборщики и Node.js 18.13+. Импортируйте только публичные точки входа: leadpending-web, leadpending-web/browser и leadpending-web/server. В npm-пакете также лежит INTEGRATION.md — автономное задание для coding agents.

npm install leadpending-web

Проверьте форму и соберите визит

Вызывайте trackPageView() при каждой навигации. Он безопасно хранит в sessionStorage до 200 шагов, первый referrer, страницу входа, начало сессии и стандартные UTM/gclid/fbclid; collectVisitor() добавляет актуальный контекст браузера при отправке. checkSubmission() только возвращает вердикт: вы решаете, остановить ли заполненный honeypot, неотрицательное время меньше 1200 мс, пустое сообщение, текст короче 3 кодовых точек Unicode или минимум 4 одинаковых непробельных символа.

import { checkSubmission, newIdempotencyKey } from 'leadpending-web'
import { collectVisitor, trackPageView } from 'leadpending-web/browser'

// Run on every page navigation. The SDK keeps this tab's journey in sessionStorage.
trackPageView()

// Generate once for this user submission and keep it if your own POST is retried.
const submissionId = newIdempotencyKey('contact')
const verdict = checkSubmission({
  message: form.message.value,
  honeypot: form.company_url.value,
  elapsedMs: Date.now() - formShownAt,
})
if (!verdict.ok) return

await fetch('/api/contact', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    submissionId,
    name: form.name.value,
    email: form.email.value,
    message: form.message.value,
    pageUrl: location.href,
    visitor: collectVisitor(),
  }),
})

Создайте заявку из server-only кода

LeadPendingClient отправляет application/json на https://api.leadpending.com/api/v1/leads. Передайте объект visitor из браузера, а IP, user-agent и страну с edge, которые видел ваш сервер, добавьте через connection; непустые connection-поля перекрывают соответствующие поля visitor, не мутируя исходный объект. LeadPending — единственное хранилище заявки: не зеркальте её в локальную строку или событие и не используйте локальный fallback. Сообщайте браузеру об успехе только после завершившегося createLead.

import { LeadPendingClient, LeadPendingError } from 'leadpending-web/server'

const leadpending = new LeadPendingClient({
  apiKey: process.env.LEADPENDING_API_KEY!,
})

export async function POST(request: Request) {
  const form = await request.json()

  try {
    const lead = await leadpending.createLead(
      {
        external_id: form.submissionId,
        name: form.name,
        email: form.email,
        message: form.message,
        page_url: form.pageUrl,
        visitor: form.visitor,
      },
      {
        idempotencyKey: form.submissionId,
        connection: {
          ip: request.headers.get('x-real-ip') ?? undefined,
          userAgent: request.headers.get('user-agent') ?? undefined,
          country: request.headers.get('cf-ipcountry') ?? undefined,
        },
        signal: request.signal,
      },
    )
    return Response.json({ accepted: true, replay: lead.replay })
  } catch (error) {
    if (error instanceof LeadPendingError) {
      console.error('LeadPending rejected lead', { status: error.status, code: error.code })
    }
    return Response.json({ accepted: false }, { status: 502 })
  }
}

Для production рекомендуется SDK. Этот эквивалентный raw-запрос нужен, чтобы независимо проверить endpoint и заголовки; он тоже выполняется только с доверенного сервера, никогда не из браузера.

curl --request POST 'https://api.leadpending.com/api/v1/leads' \
  --header 'Authorization: Bearer lp_live_<server-secret>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: contact-018f47f2' \
  --data '{
    "external_id": "contact-018f47f2",
    "name": "Jane Doe",
    "email": "[email protected]",
    "message": "Can you help with three websites?",
    "page_url": "https://example.org/pricing",
    "locale": "en",
    "metadata": { "budget": "3000-5000" },
    "visitor": { "country": "DE", "utm": { "utm_source": "google" } }
  }'

Храните заявку в одном месте и удаляйте по external_id

Не записывайте payload acquisition-формы в базу продукта. Отдельный локальный аккаунт допустим: выводите стабильный external_id из его ID без таблицы соответствий заявок. При удалении сначала вызовите site-scoped DELETE, затем удаляйте аккаунт. Метод мягко удаляет только активный лид точного сайта этого API-ключа, повторно отвечает 204 для уже отсутствующего ID и никогда не принимает браузерный ключ.

curl --request DELETE \
  'https://api.leadpending.com/api/v1/leads/by-external-id?external_id=contact-018f47f2' \
  --header 'Authorization: Bearer lp_live_<server-secret>'

# 204 No Content. Repeating the same request is also 204.

Проверьте настоящий payload без создания заявки

validateLead использует ту же авторизацию, строгое декодирование, проверку полей, нормализацию visitor и оценку спама, что и боевой приём. Он возвращает вычисленные subject и locale, очищенный visitor, spam_score и spam_reasons, но не создаёт лид, сообщение или уведомление. До запуска прогоните характерный production-payload с настоящим ключом сайта.

const preview = await leadpending.validateLead(
  {
    email: '[email protected]',
    message: 'Can you help with three websites?',
    visitor: { country: 'XX', ip: '203.0.113.77' },
  },
  { connection: { userAgent: 'integration-test' } },
)

// No lead or notification was created:
// {
//   would_accept: true,
//   subject: 'Inquiry from Example',
//   locale: 'en',
//   visitor: { ip: '203.0.113.77', user_agent: 'integration-test' },
//   spam_score: 0
// }

Поля заявки и жёсткие лимиты

Контекст посетителя: доверьте сбор SDK

Используйте trackPageView() и collectVisitor(), а не поддерживайте второй ручной collector. Все свойства необязательны. Типы JSON и неизвестные поля строго проверяются при декодировании тела; после этого неверные по формату или слишком большие значения телеметрии удаляются или обрезаются и не отклоняют в остальном валидную заявку.

Нормализованный visitor ограничен 48 КиБ. Если он больше, сервер удаляет самые старые шаги journey, пока объект не поместится; если этого недостаточно, удаляет visitor целиком. Пустой объект не возвращается. Для сырого тела запроса действует жёсткий лимит 64 КиБ, а неизвестные JSON-поля и неверные JSON-типы вернут 400 до этой best-effort очистки.

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

Новая заявка возвращает 201. Совпадение по Idempotency-Key или external_id возвращает существующую заявку с 200; LeadResult.replay вычисляется из статуса. Оба ответа имеют вид { data: { id, status, created_at }, request_id }. Принятой считается только заявка, для которой SDK успешно разобрал 2xx; некорректные данные в 2xx возвращаются как INVALID_RESPONSE.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "data": {
    "id": "0198…",
    "status": "pending",
    "created_at": "2026-08-02T12:00:00Z"
  },
  "request_id": "0198…"
}

Типизированные сбои и HTTP-коды

Корректный non-2xx ответ API выбрасывает LeadPendingError со status, code и безопасным синтетическим message; details и request_id сервера SDK наружу не отдаёт. Сетевой сбой остаётся исходной ошибкой, отмена — AbortError или явная signal.reason. Логируйте только status и code, никогда не ключ, email, message или visitor.

Оценка спама и проверка e-mail

Спам-сигналы только классифицируют и никогда не отклоняют структурно валидную заявку. Новый реальный лид сохраняется даже с высоким скором, а решение остаётся за оператором.

checkSubmission() — отдельный браузерный preflight-классификатор. Он возвращает только первую сработавшую причину: honeypot_filled, submitted_too_fast, message_empty, message_repeated_character или message_very_short. Останавливать отправку или нет, решает вызывающий код.

На приёме сервер обрезает message, считает осторожные текстовые сигналы и проверяет, есть ли у домена e-mail MX либо, как fallback, A/AAAA. DNS ограничен 2 секундами, результат кэшируется на 30 минут. Таймаут или временный сбой резолвера обрабатывается fail-open и не добавляет сигнал.

Скор считается как P = 1 − Π(1 − Pi) и ограничен сверху 0.99. Значение 0.5 и выше показывается в кабинете как подозрительное. validateLead возвращает тот же скор и стабильные коды причин до запуска.