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

REST API для программной аренды номеров и приёма SMS. Ответы — JSON. Все суммы в USD.

Обзор

Базовый URL:

https://megasimcard.net/api/v1

Порядок работы: пополните баланс и возьмите ключ в консоли → арендуйте номер (POST /numbers) → получайте входящие SMS поллингом (GET /numbers/{id}/sms) или через вебхук. Аренда, продление и отмена списываются с баланса по действующим тарифам (GET /services).

Аутентификация

Каждый запрос должен содержать ваш секретный ключ в заголовке X-API-Key. Ключ виден и перевыпускается в консоли. Держите его в тайне — он даёт доступ к балансу.

X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

Арендовать номер любого оператора на сутки и опросить SMS:

# 1. аренда
curl -X POST https://megasimcard.net/api/v1/numbers \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"period":"day"}'

# ответ: {"id":128,"number":"79001234567",...}

# 2. приём SMS (поллинг раз в 3–5 сек)
curl https://megasimcard.net/api/v1/numbers/128/sms \
  -H "X-API-Key: sk_live_..."

Формат ошибок

При ошибке возвращается HTTP-код и тело:

{"error": {"code": "insufficient_funds", "message": "top up your balance to rent a number"}}

Лимиты

До 120 запросов в минуту на ключ. При превышении — 429. SMS поллингом опрашивайте раз в 3–5 секунд, либо используйте вебхук.

Баланс

Текущий баланс аккаунта.

curl https://megasimcard.net/api/v1/balance -H "X-API-Key: sk_live_..."

{"balance": 12.50, "currency": "USD"}

Услуги и тарифы

Тарифы, операторы свободных номеров и количество доступных по каждому.

{
  "prices": {"day": 10.0, "week": 30.0, "month": 70.0, "quarter": 190.0, "destroy": 10.0, "sms": 5.0},
  "total_available": 33,
  "operators": [{"operator": "MTS", "available": 12}, {"operator": "Beeline", "available": 8}],
  "sms": {"price": 5.0, "available": 5}
}

Цены в примере — действующие тарифы (подставляются автоматически).

Аренда номера

Арендует свободный «живой» номер и списывает цену периода с баланса. Операция атомарна: при нехватке средств номер не занимается.

curl -X POST https://megasimcard.net/api/v1/numbers \
  -H "X-API-Key: sk_live_..." -H "Content-Type: application/json" \
  -d '{"period":"week","operator":"MTS","service":"telegram"}'

{
  "id": 128, "number": "79001234567", "operator": "MTS",
  "period": "week", "price": 30.0, "service": "telegram", "status": "active",
  "created_at": "2026-07-20T09:00:00Z", "expires_at": "2026-07-27T09:00:00Z"
}

Возможные ошибки: 402 insufficient_funds, 409 no_numbers, 400 bad_period, 400 bad_service.

Список аренд

Все активные аренды аккаунта.

{"numbers": [{"id": 128, "number": "79001234567", "service": "telegram", "status": "active", ...}]}

Статус аренды

Одна аренда по её id (только ваша, иначе 404).

Получить SMS

Входящие SMS по аренде, от новых к старым. Поле code — извлечённый код подтверждения (или null).

curl "https://megasimcard.net/api/v1/numbers/128/sms?since_id=0" -H "X-API-Key: sk_live_..."

{
  "messages": [
    {"id": 5501, "sender": "Telegram", "text": "Login code: 34812",
     "code": "34812", "received_at": "2026-07-20T09:01:12Z"}
  ]
}

Продление

Продлить аренду на период (списывается цена периода). Тело: {"period":"day"} (day/week/month/quarter — quarter это 90 дней).

Ошибки: 404 not_found, 402 insufficient_funds, 400 bad_period.

Отмена

Досрочно вывести номер из оборота. Это платное уничтожение по тарифу destroy.

{"id": 128, "status": "closed", "number": "79001234567"}

Вебхук sms.received

Задайте URL в консоли — на каждое входящее SMS мы отправим на него POST с JSON-телом. Одновременно доступен и поллинг (/numbers/{id}/sms).

Тело события

{
  "event": "sms.received",
  "sms_id": 5501,
  "rental_id": 128,
  "number": "79001234567",
  "sender": "Telegram",
  "text": "Login code: 34812",
  "code": "34812",
  "received_at": "2026-07-20T09:01:12Z"
}

Заголовки

• X-Event: sms.received
• X-Signature — HMAC-SHA256 сырого тела вашим секретом (виден в консоли)

Ожидаем ответ 2xx. При ошибке/таймауте — до 3 попыток. Отвечайте быстро, тяжёлую обработку выносите в фон.

Проверка подписи

Сравните X-Signature с HMAC от сырого тела запроса (не пересериализованного):

# Python
import hmac, hashlib

def valid(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

// Node.js
const crypto = require("crypto");
function valid(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}