Подтверждение номера звонком

Вы отправляете номер — мы звоним и сбрасываем после первого гудка. Код — последние 4 (или 6) цифр номера, с которого пришёл звонок. Его мы возвращаем сразу в ответе, а итог звонка присылаем вебхуком.

Быстрый старт

Один запрос: номер абонента в любом формате. В ответе — код, который увидит пользователь.

curl -X POST https://flashcall.crmcalls.ru/api/v1/flash-calls \
  -H "Authorization: Bearer $FLASHCALL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+7 916 123-45-67"}'

Покажите пользователю поле для 4 цифр и сравните введённое с code из ответа.

Авторизация

Ключ создаётся в кабинете в разделе «API-ключи» и передаётся в заголовке Authorization: Bearer. Держите ключ на сервере: из мобильного приложения или браузера вызывать API нельзя.

Создать звонок

POST /api/v1/flash-calls

Поле	Описание
phone	Мобильный номер РФ: +79161234567, 89161234567, 9161234567 — приведём сами
callback_url	Необязательно. Адрес вебхука для этого звонка вместо адреса из настроек
voice	Необязательно. true — если абонент ответит, зачитаем код голосом (тариф: вызов + секунды + синтез); false — только код в номере, фиксированная цена. По умолчанию — как в настройках аккаунта

Ответ 201 Created (200 — если это повтор с тем же Idempotency-Key):

{
  "data": {
    "id": "4a5a4cae-4567-4086-baea-b82d34355049",
    "phone": "79161234567",
    "code": "4731",
    "status": "queued",
    "reason": null,
    "operator": "mts",
    "voice": false,
    "charged_kop": 0,
    "created_at": "2026-10-23T09:48:51.160Z",
    "finished_at": null
  }
}

Статус звонка

GET /api/v1/flash-calls/{id}

Тот же объект, что и при создании, с текущим статусом. Удобно, если вебхуки не используете.

Статусы

status	Что значит	Деньги
queued	Принят, ждёт очереди на звонок	Резерв
dialing	Звоним	Резерв
delivered	Был гудок, звонок сброшен — код на экране абонента	Списано
answered	Абонент ответил — код продиктован голосом	Списано
failed	Не дошёл. Причина в reason: busy, unavailable, no_ringing, invalid_number — звонок был; остальные — сбой сети	Звонок был — списано, сбой сети — возвращено
expired	Не успели позвонить за 30 секунд	Возвращено
sms_sent	Звонок не дошёл, код отправлен SMS (если включено)	+ цена SMS
sms_failed	SMS тоже не ушло	SMS — возвращено

Возможные reason у failed: busy, no_ringing, unavailable, rejected, invalid_number, congestion, network_error.

Вебхуки и подпись

На каждый итоговый статус придёт POST на адрес из настроек кабинета. Ответьте 2xx — иначе повторим через 5 с, 30 с, 2 мин, 10 мин, 1 ч и 3 ч.

POST https://your.app/hooks/flashcall
X-Flashcall-Signature: t=1792750000,v1=5f1c9e…

{ "event": "flash_call.status", "data": { "id": "…", "status": "delivered", "code": "4731", … } }

Проверяйте подпись: HMAC-SHA256 от строки {t}.{тело запроса} секретом из кабинета. Метка времени не старше 5 минут.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, rawBody, header) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const actual = Buffer.from(v1, "hex");
  return actual.length === expected.length && timingSafeEqual(actual, expected);
}

Повторы запросов

Передайте заголовок Idempotency-Key (до 128 символов, например id попытки регистрации). Повтор с тем же ключом вернёт тот же звонок и не позвонит второй раз — безопасно ретраить при таймаутах сети.

Ошибки и лимиты

{ "error": { "code": "rate_limited", "message": "…", "details": { "retry_after_ms": 600000 } } }

HTTP	code	Когда
401	unauthorized	Нет ключа или он отозван
402	insufficient_funds	Не хватает денег на балансе
403	forbidden	Аккаунт заблокирован
422	validation_failed	Неверный номер или тело запроса; подробности в details
429	rate_limited	Больше 3 звонков на номер за 10 минут или превышен лимит запросов в минуту
503	no_route / no_free_number	Временно нет маршрута или свободного номера — повторите позже

Не больше 3 звонков на один номер за 10 минут — защита от перебора и накрутки. Вопросы по интеграции: help@crmcalls.ru.