Операторы

Получите мобильных операторов, доступных для конкретной покупки.

Получить список операторов

Возвращает операторов, у которых номера доступны прямо сейчас для выбранных провайдера, страны и сервиса (и периода аренды для virtual_rent). Это ровно тот срез наличия, по которому POST /api/v1/numbers/ проверяет operator_code, поэтому любой code из этого ответа принимается при покупке номера.

Endpoint

GET /api/v1/numbers/operators/

Параметры запроса

Параметр	Тип	Обязательно	Описание
provider	string	Да	virtual или virtual_rent. У резидентских провайдеров операторов нет
country_code	string	Да	Числовой код страны из GET /countries/
service_code	string	Да	Код сервиса из GET /services/ (например tg, google)
period	string	Для virtual_rent	Период аренды: HOUR_4, HOUR_12, DAY, DAY_3, WEEK. Для virtual не используется

У аренды наличие считается отдельно по каждой длительности — поэтому для virtual_rent параметр period обязателен: count в ответе относится именно к этому периоду. Для virtual (разовая активация) периода нет.

Пример запроса (Virtual)

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/operators/?provider=virtual&country_code=2&service_code=tg' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: ваш_api_ключ'

Пример запроса (Virtual Rent, 1 сутки)

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v1/numbers/operators/?provider=virtual_rent&country_code=2&service_code=tg&period=DAY' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: ваш_api_ключ'

Ответ

[
  {
    "code": "any",
    "name": "Any operator",
    "count": 374
  },
  {
    "code": "beeline",
    "name": "Beeline",
    "count": 43
  },
  {
    "code": "mts",
    "name": "Mts",
    "count": 6
  }
]

Псевдо-оператор any («любой оператор») идёт первым, остальные — по убыванию наличия.

Поля ответа

Поле	Тип	Описание
code	string	Код оператора — передаётся как operator_code в POST /numbers/
name	string	Человекочитаемое название оператора
count	integer	Сколько номеров доступно сейчас у этого оператора. Всегда > 0 — операторы без наличия в ответ не попадают

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

Не передан обязательный параметр (400)

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

Не передан период для аренды (400)

{
  "period": [
    "This query parameter is required for virtual_rent."
  ]
}

Неподдерживаемый провайдер (400)

{
  "provider": [
    "\"residential\" is not a valid choice."
  ]
}

Статус	Описание
400	Отсутствующие или некорректные параметры
401	Неверный или отсутствующий API-ключ
429	Превышен лимит запросов

Важные примечания

• Запрашивайте операторов ровно под ту связку, которую собираетесь купить. Наличие считается по (provider, country_code, service_code, period); код, взятый из другой связки, будет отклонён при покупке с ошибкой Bad operator_code.
• Пустой [] не означает «операторов нет». Список обновляется в фоне, поэтому первый запрос по новой паре страна+сервис может вернуться пустым, пока данные подтягиваются. Повторите запрос через 1–3 секунды. Повторные запросы в окне ~30 секунд не запускают новое обновление, так что поллинг безопасен.
• Операторы работают только для virtual и virtual_rent. Для residential и residential_rent эндпоинт вернёт 400, а operator_code при покупке игнорируется.
• Выбор оператора может быть отключён для аккаунта. Тогда эндпоинт вернёт единственный пункт {"code": "any", "name": "Any operator", "count": 2}, а явный operator_code в POST /numbers/ будет проигнорирован — покупка всё равно пройдёт, просто без выбора оператора.
• Явно выбрать any — тоже валидная стратегия: это значит «оператор не важен».
• Наличие меняется часто — запрашивайте список непосредственно перед покупкой, а не кэшируйте его.

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

import requests

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

purchase = {
    'provider': 'virtual',
    'period': 'MIN_15',
    'service_code': 'tg',
    'country_code': '2'
}

# Операторы под эту конкретную покупку
operators = requests.get(
    'https://app.cyberyozh.com/api/v1/numbers/operators/',
    headers=headers,
    params={
        'provider': purchase['provider'],
        'country_code': purchase['country_code'],
        'service_code': purchase['service_code']
    }
).json()

for operator in operators:
    print(f"{operator['name']} (код: {operator['code']}, доступно: {operator['count']})")

# Покупаем номер у оператора с наибольшим наличием
if operators:
    purchase['operator_code'] = max(operators, key=lambda item: item['count'])['code']

order = requests.post(
    'https://app.cyberyozh.com/api/v1/numbers/',
    headers=headers,
    json=purchase
).json()

print(f"Куплен {order['id']} у оператора {order['operator_code']}")