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

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

Купить номер

Приобрести телефонный номер для получения SMS кодов.

Endpoint

POST /api/v1/numbers/

Тело запроса

{
  "provider": "virtual" | "virtual_rent" | "residential",
  "period": "MIN_15" | "DAY" | "WEEK" | "MONTH",
  "service_code": "tg",
  "country_code": "2",
  "need_fraud_score": false
}

Поля запроса

Поле	Тип	Обязательно	Описание
`provider`	string	Да	Тип провайдера
`period`	string	Да	Период аренды
`service_code`	string	Да	Код сервиса из `/services/`
`country_code`	string	Да	Код страны из `/countries/`
`need_fraud_score`	boolean	Нет	Запросить проверку на мошенничество

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

virtual: Только период MIN_15
virtual_rent: Только периоды DAY, WEEK, MONTH
residential: Только период MIN_15

Пример запроса (Виртуальный, 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
  }'

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

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": "DAY",
    "service_code": "tg",
    "country_code": "1",
    "need_fraud_score": false
  }'

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

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

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

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

{
  "detail": "Запрос был ограничен. Доступен через 50 секунд."
}

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

{
  "count": [
    "Нет доступных телефонных номеров, попробуйте позже!"
  ]
}

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

{
  "provider": [
    "Это поле обязательно."
  ]
}

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

{
  "non_field_errors": [
    "Неверный service_code"
  ]
}

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

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

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": "2025-12-09T10:28:08Z",
    "report": null,
    "history_sms_code": [],
    "can_replay": false,
    "can_extend": false,
    "can_cancel": true,
    "expenses": 2.84,
    "fraud_score": null
  }
]

Поля ответа

Поле	Тип	Описание
`id`	string	Идентификатор заказа номера
`status`	string	Текущий статус (waiting, success, canceled)
`provider`	string	Тип провайдера
`price_usd`	string	Оплаченная цена
`phone_number`	string	Телефонный номер
`expiration_time`	string	Когда истекает доступ
`report`	string	Ссылка на отчет о мошенничестве (если запрошен)
`history_sms_code`	array	Полученные SMS коды
`can_replay`	boolean	Можно ли запросить новую SMS
`can_extend`	boolean	Можно ли продлить аренду
`can_cancel`	boolean	Можно ли отменить
`expenses`	number	Общие расходы
`fraud_score`	integer	Оценка мошенничества (0-100, если запрошена)

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

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

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_ключ'

Ответ

[
  {
    "id": "97f39164-512f-4ccb-9b1a-22cbdee0c47f",
    "status": "success",
    "provider": "virtual",
    "price_usd": "0.15",
    "phone_number": "+15555555555",
    "expiration_time": null,
    "report": "/checkers/phone/9adb548607424c6fa372d434649aa698/",
    "history_sms_code": [
      "79373"
    ],
    "can_replay": false,
    "can_extend": false,
    "expenses": 0.15,
    "fraud_score": 0
  }
]

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

Получить подробную информацию о конкретном заказе номера.

Endpoint

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

Запрос

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

Ответ

{
  "id": "bb157566-8003-49f3-9e74-c1488acb9625",
  "status": "waiting",
  "provider": "virtual",
  "price_usd": "0.43",
  "phone_number": "+15555555555",
  "expiration_time": "2024-09-25T08:42:02Z",
  "report": "/checkers/phone/5d7d117db605422db6cbb5afcb290433/",
  "history_sms_code": [],
  "can_replay": true,
  "can_extend": false,
  "expenses": 0.43,
  "fraud_score": 85
}

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

Отменить активный заказ номера.

Endpoint

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

Запрос

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_ключ'

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

{
  "detail": "Отмена обработана"
}

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

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

{
  "detail": "Вы не можете отменить после получения SMS сообщения."
}

Слишком рано (400)

{
  "detail": "Вы можете отменить номер через 2 минуты после покупки."
}

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

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': '666',
        '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)​

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

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

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

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

Endpoint​

Запрос​

Ответ​

Поля ответа​

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

Endpoint​

Запрос​

Ответ​

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

Endpoint​

Запрос​

Ответ​

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

Endpoint​

Запрос​

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

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

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

Слишком рано (400)​

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

Купить номер

Endpoint

Тело запроса

Поля запроса

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

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

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

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

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

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

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

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

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

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

Endpoint

Запрос

Ответ

Поля ответа

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

Endpoint

Запрос

Ответ

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

Endpoint

Запрос

Ответ

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

Endpoint

Запрос

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

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

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

Слишком рано (400)

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