SMSLogin

Документация

Быстрая покупка номера

Как работает цепочка fast purchase: отправляем запрос, храним резерв и отслеживаем статус через WebSocket.

Назначение

Fast purchase подбирает первый доступный номер из витрины с учётом сервиса, страны, оператора и лимита цены. Если номер найден, backend сразу создаёт резерв и возвращает идентификаторы заказа и резерва, которые можно полировать через WebSocket или периодическим опросом.

Шаги интеграции

  1. Получите токен клиента и убедитесь, что баланс положительный.
  2. Вызовите POST /api/v1/marketplace/fast-purchase c нужными параметрами.
  3. Сохраните order_id и reservation_id.
  4. Подключитесь к каналу /api/v1/reservations/<reservation_id>/events, чтобы отслеживать SMS-коды и статус.
  5. Если WebSocket недоступен, используйте GET /api/v1/reservations/<reservation_id> с интервалом 3–5 секунд.
  6. После завершения операции освободите номер через DELETE /api/v1/reservations/<reservation_id>, если он больше не нужен.

Типичный запрос

POST /api/v1/marketplace/fast-purchase
Content-Type: application/json

{
  "service_code": "telegram",
  "country": "RU",
  "price_limit": 1.9,
  "currency": "USD",
  "operator": "beeline",
  "extras": {
    "priority": "quality",
    "favorite": true
  }
}

Ответ при успехе

{
  "order_id": "ord_01HZY7F4NNWJ8KZ3Q0VQW4R6KJ",
  "order_status": "initiated",
  "reservation_id": "res_01HZY7F5B1Y5E3T8F2S7J9ZKX5",
  "reservation_status": "pending",
  "service": "telegram",
  "country": "RU",
  "operator": "beeline",
  "price": "1.90",
  "currency": "USD",
  "display_number": "+7 •••• •• 12",
  "expires_at": "2025-04-08T12:35:42.183Z",
  "created_at": "2025-04-08T12:30:42.183Z"
}

Бизнес-логика

  • Номера выбираются по качеству по умолчанию; параметр priority=speed отдаёт предпочтение свежим номерам.
  • Лимит цены применяется к стоимости записи в валюте номера; при пустом лимите подбирается самый дешёвый доступный вариант.
  • В ответе поле display_number маскируется для безопасности, полный номер приходит в метаданных резерва.
  • Дополнительные настройки (extras) сохраняются в истории и помогают автоматическим задачам.

Коды ошибок

number_not_found

Нет подходящих номеров: либо пустой склад, либо лимит цены/оператора слишком строгий.

insufficient_funds

Баланс клиента ниже стоимости первого подходящего номера.

rate_limit_exceeded

Достигнут лимит запросов fast-purchase для этого клиента.

reservation_not_found

Резерв больше не существует (например, был отменён вручную). Повторите покупку.