Каскадная доставка OTP: собираем fallback-цепочку каналов

Ни один канал доставки OTP не даёт 100% доходимости: у кого-то нет Telegram, кто-то не может позвонить, где-то не проходит SMS. Каскад — это цепочка каналов с переходом к следующему при неудаче. Разберём, как собрать её поверх API Verificahub: порядок каналов, функцию sendWithCascade на Node.js и почему неудачные попытки в каскаде не тарифицируются.

Каскадная доставка OTP — это стратегия, при которой код (или подтверждение) отправляется не одним фиксированным способом, а по цепочке каналов: если первый не сработал, автоматически подключается второй, затем третий. Цель двойная — поднять доходимость (кто-то из пользователей всегда выпадает из любого одного канала) и снизить стоимость (дешёвый канал закрывает большинство, дорогой подстраховывает остаток).

Сразу честно: в Verificahub нет «автокаскада» на стороне API. Одна сессия POST /v1/verify использует ровно один method. Каскад вы собираете в своём коде — последовательными вызовами с разными методами и переходом к следующему каналу при неудаче инициации или доставки. Ниже — рабочая схема и код.

Что такое каскадная доставка OTP

Определение и общий разбор термина — в глоссарии: каскадная доставка. Практический смысл прост: у каждого канала своя доходимость и цена. Обратный flash-call бесшовный и самый дешёвый, но требует, чтобы пользователь мог позвонить (иногда мешает корпоративная АТС). Telegram отлично доходит, но только если у человека установлен мессенджер. SMS доходит почти всегда, но дороже и медленнее. Каскад комбинирует их сильные стороны.

Дешёвый канал закрывает большинство пользователей, а запасной подстраховывает остальных — так каскад одновременно повышает доходимость и держит среднюю цену подтверждения низкой.

Почему в Verificahub нет автокаскада — и это нормально

Ответ POST /v1/verify дискриминирован по method: для reverse_flash_call приходит number_to_call (пользователь сам звонит, сессия подтверждается по Caller ID автоматически), для telegram_otp — code_length (код читается в Telegram и проверяется через POST /v1/verify/check). Смешивать методы в одной сессии нельзя — и это удобно: вы полностью контролируете логику перехода и не зависите от «магии» на стороне API.

Переключаться на следующий канал имеет смысл в двух точках:

• На инициации — POST /v1/verify вернул ошибку, означающую, что канал недоступен прямо сейчас (например no_gateway_available, delivery_unavailable для Telegram, provider_error).
• На доставке/подтверждении — сессия начата, но закончилась статусом expired (истёк TTL) или failed; либо пользователь сам нажал «получить код другим способом».

Как выбрать порядок каналов

Базовый принцип — сначала самый дешёвый и бесшовный, потом запасные. Так вы платите за дорогой канал только тогда, когда дешёвый реально не сработал.

• Первым — reverse_flash_call: не нужно вводить код, самый дешёвый метод, от 0,25 ₽.
• Вторым — telegram_otp: высокая доходимость там, где есть мессенджер, от 0,90 ₽ (официальный Telegram Gateway).
• Последним — sms: универсальный запасной канал, доходит почти везде.

Когда переходить к следующему каналу

Ошибки приходят в формате RFC-7807 со стабильным полем error_code — ветвитесь по нему, а не по тексту `detail`. Не любую ошибку стоит «лечить» сменой канала: неверный номер или пустой баланс новый канал не спасёт.

Второй триггер — жизненный цикл сессии sent → delivered → verified | expired | failed. Если после инициации статус дошёл до expired или failed, это сигнал эскалировать на следующий канал. Узнавать статус лучше через webhook (события verification.*, подпись HMAC-SHA256), а не опросом.

Функция sendWithCascade на Node.js

Собираем ядро каскада — инициацию с переходом по каналам. Ключи читаем из окружения, авторизация — HTTP Basic. Функция возвращает первую успешно начатую сессию либо бросает исключение, если варианты кончились.

import 'dotenv/config'

const API = 'https://api.verificahub.ru/v1'
const AUTH =
  'Basic ' + Buffer.from(`${process.env.VH_KEY}:${process.env.VH_SECRET}`).toString('base64')

// Порядок каскада: сначала самый дешёвый и бесшовный, затем запасные.
const CASCADE = ['reverse_flash_call', 'telegram_otp', 'sms']

// error_code, при которых канал недоступен «прямо сейчас» — берём следующий.
const FALLBACK_CODES = new Set([
  'no_gateway_available',
  'delivery_unavailable',
  'provider_error',
  'pricing_unavailable',
])

async function initiate(phone, method) {
  const res = await fetch(`${API}/verify`, {
    method: 'POST',
    headers: { Authorization: AUTH, 'Content-Type': 'application/json' },
    body: JSON.stringify({ phone_number: phone, method, expiry_seconds: 180 }),
  })
  return { ok: res.ok, data: await res.json() }
}

// Инициируем проверку, спускаясь по каскаду. Возвращаем первую начатую сессию.
async function sendWithCascade(phone, channels = CASCADE) {
  let lastProblem
  for (const method of channels) {
    const { ok, data } = await initiate(phone, method)
    if (ok) return { method, ...data } // { method, request_id, number_to_call?, code_length?, ... }

    lastProblem = data
    // «Чинимые» ошибки (неверный номер, нет баланса, rate limit) — каскад не поможет.
    if (!FALLBACK_CODES.has(data.error_code)) break
    // Иначе канал недоступен — пробуем следующий. Неудачная инициация не тарифицируется.
  }
  throw Object.assign(new Error('cascade exhausted'), { problem: lastProblem })
}

export { sendWithCascade, CASCADE }

Дальше действуйте по методу вернувшейся сессии: для reverse_flash_call покажите пользователю number_to_call, для telegram_otp/sms — попросите ввести код и проверьте его через POST /v1/verify/check.

Эскалация при неудачной доставке

Если канал начался, но не привёл к подтверждению (истёк TTL, статус expired/failed, или пользователь попросил другой способ), переходим на оставшиеся каналы — снова через sendWithCascade, но уже с «хвостом» списка.

// Каналы после текущего — для перехода при expired/failed или по кнопке «другой способ».
const nextChannels = (current) => CASCADE.slice(CASCADE.indexOf(current) + 1)

// Проверка кода — только для telegram_otp и sms.
// reverse_flash_call подтверждается автоматически, /v1/verify/check ему не нужен.
async function check(requestId, code) {
  const res = await fetch(`${API}/verify/check`, {
    method: 'POST',
    headers: { Authorization: AUTH, 'Content-Type': 'application/json' },
    body: JSON.stringify({ request_id: requestId, code }),
  })
  return { ok: res.ok, data: await res.json() } // 200 { status:'verified' } | 400 invalid_code
}

// Эскалация: сессия истекла/провалилась — берём следующие каналы.
async function escalate(phone, currentMethod) {
  const rest = nextChannels(currentMethod)
  if (rest.length === 0) return null // каналы кончились — показываем поддержку
  return sendWithCascade(phone, rest)
}

Детали интеграции каждого канала разобраны отдельно: верификация по звонку на Node.js и Telegram-верификация на Next.js. Каскад просто оркеструет то, что описано в этих гайдах.

Биллинг: сколько на самом деле стоит перебор каналов

Модель оплаты — за результат, со списанием при доставке (charge-on-delivery): неудачная инициация не тарифицируется. Поэтому переход к следующему каналу после ошибки инициации (no_gateway_available, delivery_unavailable, provider_error) бесплатен — за канал, который даже не начал доставку, вы ничего не платите.

Списание происходит в момент доставки, а не подтверждения. Если канал уже доставил код или звонок, он будет оплачен, даже если пользователь так и не подтвердился (expired/failed) — и следующий канал, если вы эскалируете, тоже. Отсюда правило порядка: дешёвый бесшовный канал первым удерживает среднюю стоимость подтверждения минимальной, а за дорогой Telegram или SMS вы платите только когда до них реально дошла очередь. Актуальные цены по каналам — на странице тарифов.

Коротко

• Автокаскада в API нет: одна сессия = один method, цепочку строите в своём коде.
• Порядок — от дешёвого и бесшовного к универсальному: reverse_flash_call → telegram_otp → sms.
• Переходите к следующему каналу по error_code инициации или по статусу expired/failed, а не по тексту detail.
• Оплата за результат со списанием при доставке: неудачная инициация бесплатна, но уже доставленный канал тарифицируется — поэтому дешёвый бесшовный канал ставим первым.