Документация API

API URL: https://api.fcall.kz

1. /v1/flash-call/send

Создаёт flashcall-запрос. На указанный номер совершается звонок с виртуального номера. В ответ возвращается ключ проверки и, при необходимости, PIN-код.

Входящие параметры (POST, JSON):
Требуется заголовок:
Authorization: Bearer {api_token}
Как получить API токен?

Каждому пользователю, прошедшему регистрацию, выдается персональный api_token, который используется для авторизации во всех запросах к API.

  • Перейдите в Личный кабинет по адресу https://fcall.kz/auth/
  • Откройте раздел API токен
  • Скопируйте ваш токен и используйте его в заголовке Authorization во всех запросах
  • При необходимости вы можете сбросить токен — он будет сгенерирован заново

Пример заголовка: Authorization: Bearer 123456abcdef...

Пример запроса:
POST /v1/flash-call/send
Content-Type: application/json
Authorization: Bearer your_api_token

{
    "phone": "+77012345678"
}
Пример ответа:
{
  "verification_key": "a1b2c3d4e5f6g7h8",
  "client_number": "+77012345678",
  "created_at": "2025-07-17 13:45:21",
  "pin": "8754" // если return_pin включён
}
Рекомендация по безопасности при использовании return_pin

Если вы используете параметр return_pin=true в методе /send, настоятельно рекомендуем не ограничиваться проверкой PIN на своей стороне.

Для полной безопасности всегда используйте метод /verify, так как он:

  • проверяет verification_key, привязанный к каждой попытке;
  • защищает от перебора PIN-кодов (ограничение по попыткам);
  • учитывает срок действия кода (expires_at);
  • возвращает точный статус: verified, incorrect_pin, expired, failed и др.

Без вызова /verify вы теряете встроенные механизмы безопасности и рискуете подвергнуться атаке через перебор кода.

2. /v1/flash-call/verify

Проверяет правильность введённого PIN-кода, используя verification_key, полученный из метода /send.

Входящие параметры (POST, JSON):
Требуется заголовок:
Authorization: Bearer {api_token}
Пример запроса:
POST /v1/flash-call/verify
Content-Type: application/json
Authorization: Bearer your_api_token

{
  "verification_key": "a1b2c3d4e5f6g7h8",
  "pin": "8754"
}
Возможные ответы:
// Успешная верификация
{
    "status": "verified"
}

// Неверный PIN, есть ещё попытки
{
  "status": "incorrect_pin",
  "attempts_left": 1
}

// Попытки закончились
{
  "status": "failed",
  "attempts_left": 0
}

// Срок действия истёк
{
  "status": "expired",
  "expires_at": "2025-07-17 13:50:00"
}

// Уже подтверждён ранее
{
  "status": "already_verified",
  "verified_at": "2025-07-17 13:47:30"
}

Параметры безопасности верификации — такие как время жизни PIN-кода, максимальное число попыток, а также поведение при включённом режиме return_pin — можно гибко настроить в Личном кабинете.