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

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

Купить номер

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

Endpoint

POST /api/v1/numbers/

Тело запроса

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

Поля запроса

Поле	Тип	Обязательно	Описание
`provider`	string	Да	Тип провайдера: `virtual`, `residential`, `residential_rent`
`period`	string	Да	Период аренды (см. таблицу ниже)
`service_code`	string	Да	Код сервиса из `GET /services/` (например `tg`, `google`)
`country_code`	string	Да	Числовой код страны из `GET /countries/`
`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`
`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
  }'

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

Возвращает полный объект заказа:

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

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

Ограничение частоты (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"
  ]
}

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

Возвращает все активные заказы номеров (статус 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",
    "expiration_time": null,
    "history_sms_code": [],
    "can_replay": false,
    "can_extend": false,
    "can_cancel": true
  }
]

Поля ответа

Поле	Тип	Описание
`id`	string	UUID заказа
`status`	string	Текущий статус заказа (`waiting`)
`provider`	string	Тип провайдера (`virtual` / `residential` / `residential_rent`)
`price_usd`	string	Списанная сумма в USD
`phone_number`	string	Назначенный телефонный номер
`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",
    "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 не получена
`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."
}

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

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 минут)​

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

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

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

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

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

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

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

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

Endpoint​

Запрос​

Ответ​

Поля ответа​

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

Endpoint​

Запрос​

Ответ​

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

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

Endpoint​

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

Запрос​

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

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

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

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

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

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

Купить номер

Endpoint

Тело запроса

Поля запроса

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

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

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

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

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

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

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

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

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

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

Endpoint

Запрос

Ответ

Поля ответа

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

Endpoint

Запрос

Ответ

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

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

Endpoint

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

Запрос

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

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

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

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

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

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