REST API v1

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

Используйте единый /api/control для автоматизации инвентаря номеров, активаций, получения SMS, отмен, повторного использования и аренды. Поддерживает OAuth2 Client Credentials или подпись API Key. Все операции записи требуют Idempotency-Key.

Перейти к API Reference Запросить Postman Collection

Быстрый путь интеграции

Обычный сценарий состоит из четырех шагов: получить доступ, проверить инвентарь, создать заказ и отследить доставку.

Подготовьте доступ

Сначала создайте OAuth2 Client или API Key в консоли, а затем начинайте работу с control API.

Разделяйте credentials по окружениям, чтобы лимиты, аудит и rotation ключей оставались управляемыми.

Проверьте инвентарь

До оформления заказа получите список сервисов и стран, а затем выберите валидную связку сервис-страна.

Наличие и стартовая цена зависят от live-supply, поэтому не стоит жёстко прошивать их в клиент.

Создайте заказ

Передавайте Idempotency-Key при создании активации или аренды, чтобы повторы не приводили к двойному списанию.

Сразу сохраняйте requestId или rentalId для polling, сверки и дальнейшей поддержки.

Отслеживайте результат

Опросите статус, соберите SMS, а если окно ожидания истекло — выполните отмену или возврат по правилам.

Polling, retries, cancellation и refunds лучше проектировать как один операционный workflow.

Аутентификация

• Рекомендуется OAuth2 Client Credentials; access_token истекает через 2 часа.

• Поддержка статического API Key через заголовок X-API-Key.

• Обновляйте ключи в консоли в любое время; доступен IP-белый список.

Лимиты и идемпотентность

• Лимиты по умолчанию: 10 записей/сек, 30 чтений/сек.

• Используйте заголовок Idempotency-Key для защиты от двойных списаний; генерируйте UUID на каждую транзакцию.

• При получении HTTP 429 применяйте экспоненциальный откат.

Операционная модель

Интеграцию стоит строить как workflow заказов, а не как изолированный request-response вызов.

Сначала защитите записи

Все запросы, создающие заказ или меняющие его состояние, должны иметь собственный Idempotency-Key, чтобы ретраи оставались финансово безопасными.

Явно моделируйте жизненный цикл

Поддерживайте pending, received, cancelled и expired как отдельные состояния, чтобы support мог быстро объяснять результат без ручного разбора логов.

Проектируйте с учетом ретраев

HTTP 429, колебания инвентаря и задержки SMS — это нормальные рабочие условия, а не исключительные сбои.

Основные эндпоинты

Типичные эндпоинты показаны ниже. Полный список см. в OpenAPI-файле.

Метод	Путь	Описание	Типичные ответы
GET	/api/control/balance	Получить баланс аккаунта	200 Баланс успешно получен. / 401 Ошибка аутентификации. Проверьте токен, API key или контекст подписи.
GET	/api/control/services	Получить каталог доступных сервисов	200 Каталог сервисов успешно получен. / 401 Ошибка аутентификации или недостаточные права на этот scope.
GET	/api/control/inventory	Запросить инвентарь и стартовые цены	200 Информация по инвентарю и ценам успешно получена. / 404 Запрошенный код сервиса не существует или не включён.
POST	/api/control/activations	Создать OTP-активацию	200 Заказ на активацию принят и результат аллокации возвращён. / 402 Недостаточно баланса для выбранной комбинации сервис-страна. / 460 Сейчас у поставщиков нет доступного инвентаря для этой комбинации.
GET	/api/control/activations/{requestId}	Получить статус активации и SMS	200 Состояние активации успешно получено. / 404 requestId не найден или недоступен для текущего credentials.
PATCH	/api/control/activations/{requestId}/cancel	Отменить ожидающую активацию	200 Отмена успешно выполнена. / 404 requestId не найден или заказ уже закрыт. / 409 Состояние заказа больше не допускает отмену.
POST	/api/control/rentals	Создать долгосрочную аренду	200 Заказ аренды принят и номер успешно назначен. / 402 Недостаточно баланса для выбранного срока аренды. / 460 Для выбранной страны сейчас нет доступного rental inventory.

GET/api/control/balance

Получить баланс аккаунта

Возвращает доступный баланс, замороженные средства и расчетные метаданные перед созданием новых заказов.

Параметры

Для этого эндпоинта дополнительные параметры не требуются.

Семантика ответов

200

Баланс успешно получен.

401

Ошибка аутентификации. Проверьте токен, API key или контекст подписи.

GET/api/control/services

Получить каталог доступных сервисов

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

Параметры

Для этого эндпоинта дополнительные параметры не требуются.

Семантика ответов

200

Каталог сервисов успешно получен.

401

Ошибка аутентификации или недостаточные права на этот scope.

GET/api/control/inventory

Запросить инвентарь и стартовые цены

Возвращает доступные страны, стартовые цены, объёмы инвентаря и возможность reuse для выбранного сервиса.

Параметры

serviceCodestringОбязательный

Код сервиса, ограничивающий инвентарь в ответе.

countryCodestringНеобязательный

Необязательный фильтр страны, если нужно проверить один конкретный рынок.

Семантика ответов

200

Информация по инвентарю и ценам успешно получена.

404

Запрошенный код сервиса не существует или не включён.

POST/api/control/activations

Создать OTP-активацию

Создаёт одноразовый заказ, выделяет номер и возвращает requestId для polling, отмены и возвратов.

Параметры

serviceCodestringОбязательный

Код сервиса, например whatsapp или telegram.

countryCodestringОбязательный

Страна для выделения номера.

reusebooleanНеобязательный

Необязательный флаг, приоритетизирующий reusable inventory, если сервис это поддерживает.

Семантика ответов

200

Заказ на активацию принят и результат аллокации возвращён.

402

Недостаточно баланса для выбранной комбинации сервис-страна.

460

Сейчас у поставщиков нет доступного инвентаря для этой комбинации.

GET/api/control/activations/{requestId}

Получить статус активации и SMS

Возвращает текущее состояние, таймстемпы, окно reuse и последнее SMS для ранее созданной активации.

Параметры

requestIdstringОбязательный

Идентификатор активации, полученный при создании заказа.

Семантика ответов

200

Состояние активации успешно получено.

404

requestId не найден или недоступен для текущего credentials.

PATCH/api/control/activations/{requestId}/cancel

Отменить ожидающую активацию

Отменяет заказ, который ещё находится в ожидании, завершает дальнейший polling и снимает supplier reservation, если это допустимо.

Параметры

requestIdstringОбязательный

Идентификатор активации, которую нужно отменить.

Семантика ответов

200

Отмена успешно выполнена.

404

requestId не найден или заказ уже закрыт.

409

Состояние заказа больше не допускает отмену.

POST/api/control/rentals

Создать долгосрочную аренду

Выделяет номер на месячную аренду и возвращает lifecycle-данные, статус auto-renew и метаданные привязанных сервисов.

Параметры

countryCodestringОбязательный

Страна для выделения rental inventory.

monthsintegerОбязательный

Срок аренды в месяцах, обычно в пределах поддерживаемого диапазона 1-12.

notestringНеобязательный

Необязательная служебная заметка для проектов, каналов или downstream ownership.

Семантика ответов

200

Заказ аренды принят и номер успешно назначен.

402

Недостаточно баланса для выбранного срока аренды.

460

Для выбранной страны сейчас нет доступного rental inventory.

Пример запроса активации

Тело запроса и JSON-ответа при вызове POST /api/control/activations.

POST /api/control/activations
Headers:
  Authorization: Bearer <token>
  Idempotency-Key: 73b7-...-ff2

Body:
{
  "serviceCode": "whatsapp",
  "countryCode": "US",
  "reuse": true
}

Response 200:
{
  "requestId": "act-123",
  "number": "+1 650 555 0101",
  "expiresAt": "<ISO8601 timestamp>",
  "canReuseUntil": "<ISO8601 timestamp>"
}

Поддерживаемые сервисы и страны

Сейчас доступно 6 сервисов и 10 стран/регионов.

📱 WhatsApp✈️ Telegram🔍 Google🎵 TikTok🛒 Amazon🧧 淘宝

Опирайтесь на inventory endpoints, а не на статические допущения, чтобы операции, дашборды и цены оставались синхронны с live supplier state.

Частые ошибки и их смысл

Эти статусы чаще всего встречаются в production-style интеграциях. Их лучше обрабатывать явно, а не общими ретраями.

401

Ошибка аутентификации или scope

Токен, API key или scope credentials отсутствует, истёк или не подходит для этого ресурса.

Обновите credentials, проверьте окружение и убедитесь, что запрос подписан в правильном tenant context.

402

Недостаточно баланса

На аккаунте недостаточно доступных средств для создания активации или аренды.

Перед ретраем проверьте balance endpoint и пополните аккаунт до повторной отправки заказа.

409

Конфликт состояния

Заказ уже завершён, отменён или находится в состоянии, которое нельзя изменить этим действием.

Сначала перечитайте текущее состояние заказа и скорректируйте workflow клиента, а не повторяйте тот же write request.

429

Достигнут лимит

Клиент превысил текущее окно квоты на чтение или запись.

Применяйте экспоненциальный backoff, сохраняйте idempotency keys и ставьте повторные попытки в очередь.

460

Нет доступного supplier inventory

Запрошенная комбинация страна-сервис не может быть выполнена при текущем live supply.

Снова запросите inventory, смените страну или сервис, либо покажите нехватку оператору для ручного выбора.

Техническая поддержка

Поддержка Telegram

@dogesms_support

Время работы: Ежедневно 09:00-21:00 UTC+8 для живого follow-up

Поддержка по почте

support@dogesms.com

Время работы: Приём тикетов 24/7, разбор в рабочие часы

Для корпоративного доступа или повышенных лимитов свяжитесь с отделом продаж.