ru
Бесплатный просмотр

Интеграция API WhatsApp OTP: примеры на PHP, Node.js и Python

Автор: Команда WapFlow · 16 ноября 2026 · 6 мин чтения
Редактор кода с вызовом API WhatsApp OTP и сообщением с кодом подтверждения на телефоне

Отправка кода подтверждения через WhatsApp сводится к двум вызовам API WapFlow OTP: один отправляет код, другой проверяет то, что ввёл пользователь. В этом руководстве мы собрали принцип работы API, примеры на cURL, PHP, Node.js и Python, обработку ошибок и моменты безопасности, на которые стоит обратить внимание. Примеры следуют формату из официальной документации API, с небольшими дополнениями для удобства чтения. Если вы ещё не знаете, что представляет собой продукт, прежде чем начать писать код, сначала прочитайте статью «Что такое WhatsApp OTP».

Основы

  • Базовый URL: https://wapflow.net/api/otp/v1
  • Аутентификация: заголовок Authorization: Bearer <key> в каждом запросе. Боевые ключи начинаются с wfo_live_, тестовые — с wfo_test_.
  • Формат ответа: { "success": true, ... } при успехе, { "success": false, "error": { "code": "...", "message": "..." } } при ошибке.
  • Номер телефона: с кодом страны, например 905321234567. API оставляет только цифры (знаки +, пробелы и дефисы удаляются) и ожидает от 10 до 15 цифр. Одиннадцатизначные номера, начинающиеся с 0, считаются турецкими, и к ним спереди добавляется 90.

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

Четыре конечные точки

Конечная точкаНазначение
POST /sendГенерирует код и отправляет его через WhatsApp. Параметр phone обязателен; необязательные — code_length (4–8), ttl (60–900 с), lang, app_name.
POST /verifyПроверяет код, введённый пользователем. Параметры phone и code обязательны; если передан request_id, проверяется именно этот запрос.
GET /status/:request_idВозвращает статус запроса: queued, sent, delivered, read, failed, verified, expired.
GET /meПоказывает, действителен ли ключ, тариф, количество подключённых аккаунтов и использование квоты за этот месяц.

После 5 неверных попыток запрос блокируется, а подтверждённый код нельзя использовать повторно. Если не передать request_id, проверяется последний действующий код, отправленный на этот номер с этим ключом. Так как может существовать несколько сессий, рекомендуем сохранять request_id и передавать его при проверке.

Первая попытка с cURL

# 1) send the code
curl -X POST https://wapflow.net/api/otp/v1/send \
  -H "Authorization: Bearer wfo_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"phone":"905321234567","app_name":"Acme"}'

# 2) verify the code
curl -X POST https://wapflow.net/api/otp/v1/verify \
  -H "Authorization: Bearer wfo_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"req_...","phone":"905321234567","code":"123456"}'

Первую попытку сделайте с ключом wfo_test_: сообщение WhatsApp не отправляется, квота не расходуется, а код возвращается в поле test_code ответа.

Пример на PHP

<?php
function wapflow_otp(string $path, array $body): array {
    $ch = curl_init('https://wapflow.net/api/otp/v1' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('WAPFLOW_OTP_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode($body),
    ]);
    $res = json_decode(curl_exec($ch), true) ?: [];
    curl_close($ch);
    return $res;
}

$sent = wapflow_otp('/send', ['phone' => '905321234567', 'app_name' => 'Acme']);
// ... when the user submits the code:
$check = wapflow_otp('/verify', ['request_id' => $sent['request_id'], 'phone' => '905321234567', 'code' => $_POST['code']]);
if (!empty($check['valid'])) { /* signed in */ }

Пример на Node.js

В примере используется встроенный fetch (Node.js 18 или новее), и он должен выполняться как ES-модуль.

const BASE = 'https://wapflow.net/api/otp/v1';
async function otp(path, body) {
  const res = await fetch(BASE + path, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.WAPFLOW_OTP_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });
  return res.json();
}
const sent = await otp('/send', { phone: '905321234567', app_name: 'Acme' });
// ... when the user submits the code:
const check = await otp('/verify', { request_id: sent.request_id, phone: '905321234567', code: '123456' });
if (check.valid) { /* signed in */ }

Пример на Python

import os
import requests

BASE = "https://wapflow.net/api/otp/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["WAPFLOW_OTP_KEY"]}

def otp(path, body):
    return requests.post(BASE + path, json=body, headers=HEADERS, timeout=15).json()

sent = otp("/send", {"phone": "905321234567", "app_name": "Acme"})
# ... when the user submits the code:
check = otp("/verify", {"request_id": sent["request_id"], "phone": "905321234567", "code": "123456"})
if check.get("valid"):
    pass  # signed in

Обработка ошибок

Отправку и проверку обрабатывайте отдельно. Если отправка возвращает success: false, действуйте в зависимости от кода ошибки:

HTTP / кодЧто делать
401 invalid_keyПроверьте ключ; возможно, он отозван или набран с ошибкой.
402 no_subscription, subscription_expiredОформите или продлите подписку.
422 invalid_phoneПопросите пользователя ввести номер заново с кодом страны.
429 rate_limitedПовторите запрос через количество секунд из поля retry_after в ответе.
429 quota_exceededМесячная квота исчерпана; повысьте тариф или дождитесь следующего периода.
429 daily_limit_reachedПодключённые аккаунты достигли дневного лимита; повторите запрос через retry_after (со следующего дня в 00:00 по турецкому времени). Квота не расходуется.
503 no_account_connected, send_failedУбедитесь, что есть подключённый и включённый аккаунт WhatsApp; повторите попытку немного позже.

При проверке ответ HTTP 200 всё равно может содержать valid со значением false. Причину показывает поле reason: invalid_code, expired, too_many_attempts, already_verified или not_found. При неверном коде поле attempts_left показывает, сколько попыток осталось; передача этого значения пользователю улучшает его опыт.

Лимиты запросов и пользовательский опыт

  • На один номер можно получить 1 код за 60 секунд, 5 в час и 10 в день. Добавьте 60-секундный обратный отсчёт на кнопку «Отправить повторно».
  • Лимиты: 60 отправок в минуту на один ключ API, 120 запросов в минуту на один IP-адрес и, для проверки, 10 попыток в минуту на один номер.
  • На отправку влияют дневной лимит и прогрев новых номеров; подробности — в нашей статье о снижении риска блокировки.

Чек-лист безопасности

  • Никогда не используйте ключ API в браузере, мобильном приложении или любом открытом коде; выполняйте вызовы с вашего сервера.
  • Всегда проверяйте код на сервере через /verify; не доверяйте флагу «подтверждено», пришедшему из браузера.
  • Храните ключ в переменной окружения, а не в репозитории.
  • Ставьте собственное ограничение частоты и, при необходимости, CAPTCHA перед отправкой кода: злоупотребления могут съесть вашу квоту.
  • Для критичных действий держите резервный канал (SMS или e-mail). WapFlow OTP — не официальный WhatsApp Business API, и доставка не гарантируется.

Если вы используете WordPress или WooCommerce, можно обойтись без программирования и воспользоваться плагином. Тарифы смотрите на странице цен, обзор продукта — на странице WapFlow OTP.

Часто задаваемые вопросы

Что меняется при переходе в боевой режим?

Только ключ. Тестовый ключ начинается с wfo_test_, а правила отправки и лимитов у него такие же, как у боевого ключа; действующая подписка всё равно нужна.

Обязательно ли передавать request_id?

Нет, но рекомендуется. Если его не передать, проверяется последний действующий код, отправленный на этот номер.

Можно ли изменить текст сообщения?

Да. В панели можно задать название приложения, шаблон сообщения, длину кода, срок действия и язык. В шаблоне используются переменные {code}, {app} и {minutes}. Для каждого запроса их можно переопределить параметрами app_name, code_length, ttl и lang.

Как узнать, что сообщение доставлено?

Запросите статус через /status/:request_id; вы можете увидеть sent, delivered и read. Информация о доставке зависит от WhatsApp и не гарантируется.

Доступен ли этот API в приложении для Windows?

Нет. WapFlow OTP — отдельный облачный сервис.

Похожие статьи