Покупка и управление номерами

Заказ телефонных номеров для приёма SMS и управление активными номерами.

Купить номер

Приобрести телефонный номер для получения SMS-кодов. Цена немедленно списывается с баланса, заказ переходит в статус waiting.

Endpoint

POST /api/v1/numbers/

Тело запроса

{
  "provider": "virtual",
  "period": "MIN_15",
  "service_code": "tg",
  "country_code": "2",
  "operator_code": "",
  "need_fraud_score": false,
  "markup_percent": 0,
  "promo_code": "DISCOUNT10"
}

Поля запроса

Поле	Тип	Обязательно	Описание
`provider`	string	Да	Тип провайдера: `virtual`, `virtual_rent`, `residential`, `residential_rent`
`period`	string	Да	Период аренды (см. таблицу ниже)
`service_code`	string	Да	Код сервиса из `GET /services/` (например `tg`, `google`)
`country_code`	string	Да	Числовой код страны из `GET /countries/`
`operator_code`	string	Нет	Код оператора из `GET /operators/`, запрошенный под ту же связку `provider` + `country_code` + `service_code` (+ `period` для `virtual_rent`). Не передавайте поле или отправьте пустую строку — оператор подберётся автоматически. Работает только для `virtual` / `virtual_rent`, для резидентских провайдеров игнорируется
`need_fraud_score`	boolean	Нет	Запросить проверку fraud-score для номера (по умолчанию `false`)
`markup_percent`	integer	Нет	Наценка над базовой ценой в %. Допустимые значения: `0`, `50`, `100`, `200`, `300`, `400`, `500`, `1000`, `2000` (по умолчанию `0`)
`promo_code`	string	Нет	Промо-код для применения скидки к заказу

Правила провайдера и периода

Провайдер	Доступные периоды
`virtual`	Только `MIN_15`
`virtual_rent`	`HOUR_4`, `HOUR_12`, `DAY`, `DAY_3`, `WEEK`
`residential`	Только `MIN_15`
`residential_rent`	`DAY_3`, `WEEK`, `WEEK_2`, `DAY_25`

Пример запроса (Виртуальный, 15 минут)

curl -X 'POST' \
  'https://app.cyberyozh.com/api/v1/numbers/' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: ваш_api_ключ' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "virtual",
    "period": "MIN_15",
    "service_code": "tg",
    "country_code": "2",
    "need_fraud_score": false
  }'

Пример запроса (Виртуальная аренда, 4 часа)

curl -X 'POST' \
  'https://app.cyberyozh.com/api/v1/numbers/' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: ваш_api_ключ' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "virtual_rent",
    "period": "HOUR_4",
    "service_code": "tg",
    "country_code": "1"
  }'

Пример запроса (Виртуальный, конкретный оператор)

curl -X 'POST' \
  'https://app.cyberyozh.com/api/v1/numbers/' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: ваш_api_ключ' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "virtual",
    "period": "MIN_15",
    "service_code": "tg",
    "country_code": "2",
    "operator_code": "beeline"
  }'

Успешный ответ (201)

Возвращает созданный заказ:

{
  "id": "71066120515e427ea147fc090fe395ce",
  "pk": "71066120-515e-427e-a147-fc090fe395ce",
  "provider": "virtual",
  "period": "MIN_15",
  "service": "tg",
  "country": "2",
  "operator_code": "beeline",
  "operator_name": "Beeline",
  "need_fraud_score": false,
  "status": "new"
}

Заказ создаётся в статусе new и переходит в waiting, когда номер выдан — сам номер (phone_number) и приходящие SMS-коды забирайте через GET /api/v1/numbers/.

operator_code / operator_name показывают оператора, у которого номер реально куплен: переданный вами код либо подобранный автоматически, если поле было пустым. Для резидентских провайдеров — null.

Ответы с ошибками

Ограничение частоты (429)

{
  "detail": "Request was throttled. Expected available in 50 seconds."
}

Недостаточно средств (402)

{
  "detail": "You can top up your account balance."
}

Нет доступных номеров (400)

{
  "count": [
    "There are no available phone numbers, try again later!"
  ]
}

Отсутствует поле (400)

{
  "provider": [
    "This field is required."
  ]
}

Неверный код сервиса (400)

{
  "non_field_errors": [
    "Bad service_code"
  ]
}

Неверный код оператора (400)

Оператор недоступен для этой связки provider + country_code + service_code (+ period). Перезапросите GET /operators/ ровно под эту связку и возьмите код из ответа.

{
  "operator_code": [
    "Bad operator_code"
  ]
}

Получить активные номера

Возвращает все активные заказы номеров (статус waiting) — заказы, ожидающие входящего SMS-кода. Для завершённых заказов используйте GET /history/.

Endpoint

GET /api/v1/numbers/

Запрос

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: ваш_api_ключ'

Ответ

[
  {
    "id": "71066120515e427ea147fc090fe395ce",
    "status": "waiting",
    "provider": "virtual",
    "price_usd": "2.84",
    "phone_number": "+15555555555",
    "operator_code": "beeline",
    "operator_name": "Beeline",
    "expiration_time": null,
    "history_sms_code": [],
    "can_replay": false,
    "can_extend": false,
    "can_cancel": true
  }
]

Поля ответа

Поле	Тип	Описание
`id`	string	UUID заказа
`status`	string	Текущий статус заказа (`waiting`)
`provider`	string	Тип провайдера (`virtual` / `virtual_rent` / `residential` / `residential_rent`)
`price_usd`	string	Списанная сумма в USD
`phone_number`	string	Назначенный телефонный номер
`operator_code`	string\|null	Оператор, у которого куплен номер; `null` для резидентских провайдеров и для заказов, созданных до появления выбора оператора
`operator_name`	string\|null	Человекочитаемое название этого оператора
`expiration_time`	string\|null	Время истечения заказа (UTC); `null` для одноразовых номеров
`history_sms_code`	array	Список полученных SMS-кодов
`can_replay`	boolean	Можно ли повторно запросить SMS
`can_extend`	boolean	Можно ли продлить аренду
`can_cancel`	boolean	Можно ли отменить заказ

Получить историю номеров

Возвращает все заказы, достигшие конечного состояния. Активные заказы (waiting) исключены — для них используйте GET /numbers/.

Заказы отсортированы по времени завершения: сначала те, что завершились последними.

Endpoint

GET /api/v1/numbers/history/

Запрос

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/history/' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: ваш_api_ключ'

Ответ

[
  {
    "pk": "97f39164-512f-4ccb-9b1a-22cbdee0c47f",
    "id": "97f39164-512f-4ccb-9b1a-22cbdee0c47f",
    "status": "success",
    "provider": "virtual",
    "price_usd": "0.15",
    "phone_number": "+15555555555",
    "operator_code": "beeline",
    "operator_name": "Beeline",
    "expiration_time": null,
    "history_sms_code": ["79373"],
    "fraud_score": null,
    "expenses": "0.15",
    "report": null,
    "can_replay": false,
    "can_extend": false,
    "can_cancel": false
  }
]

Возможные статусы

Статус	Описание
`success`	SMS-код получен
`canceled`	Заказ отменён пользователем
`refund`	Заказ возвращён
`not_sms_code`	SMS-код не поступил в течение периода аренды
`calculation`	Заказ находится в постобработке / расчёте

Отменить номер

Отменить активный заказ номера. Списанная сумма возвращается на баланс пользователя. Отмена доступна только в определённом временном окне и только если SMS ещё не была получена.

Endpoint

PUT /api/v1/numbers/{id}/cancel/

Правила отмены по провайдеру

Провайдер	Окно	Условие
`virtual`	2–15 минут после покупки	SMS не получена
`virtual_rent`	2–20 минут после покупки	SMS не получена
`residential`	2–15 минут после покупки	SMS не получена
`residential_rent`	Отмена недоступна	—

Запрос

curl -X 'PUT' \
  'https://app.cyberyozh.com/api/v1/numbers/bb157566-8003-49f3-9e74-c1488acb9625/cancel/' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: ваш_api_ключ'

Успешный ответ (200)

{
  "detail": "Cancel processed"
}

Ответы с ошибками

Уже получена SMS (400)

{
  "detail": "You can't cancel if you've already received a text message."
}

Слишком рано — окно ещё не открылось (400)

{
  "detail": "You can cancel the phone number 2 minutes after you bought it."
}

Слишком поздно — окно уже закрылось (400)

{
  "detail": "You can cancel the phone number 20 minutes after you bought it."
}

Получить варианты продления

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

Endpoint

GET /api/v1/numbers/{id}/extend-options/

Запрос

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/bb157566-8003-49f3-9e74-c1488acb9625/extend-options/' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: ваш_api_ключ'

Успешный ответ (200)

Номер virtual_rent, купленный на неделю за 1.50:

{
  "options": [
    { "period": "HOUR_4", "price": "0.04", "is_current_period": false },
    { "period": "HOUR_12", "price": "0.11", "is_current_period": false },
    { "period": "DAY", "price": "0.21", "is_current_period": false },
    { "period": "DAY_3", "price": "0.64", "is_current_period": false },
    { "period": "WEEK", "price": "1.50", "is_current_period": true }
  ]
}

Поля ответа

Поле	Тип	Описание
`period`	string	Имя периода, которое передаётся в продление
`price`	string	Цена продления в USD
`is_current_period`	boolean	Период, с которым аренда куплена

Правила цены

Провайдер	Период покупки	Любой другой период
`virtual_rent`	Цена покупки	Цена покупки пропорционально часам, с округлением до цента, минимум `0.02`
`residential_rent`, `residential_private`	Цена покупки	Текущая розничная цена периода; периоды без цены в список не попадают

Список — это таблица продления провайдера, заранее с провайдером он не сверяется. Если провайдер сейчас не даёт продлить на период, продление не состоится: деньги не списываются, срок аренды не меняется.

Ответы с ошибками

Номер нельзя продлить (400)

{
  "detail": "The number can't be extended."
}

Для завершённой аренды приходит "You can only extend an active rental.".

Продлить аренду

Продлевает активную аренду. Выбранный период прибавляется к текущему сроку. Продление обрабатывается асинхронно: ответ 200 означает, что запрос принят, а не что аренда уже продлена. Деньги списываются только после того, как провайдер подтвердил продление.

Endpoint

PUT /api/v1/numbers/{id}/extend/

Тело запроса

Поле	Тип	Обязательно	Описание
`period`	string	Нет	Период из вариантов продления. Без него аренда продлевается периодом покупки

Периоды продления по провайдерам

Провайдер	Периоды
`virtual_rent`	`HOUR_4`, `HOUR_12`, `DAY`, `DAY_3`, `WEEK`
`residential_rent`	`DAY_3`, `WEEK`, `WEEK_2`, `DAY_25`
`residential_private`	`MONTH`, `MONTH_3`

Одноразовые номера (virtual, residential) продлить нельзя. Цена периода считается по правилам цены.

Запрос

curl -X 'PUT' \
  'https://app.cyberyozh.com/api/v1/numbers/bb157566-8003-49f3-9e74-c1488acb9625/extend/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: ваш_api_ключ' \
  -d '{"period": "DAY"}'

Успешный ответ (200)

{
  "detail": "Extend processed",
  "period": "DAY",
  "price": "0.21"
}

price — сумма, которая будет списана за продление. Результат смотрите через GET /api/v1/numbers/: при успехе expiration_time заказа сдвинется на выбранный период. Если провайдер откажет в продлении (например, недельную аренду нельзя продлить сразу после покупки), деньги не списываются и expiration_time не меняется.

Ответы с ошибками

Периода нет в таблице продления (400)

{
  "period": [
    "Period MONTH can't be used to extend a virtual_rent rental. Allowed: HOUR_4, HOUR_12, DAY, DAY_3, WEEK."
  ]
}

Номер нельзя продлить (400)

{
  "detail": "You can only extend an active rental."
}

Недостаточно средств (402)

{
  "detail": "You can top up your account balance."
}

Повторно запросить SMS (Replay)

Запрашивает новую SMS для существующего заказа. За каждый повтор с баланса списывается price_usd заказа.

Endpoint

PUT /api/v1/numbers/{id}/replay/

Условия

у заказа can_replay равен true
на балансе не меньше price_usd заказа
для virtual и virtual_rent: у заказа нет активного срока, а статус — success

Запрос

curl -X 'PUT' \
  'https://app.cyberyozh.com/api/v1/numbers/bb157566-8003-49f3-9e74-c1488acb9625/replay/' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: ваш_api_ключ'

Успешный ответ (200)

{
  "detail": "Replay processed"
}

Новый код появится в history_sms_code заказа.

Ответы с ошибками

Недостаточно средств (402)

{
  "detail": "You can top up your account balance."
}

Повтор недоступен (404)

{
  "detail": "The number can't be replayed."
}

Получить сообщения номера

Возвращает полную историю SMS заказа с отправителем и текстом, новые первыми. Работает и для активных, и для завершённых заказов. GET /numbers/ отдаёт только последние коды, поэтому для долгой аренды используйте эту ручку.

Endpoint

GET /api/v1/numbers/{id}/messages/

Query-параметры

Параметр	Тип	Обязательно	Описание
`page`	integer	Нет	Номер страницы, по умолчанию `1`
`page_size`	integer	Нет	Сообщений на странице, по умолчанию `10`, максимум `50`

Запрос

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/bb157566-8003-49f3-9e74-c1488acb9625/messages/?page=1&page_size=10' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: ваш_api_ключ'

Успешный ответ (200)

{
  "count": 1,
  "next": null,
  "previous": null,
  "currentPage": 1,
  "nextPage": null,
  "prevPage": null,
  "results": [
    {
      "id": "3f2b7c1e9a4d4e0f8b6a5c2d1e0f9a8b",
      "sms_code": "123456",
      "sender": "Telegram",
      "text": "Telegram code: 123456",
      "received_at": "2026-09-16T10:30:00Z",
      "created_at": "2026-09-16T10:30:02Z"
    }
  ]
}

Поля ответа

Поле	Тип	Описание
`id`	string	ID сообщения
`sms_code`	string	Извлечённый код
`sender`	string\|null	Отправитель по данным провайдера
`text`	string\|null	Полный текст SMS; `null` у старых сообщений
`received_at`	string\|null	Когда сообщение получил провайдер (UTC)
`created_at`	string	Когда сообщение сохранено (UTC)

Ответы с ошибками

Заказ не найден (404)

Приходит, если заказа нет или он принадлежит другому пользователю.

Пример использования

import requests
import time

headers = {
    'accept': 'application/json',
    'X-Api-Key': 'ваш_api_ключ'
}

# Купить номер
order_response = requests.post(
    'https://app.cyberyozh.com/api/v1/numbers/',
    headers=headers,
    json={
        'provider': 'residential',
        'period': 'MIN_15',
        'service_code': 'tg',
        'country_code': '667',
        'need_fraud_score': True
    }
)

order = order_response.json()
order_id = order['id']
print(f"Номер заказан с ID: {order_id}")

# Опрос для получения SMS-кодов
for _ in range(30):  # Проверка в течение 5 минут
    details = requests.get(
        f'https://app.cyberyozh.com/api/v1/numbers/{order_id}/',
        headers=headers
    ).json()

    if details['history_sms_code']:
        print(f"Получен SMS-код: {details['history_sms_code'][0]}")
        break

    time.sleep(10)
else:
    print("SMS не получена, отмена...")
    requests.put(
        f'https://app.cyberyozh.com/api/v1/numbers/{order_id}/cancel/',
        headers=headers
    )

Купить номер​

Endpoint​

Тело запроса​

Поля запроса​

Правила провайдера и периода​

Пример запроса (Виртуальный, 15 минут)​

Пример запроса (Виртуальная аренда, 4 часа)​

Пример запроса (Виртуальный, конкретный оператор)​

Успешный ответ (201)​

Ответы с ошибками​

Ограничение частоты (429)​

Недостаточно средств (402)​

Нет доступных номеров (400)​

Отсутствует поле (400)​

Неверный код сервиса (400)​

Неверный код оператора (400)​

Получить активные номера​

Endpoint​

Запрос​

Ответ​

Поля ответа​

Получить историю номеров​

Endpoint​

Запрос​

Ответ​

Возможные статусы​

Отменить номер​

Endpoint​

Правила отмены по провайдеру​

Запрос​

Успешный ответ (200)​

Ответы с ошибками​

Уже получена SMS (400)​

Слишком рано — окно ещё не открылось (400)​

Слишком поздно — окно уже закрылось (400)​

Получить варианты продления​

Endpoint​

Запрос​

Успешный ответ (200)​

Поля ответа​

Правила цены​

Ответы с ошибками​

Номер нельзя продлить (400)​

Продлить аренду​

Endpoint​

Тело запроса​

Периоды продления по провайдерам​

Запрос​

Успешный ответ (200)​

Ответы с ошибками​

Периода нет в таблице продления (400)​

Номер нельзя продлить (400)​

Недостаточно средств (402)​

Повторно запросить SMS (Replay)​

Endpoint​

Условия​

Запрос​

Успешный ответ (200)​

Ответы с ошибками​

Недостаточно средств (402)​

Повтор недоступен (404)​

Получить сообщения номера​

Endpoint​

Query-параметры​

Запрос​

Успешный ответ (200)​

Поля ответа​

Ответы с ошибками​

Заказ не найден (404)​

Пример использования​

Купить номер

Endpoint

Тело запроса

Поля запроса

Правила провайдера и периода

Пример запроса (Виртуальный, 15 минут)

Пример запроса (Виртуальная аренда, 4 часа)

Пример запроса (Виртуальный, конкретный оператор)

Успешный ответ (201)

Ответы с ошибками

Ограничение частоты (429)

Недостаточно средств (402)

Нет доступных номеров (400)

Отсутствует поле (400)

Неверный код сервиса (400)

Неверный код оператора (400)

Получить активные номера

Endpoint

Запрос

Ответ

Поля ответа

Получить историю номеров

Endpoint

Запрос

Ответ

Возможные статусы

Отменить номер

Endpoint

Правила отмены по провайдеру

Запрос

Успешный ответ (200)

Ответы с ошибками

Уже получена SMS (400)

Слишком рано — окно ещё не открылось (400)

Слишком поздно — окно уже закрылось (400)

Получить варианты продления

Endpoint

Запрос

Успешный ответ (200)

Поля ответа

Правила цены

Ответы с ошибками

Номер нельзя продлить (400)

Продлить аренду

Endpoint

Тело запроса

Периоды продления по провайдерам

Запрос

Успешный ответ (200)

Ответы с ошибками

Периода нет в таблице продления (400)

Номер нельзя продлить (400)

Недостаточно средств (402)

Повторно запросить SMS (Replay)

Endpoint

Условия

Запрос

Успешный ответ (200)

Ответы с ошибками

Недостаточно средств (402)

Повтор недоступен (404)

Получить сообщения номера

Endpoint

Query-параметры

Запрос

Успешный ответ (200)

Поля ответа

Ответы с ошибками

Заказ не найден (404)

Пример использования