Приём SMS-кодов на Node.js
Здесь вы найдёте полный пример работы с API приёма SMS Turonay через встроенный в Node.js 18 и новее fetch: купите номер, опросите статус до прихода SMS-кода, затем завершите или отмените активацию. Turonay работает по протоколу handler_api, поэтому этот код совместим и с ботами и библиотеками на том же протоколе.
HTTP-пакеты не нужны; Express устанавливается только для приёмника вебхуков. Страница начинается с запроса баланса, затем разбирает полный сценарий на async/await, JSON-методы, повторный запрос SMS, вебхук с проверкой подписи и таблицу ошибок. Обзор смотрите на странице SMS API, а подробности параметров — в Документация API.
Предварительные условия
Перед началом должны быть готовы три вещи:
- API-ключ: после регистрации он лежит в разделе API вашего профиля. Ключ позволяет тратить ваш баланс, поэтому используйте его только в серверном коде Node.js, читайте из
process.envи никогда не отправляйте в браузер. - Баланс:
getNumberрезервирует цену; суммы указаны в турецких лирах (TRY). - Node.js 18 или новее:
fetchиAbortSignal.timeoutвстроены.
EARLY_CANCEL_DENIED.Подготовка: без зависимостей
Проверьте версию Node.js и сохраните ключ в переменную окружения. Пакет express нужен, только если вы запускаете приёмник вебхуков; для вызовов API ничего ставить не требуется. Примеры написаны на CommonJS, так что дополнительная настройка не нужна.
node --version # v18 or newer: fetch() is built in, no HTTP package needed
npm install express # only needed for the webhook receiver below
export TURONAY_API_KEY="paste-your-api-key-here"Первый запрос: узнайте баланс
Самый короткий рабочий пример — запрос getBalance. API принимает GET и отвечает простым текстом, а не JSON: при успехе приходит ACCESS_BALANCE:125.4000, при неверном ключе — BAD_KEY. Не вызывайте res.json(): сначала прочитайте res.text() и примените trim().
// balance.js - run with: node balance.js
const API = "https://turonay.com/stubs/handler_api.php";
async function main() {
const query = new URLSearchParams({
api_key: process.env.TURONAY_API_KEY,
action: "getBalance",
});
const res = await fetch(`${API}?${query}`, { signal: AbortSignal.timeout(20_000) });
const text = (await res.text()).trim(); // plain text, not JSON: "ACCESS_BALANCE:125.4000"
if (text.startsWith("ACCESS_BALANCE:")) {
console.log("Balance (TRY):", text.split(":")[1]);
} else {
console.log("Error:", text); // e.g. BAD_KEY
}
}
main();Полный сценарий на Node.js: получить номер, дождаться кода, закрыть
Скрипт ниже проходит весь жизненный цикл на async/await. getNumber() покупает номер с потолком цены (maxPrice), waitForCode() каждые 5 секунд вызывает getStatus и ждёт не дольше 20 минут, а затем выполняется finish() или cancel(). Имена функций совпадают с референсным Node-клиентом Turonay. Запустите скрипт командой node sms-flow.js.
// sms-flow.js - buy a number, wait for the SMS code, finish or cancel. Node 18+, no packages.
const API = "https://turonay.com/stubs/handler_api.php";
const API_KEY = process.env.TURONAY_API_KEY;
// The API answered with a plain-text error code (NO_BALANCE, NO_NUMBERS, ...).
class ApiError extends Error {}
// Network trouble, HTTP 429 or 5xx, NO_CONNECTION: safe to retry later.
class Transient extends ApiError {}
class CodeTimeout extends Error {}
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function call(action, params = {}) {
const query = new URLSearchParams({ api_key: API_KEY, action });
for (const [key, value] of Object.entries(params)) {
if (value != null) query.set(key, String(value));
}
let res;
try {
res = await fetch(`${API}?${query}`, { signal: AbortSignal.timeout(20_000) });
} catch (err) {
throw new Transient(`network error: ${err.name}`); // never log the URL: it holds your api_key
}
if (res.status !== 200) throw new Transient(`HTTP ${res.status}`);
const text = (await res.text()).trim(); // always trim: bodies are plain text
if (text === "NO_CONNECTION") throw new Transient(text);
return text;
}
async function getBalance() {
const text = await call("getBalance");
if (!text.startsWith("ACCESS_BALANCE:")) throw new ApiError(text);
return text.split(":")[1];
}
// Returns [activationId, phone]. The price is only RESERVED here, not charged.
async function getNumber(service, country, maxPrice = null) {
const text = await call("getNumber", {
service,
country,
maxPrice: maxPrice == null ? null : maxPrice.toFixed(2),
});
const [tag, id, phone] = text.split(":");
if (tag === "ACCESS_NUMBER" && id && phone) return [id, phone];
throw new ApiError(text); // NO_BALANCE, NO_NUMBERS, BAD_SERVICE, WRONG_MAX_PRICE:<price> ...
}
// Returns ["wait" | "ok" | "cancel", code | null].
async function getStatus(id) {
const text = await call("getStatus", { id });
if (text.startsWith("STATUS_OK:")) return ["ok", text.slice("STATUS_OK:".length)];
if (text === "STATUS_CANCEL") return ["cancel", null];
if (text === "STATUS_WAIT_CODE" || text === "STATUS_WAIT_RESEND" || text.startsWith("STATUS_WAIT_RETRY:")) {
return ["wait", null]; // WAIT_RETRY carries the OLD code: still waiting for the new one
}
throw new ApiError(text); // NO_ACTIVATION, BAD_KEY ...
}
const setStatus = (id, status) => call("setStatus", { id, status });
const requestAnotherSms = (id) => setStatus(id, 3); // free, ACCESS_RETRY_GET
const finish = (id) => setStatus(id, 6); // ACCESS_ACTIVATION, only after a code
const cancel = (id) => setStatus(id, 8); // ACCESS_CANCEL / EARLY_CANCEL_DENIED
// Poll every `interval` seconds for at most `timeout` seconds (20 minutes).
async function waitForCode(id, { timeout = 1200, interval = 5 } = {}) {
const deadline = Date.now() + timeout * 1000;
let delay = interval;
while (Date.now() < deadline) {
try {
const [state, code] = await getStatus(id);
delay = interval;
if (state === "ok") return code;
if (state === "cancel") throw new ApiError("STATUS_CANCEL");
} catch (err) {
if (!(err instanceof Transient)) throw err;
delay = Math.min(delay * 2, 60); // back off on HTTP 429 / network trouble
}
await sleep(Math.max(0, Math.min(delay * 1000, deadline - Date.now())));
}
throw new CodeTimeout(`no SMS within ${timeout} seconds`);
}
async function main() {
const [service, country] = ["wa", "62"]; // WhatsApp, Turkey (see getPrices / getCountries)
let id;
let phone;
try {
console.log("Balance (TRY):", await getBalance());
[id, phone] = await getNumber(service, country, 15.0);
} catch (err) {
if (!(err instanceof ApiError)) throw err;
if (err instanceof Transient) console.error("Temporary problem, try again later:", err.message);
else if (err.message.startsWith("WRONG_MAX_PRICE")) console.error("Current price is above your limit:", err.message.split(":")[1] ?? "?");
else if (err.message === "NO_NUMBERS") console.error("No numbers in stock right now, try again in a minute");
else if (err.message === "NO_BALANCE") console.error("Not enough balance, top up first");
else console.error("API error:", err.message);
return 1;
}
console.log(`Use this number: ${phone} (activation ${id})`);
let code;
try {
code = await waitForCode(id);
} catch (err) {
if (err instanceof CodeTimeout) {
const reply = await cancel(id); // nothing is charged when no code arrived
if (reply !== "EARLY_CANCEL_DENIED") {
console.error("Timed out, activation cancelled:", reply);
return 1;
}
code = (await getStatus(id))[1]; // the code arrived in the last second
} else if (err instanceof ApiError) {
console.error("Activation cancelled:", err.message); // STATUS_CANCEL: nothing charged
return 1;
} else {
throw err;
}
}
console.log("SMS code:", code);
console.log(await finish(id)); // ACCESS_ACTIVATION
return 0;
}
main().then((status) => { process.exitCode = status; });Какие случаи обрабатывает скрипт:
- Если текущая цена выше
maxPrice, номер не покупается и возвращаетсяWRONG_MAX_PRICE:<цена>; текущую цену можно прочитать из сообщения об ошибке. NO_NUMBERS— временное отсутствие номеров,NO_BALANCEтребует пополнения. Ошибки сети, HTTP 429 и 5xx помечаются какTransientи повторяются внутри цикла опроса с удваиваемой паузой (до 60 с).STATUS_WAIT_CODEиSTATUS_WAIT_RETRY:<старый код>оба означают «продолжайте ждать»; второй содержит код предыдущего SMS.- Через 20 минут активация отменяется статусом 8; если код пришёл в последнюю секунду, вернётся
EARLY_CANCEL_DENIED, и код будет прочитан заново. Когда код получен, активация закрывается статусом 6.
JSON-методы: getNumberV2 и getStatusV2
Чтобы работать с объектами, используйте getNumberV2: он возвращает JSON, который читается через JSON.parse (поля activationId, phoneNumber, activationCost, currency, activationEndTime). Когда код приходит, getStatusV2 отдаёт JSON с sms.code и sms.text. Однако коды ошибок и в V2 — простой текст, а пока кода нет, getStatusV2 возвращает текстовый статус, поэтому try/catch, который при сбое JSON.parse использует текст как статус, обязателен. Поле activationEndTime задано по времени сервера (Europe/Istanbul, UTC+3) в формате Y-m-d H:i:s без указания часового пояса.
async function getNumberV2(service, country, maxPrice = null) {
const text = await call("getNumberV2", {
service,
country,
maxPrice: maxPrice == null ? null : maxPrice.toFixed(2),
});
try {
return JSON.parse(text); // activationId, phoneNumber, activationCost, activationEndTime ...
} catch {
throw new ApiError(text); // errors stay plain text, even in V2
}
}
// Object with the SMS once it arrived, otherwise the plain-text status (a string).
async function getStatusV2(id) {
const text = await call("getStatusV2", { id });
let data;
try {
data = JSON.parse(text);
} catch {
return text; // STATUS_WAIT_CODE, STATUS_WAIT_RETRY:<old>, STATUS_CANCEL ...
}
return { code: data?.sms?.code ?? null, text: data?.sms?.text ?? null };
}
(async () => {
const order = await getNumberV2("wa", "62", 15.0);
console.log(order.activationId, order.phoneNumber, order.activationCost, "until", order.activationEndTime);
})();Повторное SMS (setStatus 3)
Когда нужно новое SMS на тот же номер, отправьте 3 через setStatus. Это бесплатно, платите вы один раз за активацию. Ответ — ACCESS_RETRY_GET, а пока новое SMS не пришло, getStatus возвращает STATUS_WAIT_RETRY со старым кодом; waitForCode() считает это ожиданием. Закрывайте активацию статусом 6 только после последнего кода. Фрагмент ниже выполняется внутри async-функции.
// Inside an async function: you have a first code and need a second SMS on the same number (free).
const firstCode = await waitForCode(id);
const reply = await requestAnotherSms(id); // setStatus status=3 -> ACCESS_RETRY_GET
if (reply === "ACCESS_RETRY_GET") {
// While the new SMS is on its way getStatus answers STATUS_WAIT_RETRY:<first code>,
// which waitForCode() treats as "still waiting".
const secondCode = await waitForCode(id);
console.log("First:", firstCode, "Second:", secondCode);
}
await finish(id); // close only after the LAST codeПриёмник вебхуков: Express и проверка подписи
Если вам нужны уведомления вместо опроса, укажите HTTPS-адрес вебхука в разделе API вашего профиля (доменное имя, порт 443 или 8443). Когда приходит код (code_received) или активация отменяется (cancelled), вы получаете подписанный JSON POST. Заголовки: X-Turonay-Event, X-Turonay-Timestamp, X-Turonay-Signature и X-Turonay-Delivery, а подпись равна sha256= + HMAC-SHA256(секрет, метка времени + "." + тело запроса).
// webhook.js npm install express | TURONAY_WEBHOOK_SECRET=whsec_... node webhook.js
const crypto = require("node:crypto");
const express = require("express");
const SECRET = process.env.TURONAY_WEBHOOK_SECRET; // whsec_... from your profile page
const seen = new Set(); // demo only: use Redis/DB with a TTL
// sha256=HMAC_SHA256(secret, timestamp + "." + raw body), 5 minute replay window.
function verifyWebhookSignature(secret, timestamp, rawBody, signature, toleranceSec = 300) {
if (!/^[0-9]{1,12}$/.test(timestamp ?? "")) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSec) return false;
const expected = "sha256=" + crypto.createHmac("sha256", secret)
.update(`${timestamp}.`)
.update(rawBody)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from((signature ?? "").trim());
return a.length === b.length && crypto.timingSafeEqual(a, b); // constant time
}
const app = express();
// express.raw keeps the exact bytes; express.json() would re-serialise them.
app.post("/turonay/webhook", express.raw({ type: "*/*", limit: "64kb" }), (req, res) => {
if (!SECRET) return res.sendStatus(500);
const raw = req.body;
if (!Buffer.isBuffer(raw)) return res.sendStatus(400);
if (!verifyWebhookSignature(SECRET, req.get("X-Turonay-Timestamp"), raw, req.get("X-Turonay-Signature"))) {
return res.sendStatus(401);
}
let event;
try {
event = JSON.parse(raw.toString("utf8"));
} catch {
return res.sendStatus(400);
}
if (!seen.has(event.id)) { // retries repeat the same delivery id
seen.add(event.id);
if (event.event === "code_received") {
console.log("code", event.code, "for activation", event.activationId, event.phone);
} else if (event.event === "cancelled") {
console.log("activation", event.activationId, "cancelled, nothing charged");
}
}
res.sendStatus(200); // answer 2xx within 5 seconds
});
app.listen(8080, () => console.log("listening on :8080 (put HTTPS in front)"));Самая частая ошибка в Express — использовать express.json(): после разбора и повторной сериализации тела подпись перестаёт совпадать. Берите исходный Buffer через express.raw(). Функция crypto.timingSafeEqual выбрасывает ошибку, если буферы разной длины, поэтому сначала сравните длины. Отклоняйте метки времени старше 5 минут, отвечайте 2xx за 5 секунд и пропускайте уже виденный id (делается до 8 повторов). Подробности — на странице Вебхуки.
Коды ошибок
Ошибки приложения приходят простым текстом с HTTP 200; ошибки сети, 429 и 5xx в примере превращаются в класс Transient. В таблице перечислены коды, которые могут встретиться в теле ответа, и рекомендуемые действия.
| Код | Значение | Что делать |
|---|---|---|
BAD_KEY | API-ключ пустой, неверный или заблокирован. | Скопируйте ключ из профиля ещё раз и проверьте, что в начале и в конце нет пробелов. |
NO_BALANCE | Доступный баланс меньше цены номера. | Пополните баланс. Уже зарезервированные суммы вычтены из доступного баланса. |
NO_NUMBERS | Для этого сервиса и страны сейчас нет номеров (ответ приходит и во время техработ). | Повторите через несколько минут или выберите другую страну. |
BAD_SERVICE | Код сервиса или номер страны неверен либо недоступен для продажи. | Сверьтесь с допустимыми значениями через getPrices и getCountries. |
WRONG_MAX_PRICE:<price> | Текущая цена выше вашего лимита maxPrice (или лимит задан неверно). Номер не покупается, деньги не резервируются. | Прочитайте текущую цену после двоеточия; если она устраивает, поднимите лимит и повторите запрос. |
NO_ACTIVATION | Такой активации нет или она не принадлежит вашему аккаунту. | Используйте id из ответа getNumber без изменений. |
BAD_STATUS | Недопустимый статус либо status=6, отправленный до получения кода. | Сначала дождитесь кода и отправляйте только 1, 3, 6 или 8. |
EARLY_CANCEL_DENIED | Отмена невозможна, потому что код уже пришёл. | Прочитайте код через getStatus и закройте активацию статусом 6; списание окончательное. |
NO_CONNECTION / HTTP 429 | Временная проблема или превышен лимит запросов. | Повторите запрос с растущей паузой (до 60 секунд) и опрашивайте реже. |
STATUS_CANCEL | Активация отменена (вами или поставщиком). | Прекратите ожидание; деньги не списываются. При необходимости купите новый номер. |
Как направить существующий клиент handler_api на Turonay
Если у вас есть Node.js-бот или библиотека, использующая формат handler_api, возможно, переписывать их не придётся: в большинстве интеграций достаточно сделать базовым адресом /stubs/handler_api.php Turonay, а ключом — ваш API-ключ Turonay. Если читать адрес из файла .env или переменной окружения, переход сводится к одной строке.
// Before: const BASE_URL = "https://provider.example.com/stubs/handler_api.php";
const BASE_URL = process.env.SMS_API_URL ?? "https://turonay.com/stubs/handler_api.php";
const API_KEY = process.env.SMS_API_KEY; // your Turonay API key
// Libraries and bots with a base-URL option need only these two values, e.g.:
// const client = new SomeHandlerApiClient({ apiKey: API_KEY, baseUrl: BASE_URL });Помните, что цены указаны в турецких лирах, а коды сервисов и номера стран должны совпадать с ответами getPrices и getCountries. Цены смотрите на странице Цены API.
Частые вопросы
Как использовать API, совместимый с handler_api, в Node.js?
Turonay работает по протоколу handler_api. Встроенным fetch вы отправляете GET-запрос на адрес API с параметрами api_key и action и разбираете текстовый ответ. Если у вас уже есть библиотека, достаточно заменить базовый адрес и ключ.
Нужны ли axios или node-fetch?
Нет. В Node.js 18 и новее fetch встроен. Если вы предпочитаете axios, логика остаётся той же; просто читайте ответ как простой текст, а не как JSON.
Спишутся ли деньги, если SMS не придёт?
Нет. getNumber только резервирует цену, а списание происходит при приходе SMS-кода. Если вы отмените активацию до кода или пройдёт 20 минут, резерв снимется.
Почему для вебхука нужен express.raw?
Подпись считается по точным байтам тела запроса. Когда express.json() разбирает и заново сериализует тело, пробелы и порядок полей могут измениться, и проверка подписи не пройдёт. Сначала проверьте исходное тело, а затем преобразуйте его в JSON.
Можно ли получить второе SMS на тот же номер?
Да. Отправьте status=3 через setStatus, чтобы запросить новое SMS на тот же номер. Это бесплатно, платить нужно один раз за активацию. После последнего кода закройте активацию статусом 6.