Главная › SMS API › SMS API на Node.js
Node.js · fetch · API приёма SMS

Приём 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 встроены.
Списание: при покупке номера цена только резервируется, а деньги списываются в момент прихода SMS-кода. Если вы отмените активацию до кода или пройдёт 20 минут, резерв снимется. После получения кода отмена отклоняется с ответом EARLY_CANCEL_DENIED.

Подготовка: без зависимостей

Проверьте версию Node.js и сохраните ключ в переменную окружения. Пакет express нужен, только если вы запускаете приёмник вебхуков; для вызовов API ничего ставить не требуется. Примеры написаны на CommonJS, так что дополнительная настройка не нужна.

bash
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().

javascript
// 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.

javascript
// 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 без указания часового пояса.

javascript
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-функции.

javascript
// 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(секрет, метка времени + "." + тело запроса).

javascript
// 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_KEYAPI-ключ пустой, неверный или заблокирован.Скопируйте ключ из профиля ещё раз и проверьте, что в начале и в конце нет пробелов.
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 или переменной окружения, переход сводится к одной строке.

javascript
// 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.