Open in your browser for best results

Inside Facebook, number lists sometimes don’t load. Tap continue to open Proxnum in Chrome or Safari — one tap, no copying links.

Справочник API

API для разработчиков

Полная документация API для реализации SMS-верификации. Все ответы в формате JSON.

Примечание: Справочник для разработчиков и интеграторов. Каждый endpoint содержит описание, аутентификацию, примеры запросов и ответов.
Аутентификация Настройка Bearer-токена Виртуальные номера Разовая SMS-верификация Аренда номеров Номер на несколько дней со всеми SMS

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

Все endpoint требуют Bearer-токен в заголовке Authorization.

Как получить API-ключ
  1. Войдите в аккаунт Proxnum и откройте страницу профиля
  2. Прокрутите до раздела «Управление API-ключами»
  3. Нажмите «Создать API-ключ»
  4. Скопируйте отображённый токен

Включайте API-токен в каждый запрос:

Authorization: Bearer YOUR_API_TOKEN_HERE
Accept: application/json
Content-Type: application/json

Быстрые ссылки:

Общий формат ответа

Ошибки используют нормализованную структуру с полем code. Все ошибки следуют этому шаблону:

{
  "success": false,
  "code": "no_numbers",
  "message": "No numbers available for the selected service and country"
}

Endpoints

GET /api/v1/resell/price?service=&country=

Получить базовую и продажную цену для сервиса и страны. Используйте для оценки стоимости перед заказом.

Параметры (query): service (string), country (int)

Пример запроса:

curl -s -X GET "https://proxnum.com/api/v1/resell/price?service=ig&country=6" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Успешный ответ:

{
  "country": "6",
  "service": "ig",
  "base_price": 0.0334,
  "sell_price": 0.1114892
}

GET /api/v1/prices

Полная ценовая информация по всем сервисам и странам. Возвращает базовые и реселлерские цены.

Параметры (query, необязательные):

  • service service (string) — фильтр по коду сервиса (например ig, wa, tg)
  • country country (int) — фильтр по коду страны

Пример запроса (все цены):

curl -s -X GET "https://proxnum.com/api/v1/prices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Пример запроса (фильтр по стране):

curl -s -X GET "https://proxnum.com/api/v1/prices?country=6" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Успешный ответ (фильтр по стране):

{
  "success": true,
  "prices": {
    "6": {
      "ig": {
        "base_price": 0.0334,
        "sell_price": 0.1114892,
        "available": 245
      },
      "wa": {
        "base_price": 0.0389,
        "sell_price": 0.1298737,
        "available": 189
      },
      "tg": {
        "base_price": 0.0223,
        "sell_price": 0.0744551,
        "available": 521
      },
      "go": {
        "base_price": 0.0278,
        "sell_price": 0.0928206,
        "available": 312
      }
    }
  }
}

Примечание: Ответ — вложенный объект: первый уровень — коды стран, второй — коды сервисов. Каждый сервис содержит base_price, sell_price и available (или null).

POST /api/v1/resell/virtual/buy

Купить временный (виртуальный) номер. Попытка выделить номер и списать средства.

Тело (JSON): {"service":"ig","country":6}

Пример запроса:

curl -s -X POST "https://proxnum.com/api/v1/resell/virtual/buy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service":"ig","country":6}'

Успешный ответ (нормализованный):

{
  "success": true,
  "activation": {
    "id": 737,
    "phone": "62895406203932",
    "activation_id": "4390520873",
    "msg": "Waiting Sms",
    "date_created": "2025-11-08 21:50:34",
    "amount_paid": 0.111489,
    "status": 1
  }
}

Частые коды ошибок:

{
  "success": false,
  "code": "no_numbers",
  "message": "No numbers available for this service in the selected country"
}

{
  "success": false,
  "code": "insufficient_balance",
  "message": "Not enough balance to place the order"
}

GET /api/v1/resell/virtual/{id}/status

Проверить статус активации. {id} — строка activation id из покупки.

Пример запроса:

curl -s -X GET "https://proxnum.com/api/v1/resell/virtual/4390520873/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Успех (когда код доступен):

{
  "success": true,
  "status": "completed",
  "code": "1234",
  "activation": { "id": 737, "phone": "628...", "activation_id": "4390520873" }
}

POST /api/v1/resell/virtual/resend

Запросить повтор/реактивацию. Передайте activation id в теле запроса.

Тело: {"activation_id":"4390520873"}

curl -s -X POST "https://proxnum.com/api/v1/resell/virtual/resend" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activation_id":"4390520873"}'

Ответ (принято):

{
  "success": true,
  "message": "Resend requested; new activation created",
  "activation": { "id": 738, "activation_id": "4390520874", "phone": "628..." }
}

POST /api/v1/resell/virtual/cancel

Запросить отмену и возврат. Сервер проверяет возможность возврата.

Тело: {"activation_id":"4390520873"}

curl -s -X POST "https://proxnum.com/api/v1/resell/virtual/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activation_id":"4390520873"}'

Принято:

{
  "success": true,
  "code": "cancel_accepted",
  "message": "Cancellation accepted, refund processed"
}

Отклонено:

{
  "success": false,
  "code": "cancel_rejected",
  "message": "Cancellation rejected — activation already completed or not refundable"
}

GET /api/v1/resell/activations

Список активаций пользователя (с пагинацией). Поддерживает page и per_page.

curl -s -X GET "https://proxnum.com/api/v1/resell/activations?page=1&per_page=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

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

Арендованные номера закреплены за вашим аккаунтом на купленный срок и принимают все отправленные на них SMS. С помощью этих методов можно показывать клиентам доступные сроки и цены, арендовать номера, читать входящие SMS, отменять аренду в допустимое окно и продлевать активные аренды.

Все методы аренды доступны и без префикса /resell (например, /api/v1/rental/catalog). Публичный каталог /api/v1/rental/catalog не требует токена.

Ответы содержат "ok" (true или false), код "error" при ошибке и понятное сообщение "message" на языке вашего аккаунта. HTTP-код отражает результат (200 успех, 202 принято и в обработке, 4xx ошибка запроса, 503 временно недоступно).

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

  • active — Номер ваш и принимает SMS до expires_at.
  • cancelling — Отмена запрошена и ожидает подтверждения. Возврат ещё не выполнен.
  • cancelled — Отмена подтверждена, amount_paid возвращено на баланс.
  • expired — Срок аренды закончился.

GET /api/v1/resell/rental/catalog?country=&hours=

Возвращает доступные сейчас сроки аренды, страны и сервисы с вашей ценой и наличием для одной страны и срока. Список сроков приходит в реальном времени от поставщика номеров, поэтому всегда берите его из durations[], а не задавайте вручную.

Параметры запроса: country (необязательно, числовой id страны, см. страницу кодов стран) и hours (необязательно, одно из значений durations[].hours). Неверные или отсутствующие значения заменяются значениями по умолчанию из ответа.

Пример запроса:

curl -s "https://proxnum.com/api/v1/resell/rental/catalog?country=187&hours=168" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
{
  "ok": true,
  "country": "187",
  "hours": 168,
  "durations": [
    { "hours": 24, "label": "1 day" },
    { "hours": 72, "label": "3 days" },
    { "hours": 168, "label": "1 week" },
    { "hours": 720, "label": "30 days" }
  ],
  "countries": [ { "id": "187", "name": "USA" }, { "id": "16", "name": "United Kingdom" } ],
  "services": [
    { "code": "wa", "name": "WhatsApp", "icon": "...", "price": 4.2, "stock": 35 }
  ],
  "cancel_window_seconds": 120
}

POST /api/v1/resell/rental/buy

Арендует номер и списывает средства с баланса. hours должно быть одним из значений durations[].hours из каталога. Можно передать max_price: если текущая цена выше, ничего не списывается и возвращается ошибка price_changed с новой ценой.

Тело (JSON): {"service":"wa","country":187,"hours":168,"max_price":4.20}

curl -s -X POST "https://proxnum.com/api/v1/resell/rental/buy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"service":"wa","country":187,"hours":168,"max_price":4.20}'
{
  "ok": true,
  "error": null,
  "message": "Your rental number is ready.",
  "price": 4.2,
  "balance": 25.8,
  "rental": {
    "id": 512,
    "phone": "14155550123",
    "service": "wa",
    "service_name": "WhatsApp",
    "country": "187",
    "country_name": "USA",
    "status": "active",
    "amount_paid": 4.2,
    "hours": 168,
    "purchased_at": "2026-10-03T12:00:00+03:00",
    "expires_at": "2026-10-10T12:00:00+03:00",
    "cancel_until": "2026-10-03T12:02:00+03:00",
    "can_cancel": true,
    "cancel_pending": false,
    "can_extend": true
  }
}

Частые ошибки: invalid_period (422), no_numbers (409), price_changed (409), insufficient_funds (402), option_unavailable (422), unavailable или provider_unreachable (503, средства не списаны).

GET /api/v1/resell/rental/{id}/status

Возвращает аренду с полученными SMS (новые сверху). Каждое сообщение содержит текст и, если найден, code. Во время ожидания сообщения опрашивайте метод каждые 5–10 секунд. id может быть нашим id аренды или id активации, полученным при покупке.

curl -s "https://proxnum.com/api/v1/resell/rental/512/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
{
  "ok": true,
  "rental": {
    "id": 512,
    "phone": "14155550123",
    "status": "active",
    "expires_at": "2026-10-10T12:00:00+03:00",
    "can_cancel": false,
    "can_extend": true,
    "messages": [
      { "id": 9001, "sender": "WhatsApp", "text": "Your WhatsApp code: 123-456", "code": "123456", "date": "2026-10-03T12:05:10+03:00" }
    ]
  }
}

POST /api/v1/resell/rental/cancel

Аренду можно отменить только в течение 2 минут после покупки, если на номер не пришло ни одного SMS и он не продлевался. Отмена подтверждается у поставщика номеров, это может занять несколько минут.

Тело: {"id":512}

curl -s -X POST "https://proxnum.com/api/v1/resell/rental/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"id":512}'
HTTP/1.1 202 Accepted
{
  "ok": true,
  "pending": true,
  "refunded": 0,
  "message": "Cancellation requested. Your refund will be added once the cancellation is confirmed, usually within a few minutes.",
  "rental": { "id": 512, "status": "cancelling", "cancel_pending": true }
}

HTTP/1.1 200 OK
{
  "ok": true,
  "pending": false,
  "refunded": 4.2,
  "balance": 30,
  "rental": { "id": 512, "status": "cancelled" }
}

HTTP/1.1 409 Conflict
{
  "ok": false,
  "error": "sms_received",
  "message": "This number has already received an SMS, so it cannot be cancelled."
}
HTTP 202 с "pending": true означает, что запрос принят, но возврат ещё не выполнен. Опрашивайте метод статуса: status станет cancelled, когда amount_paid будет возвращено, или вернётся в active, если отмена отклонена (например, если за это время пришло SMS). Возврат никогда не выполняется до подтверждения и никогда не выполняется дважды.

Частые ошибки: window_closed, sms_received, extended, cancel_pending (запрос уже обрабатывается), not_active (все 409).

GET /api/v1/resell/rental/{id}/extend-options

Список сроков и цен продления для одной активной аренды. Цены запрашиваются в реальном времени для конкретного номера.

curl -s "https://proxnum.com/api/v1/resell/rental/512/extend-options" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{
  "ok": true,
  "options": [
    { "hours": 24, "label": "1 day", "price": 1.1 },
    { "hours": 168, "label": "1 week", "price": 5.0 }
  ]
}

POST /api/v1/resell/rental/{id}/extend

Продлевает активную аренду на один из сроков, полученных из вариантов продления, и списывает средства с баланса. Передайте max_price, чтобы никогда не списать больше цены, показанной клиенту. Продлённую аренду отменить нельзя.

Тело (JSON): {"hours":168,"max_price":5.00}

curl -s -X POST "https://proxnum.com/api/v1/resell/rental/512/extend" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"hours":168,"max_price":5.00}'

{
  "ok": true,
  "message": "Rental extended by 1 week.",
  "price": 5,
  "balance": 25,
  "rental": { "id": 512, "status": "active", "expires_at": "2026-10-17T12:00:00+03:00", "can_cancel": false }
}

Частые ошибки: invalid_period (422), price_changed (409), insufficient_funds (402), not_active (409), unavailable (503).

GET /api/v1/resell/rentals

Постраничный список ваших аренд, новые сверху. Параметры запроса: page и per_page (от 1 до 100).

curl -s "https://proxnum.com/api/v1/resell/rentals?page=1&per_page=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{ "ok": true, "total": 3, "page": 1, "per_page": 25, "data": [ { "id": 512, "phone": "14155550123", "status": "active", "...": "..." } ] }

Примечания по реализации

  • Операции списания идемпотентны по заказу; проверяйте поля order или transaction.
  • Используйте endpoint price для пробного расчёта перед оплатой.
  • Коды ошибок: no_numbers, insufficient_balance, service_unavailable, cancel_rejected.
Лучшие практики:
  • Обрабатывайте успешные и ошибочные ответы
  • Реализуйте обработку сетевых таймаутов
  • Кэшируйте списки стран и сервисов
  • Используйте webhooks для обновлений в реальном времени

Обновлено: 26 января 2026 — предложения и сообщения об ошибках: [email protected].

chat us