REST API v1

DogeSMS API для разработчиков

Автоматизируйте выдачу номеров, получение SMS и управление заказами через REST API на api.dogesms.com. Используйте API Key для аутентификации. POST /v1/orders поддерживает заголовок X-Idempotency-Key для защиты от двойных списаний при повторных запросах.

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

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

Типичный сценарий состоит из четырёх шагов: создать API Key, проверить баланс, оформить заказ и получить SMS.

Создайте API Key

Сгенерируйте ключ в дашборде в разделе «Настройки → API Keys». Скопируйте его сразу — он отображается только один раз.

Создавайте отдельный ключ для каждого окружения (dev / staging / prod), чтобы ротация и аудит оставались управляемыми.

Проверьте баланс

Вызовите GET /v1/balance перед заказом, чтобы убедиться, что на счёте достаточно средств и избежать ошибки INSUFFICIENT_BALANCE (422).

Баланс возвращается в центах (целое число). Разделите на 100, чтобы получить сумму в долларах. Пополните счёт в дашборде при необходимости.

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

POST /v1/orders с полями service_code и country_code. Добавьте заголовок X-Idempotency-Key с UUID, чтобы повторные запросы не создавали дубликаты.

Сразу сохраняйте id из ответа — он нужен для polling статуса и возможной отмены.

Получите номер и SMS

Рекомендуется: зарегистрируйте webhook, чтобы получать события order.number_allocated (phone_number готов) и order.completed (sms_code готов) в реальном времени — без опроса. Либо опрашивайте GET /v1/orders/{id}: active означает, что phone_number готов; completed — что sms_code доступен.

Состояния expired, cancelled и failed — терминальные. Если SMS не поступило в ожидаемое время, отмените заказ через POST /v1/orders/{id}/cancel для освобождения ресурса.

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

• Передавайте API Key в заголовке Authorization: Authorization: Bearer sk_live_…

• Ключи начинаются с sk_live_ — не коммитьте их в репозиторий и не передавайте третьим лицам.

• Отзовите или замените ключ в дашборде в любой момент; изменения вступают в силу немедленно.

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

• Добавляйте заголовок X-Idempotency-Key: <uuid> к запросу POST /v1/orders (CreateOrder), чтобы ретраи были безопасными. Эндпоинт отмены не использует этот заголовок.

• Ключ навсегда привязан к исходной попытке создания — повторное использование старого ключа вернёт исходный заказ, а не создаст новый. Для каждого нового заказа всегда генерируйте новый UUID.

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

Модель интеграции

Рассматривайте API как workflow заказов, а не как изолированный request-response вызов.

Безопасные записи с Idempotency-Key

Генерируйте новый UUID для каждого вызова POST /v1/orders и сохраняйте его вместе с заказом. Повтор с тем же ключом вернёт оригинальный результат без повторного списания.

Отслеживайте жизненный цикл заказа

Заказы проходят путь pending → active (phone_number готов) → completed (sms_code готов), либо завершаются в expired / cancelled / failed. Подпишитесь на webhooks (order.number_allocated, order.completed) для реакции в реальном времени или опрашивайте GET /v1/orders/{id} как запасной вариант.

Обрабатывайте временные сбои

HTTP 429 и 422 SERVICE_NOT_AVAILABLE (нет инвентаря) — это ожидаемые рабочие условия. Применяйте откат и повтор, не передавая сырые коды ошибок конечным пользователям.

Webhooks (рекомендуется)

Получайте события заказа через HTTP POST в момент их возникновения — без опроса. Зарегистрируйте один эндпоинт, и мы будем присылать весь жизненный цикл (выделение номера, доставку SMS, терминальные сбой/истечение) в реальном времени.

Зарегистрируйте эндпоинт

Настройте URL вашего webhook в дашборде в разделе Настройки → Webhooks (ваш API Key и webhook-эндпоинт принадлежат одному аккаунту). Секрет для подписи показывается один раз при создании — сохраните его надёжно.

События

• order.number_allocated — order.number_allocated — срабатывает при выделении номера (status становится active). Payload содержит phone_number для ввода на целевой платформе. sms_code пока недоступен.

• order.completed — order.completed — срабатывает при поступлении SMS (status становится completed). Payload содержит sms_code и sms_content.

• order.failed — order.failed — срабатывает при сбое заказа (нет доступного номера или ошибка выделения). Payload содержит обезличенный error_code; списание не удерживается.

• order.expired — order.expired — срабатывает, когда номер выделен, но SMS не поступило в окне (status становится expired). Списание автоматически возвращается.

Примеры payload

POST <your webhook url>
X-Webhook-Signature: sha256=<hex>
Content-Type: application/json

{
  "event_type": "order.number_allocated",
  "order_id": "01960a9b-…",
  "service_code": "whatsapp",
  "country_code": "US",
  "phone_number": "+12015550123",
  "status": "active",
  "allocated_at": "2024-11-01T09:00:05Z"
}

{
  "event_type": "order.completed",
  "order_id": "01960a9b-…",
  "service_code": "whatsapp",
  "country_code": "US",
  "phone_number": "+12015550123",
  "sms_code": "123456",
  "sms_content": "Your code is 123456",
  "completed_at": "2024-11-01T09:01:30Z"
}

{
  "event_type": "order.failed",
  "order_id": "01960a9b-…",
  "service_code": "whatsapp",
  "country_code": "US",
  "status": "failed",
  "error_code": "NO_NUMBERS_AVAILABLE",
  "failed_at": "2024-11-01T09:00:30Z"
}

Проверьте подпись

Каждый запрос содержит заголовок X-Webhook-Signature: sha256=<hex>. Вычислите HMAC-SHA256 по сырому телу запроса с вашим секретом и сравните за константное время, прежде чем доверять payload.

import crypto from 'node:crypto'

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)              // raw bytes, not parsed JSON
    .digest('hex')
  const sig = Buffer.from(header || '', 'utf8')
  const exp = Buffer.from(expected, 'utf8')
  // length check first — timingSafeEqual throws on unequal lengths
  return sig.length === exp.length &&
    crypto.timingSafeEqual(sig, exp)
}

Доставка и повторы

Отвечайте 2xx быстро (в течение 10 с). Неуспешные доставки повторяются до 5 раз с откатом (30s → 5m → 30m → 2h). Доставка — best-effort.

Резервная сверка

Поскольку доставка — best-effort, оставьте GET /v1/orders/{id} как запасной вариант для сверки пропущенных событий. Когда оба события подключены, опрос становится подстраховкой, а не основным путём.

Список эндпоинтов

Базовый URL: https://api.dogesms.com — все пути ниже относительны этой базы.

Метод	Путь	Описание	Типичные ответы
GET	/v1/balance	Получить баланс аккаунта	200 Успешно. Возвращает { data: { balance_cents: number, currency: string }, request_id: string }. / 401 API Key отсутствует, недействителен или отозван.
POST	/v1/orders	Создать заказ	201 Заказ создан. Возвращает объект заказа с id и status. phone_number доступен при status active; sms_code готов при status completed. Опрашивайте GET /v1/orders/{id} для отслеживания. / 400 Отсутствуют или неверно указаны параметры (нет service_code или country_code, неверный формат Idempotency-Key и т.д.). / 412 Фактическая цена превышает лимит стоимости (max_price_cents). Код ошибки: PRICE_CHANGED. / 422 Недостаточно средств (INSUFFICIENT_BALANCE), кошелёк не инициализирован (WALLET_NOT_INITIALIZED) или номера для данной комбинации сервис/страна временно недоступны (SERVICE_NOT_AVAILABLE).
GET	/v1/orders	Список заказов	200 Успешно. Возвращает { data: { items: Order[], total: number, limit: number, offset: number }, request_id: string }. / 401 API Key отсутствует, недействителен или отозван.
GET	/v1/orders/{id}	Получить один заказ	200 Успешно. Возвращает объект заказа. / 404 Заказ не найден или не принадлежит текущему аккаунту.
POST	/v1/orders/{id}/cancel	Отменить заказ	200 Отмена принята. Если заказ уже в конечном состоянии (completed/expired/failed/cancelled) и его состояние доступно для чтения — возвращает текущий объект заказа идемпотентно, без побочных эффектов. / 404 Заказ не найден или не принадлежит текущему аккаунту. / 409 Заказ в конечном состоянии, но его состояние не удалось получить — редкий защитный fallback (код: ORDER_ALREADY_TERMINAL). Получите текущее состояние через GET /v1/orders/{id}. / 422 Отмена не разрешена в течение 2 минут после создания заказа (кулдаун). Код ошибки: CANCEL_TOO_EARLY.
GET	/v1/catalog/services	Список доступных сервисов	200 Успешно. Возвращает массив объектов сервисов, каждый содержит code и name. / 401 Ошибка аутентификации.
GET	/v1/catalog/countries	Список доступных стран	200 Успешно. Возвращает массив объектов стран (code, name, phone_prefix, service_count). / 401 Ошибка аутентификации.
GET	/v1/catalog/prices	Цены для указанной страны	200 Успешно. Возвращает массив (service_code, service_name, price_cents, available_count). / 400 Отсутствует параметр country_code. / 401 Ошибка аутентификации. / 404 Страна не найдена или нет данных о ценах.

GET/v1/balance

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

Возвращает текущий баланс в центах. Проверяйте его перед созданием заказов, чтобы избежать ошибки INSUFFICIENT_BALANCE (422).

Параметры

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

Коды ответов

200

Успешно. Возвращает { data: { balance_cents: number, currency: string }, request_id: string }.

401

API Key отсутствует, недействителен или отозван.

POST/v1/orders

Создать заказ

Создаёт заказ на номер для указанного сервиса и страны. Возвращает объект заказа с id и status. Опрашивайте GET /v1/orders/{id}: phone_number доступен при status active; sms_code готов при status completed. Добавьте X-Idempotency-Key для защиты от дублирования при ретраях.

Параметры

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

Сервис для активации, например whatsapp или telegram.

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

Двухбуквенный код страны для выделения номера, например US или GB.

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

Ценовой уровень: standard (по умолчанию) или premium.

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

Необязательный лимит стоимости в центах. Если фактическая цена превышает его (с допуском 5%), заказ возвращает 412 PRICE_CHANGED. Пропустите поле, если лимит не нужен.

Коды ответов

201

Заказ создан. Возвращает объект заказа с id и status. phone_number доступен при status active; sms_code готов при status completed. Опрашивайте GET /v1/orders/{id} для отслеживания.

400

Отсутствуют или неверно указаны параметры (нет service_code или country_code, неверный формат Idempotency-Key и т.д.).

412

Фактическая цена превышает лимит стоимости (max_price_cents). Код ошибки: PRICE_CHANGED.

422

Недостаточно средств (INSUFFICIENT_BALANCE), кошелёк не инициализирован (WALLET_NOT_INITIALIZED) или номера для данной комбинации сервис/страна временно недоступны (SERVICE_NOT_AVAILABLE).

GET/v1/orders

Список заказов

Возвращает постраничный список заказов, принадлежащих текущему API Key. Фильтруйте по статусу для поиска ожидающих или завершённых заказов.

Параметры

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

Размер страницы, по умолчанию 20, максимум 100.

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

Смещение пагинации, по умолчанию 0.

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

Фильтр по статусам через запятую, например pending,completed.

Коды ответов

200

Успешно. Возвращает { data: { items: Order[], total: number, limit: number, offset: number }, request_id: string }.

401

API Key отсутствует, недействителен или отозван.

GET/v1/orders/{id}

Получить один заказ

Получить полные данные заказа по UUID: текущий статус, phone_number, sms_code, sms_content и временны́е метки жизненного цикла.

Параметры

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

UUID заказа, возвращённый при вызове POST /v1/orders.

Коды ответов

200

Успешно. Возвращает объект заказа.

404

Заказ не найден или не принадлежит текущему аккаунту.

POST/v1/orders/{id}/cancel

Отменить заказ

Отменяет заказ в статусе pending (ожидает выделения номера) или active (номер выделен, ожидает SMS). Освобождает номер и возвращает оплату. Завершённые, проваленные или уже отменённые заказы отменить нельзя.

Параметры

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

UUID заказа для отмены.

Коды ответов

200

Отмена принята. Если заказ уже в конечном состоянии (completed/expired/failed/cancelled) и его состояние доступно для чтения — возвращает текущий объект заказа идемпотентно, без побочных эффектов.

404

Заказ не найден или не принадлежит текущему аккаунту.

409

Заказ в конечном состоянии, но его состояние не удалось получить — редкий защитный fallback (код: ORDER_ALREADY_TERMINAL). Получите текущее состояние через GET /v1/orders/{id}.

422

Отмена не разрешена в течение 2 минут после создания заказа (кулдаун). Код ошибки: CANCEL_TOO_EARLY.

GET/v1/catalog/services

Список доступных сервисов

Возвращает все поддерживаемые сервисы (WhatsApp, Telegram, Google и др.) с кодом (code) и отображаемым именем (name). Используйте коды из этого списка в качестве service_code при создании заказов.

Параметры

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

Коды ответов

200

Успешно. Возвращает массив объектов сервисов, каждый содержит code и name.

401

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

GET/v1/catalog/countries

Список доступных стран

Возвращает все поддерживаемые страны, отсортированные по количеству доступных сервисов (сначала популярные). Используйте коды стран как country_code при создании заказов.

Параметры

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

Коды ответов

200

Успешно. Возвращает массив объектов стран (code, name, phone_prefix, service_count).

401

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

GET/v1/catalog/prices

Цены для указанной страны

Возвращает все доступные сервисы и справочные цены для указанной страны. Цены указаны в центах (USD) с учётом наценки. Сервер применяет авторитетные цены каталога в момент создания заказа — используйте max_price_cents в POST /v1/orders для защиты от изменения цены.

Параметры

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

Код страны ISO (например US, GB). Регистр не важен.

Коды ответов

200

Успешно. Возвращает массив (service_code, service_name, price_cents, available_count).

400

Отсутствует параметр country_code.

401

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

404

Страна не найдена или нет данных о ценах.

Пример создания заказа

Тело запроса и JSON-ответ при вызове POST /v1/orders.

POST https://api.dogesms.com/v1/orders
Authorization: Bearer sk_live_…
X-Idempotency-Key: 73b7f4a2-1c3e-4d5f-8e9a-0b1c2d3e4f52
Content-Type: application/json

{
  "service_code": "whatsapp",
  "country_code": "US"
}

HTTP 201 Created
X-Request-Id: req_abc123…

{
  "data": {
    "id": "01960a9b-…",
    "order_no": "ORD-20241101-0042",
    "service_code": "whatsapp",
    "country_code": "US",
    "status": "pending",
    "amount_cents": 0,
    "currency": "USD",
    "created_at": "2024-11-01T09:00:00Z"
  },
  "request_id": "req_abc123…"
}
// Poll GET /v1/orders/{id}:
//   "pending"  → waiting for number allocation
//   "active"   → phone_number now available; enter it on the target platform
//   "completed"→ sms_code ready; order done
//   "expired" / "cancelled" / "failed" → terminal error states

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

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

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

Наличие номеров меняется в реальном времени. Ориентируйтесь на ответ заказа, а не на фиксированный каталог.

Частые коды ошибок

Обрабатывайте эти статусы явно, а не через общую логику повтора запросов.

401

Ошибка авторизации

API Key отсутствует, имеет неверный формат или отозван.

Проверьте формат заголовка Authorization (Bearer sk_live_…) и убедитесь, что ключ активен в дашборде.

403

Аккаунт заблокирован или не активен

API Key действителен, но аккаунт не может делать запросы: заблокирован (ACCOUNT_BANNED), email не подтверждён (EMAIL_NOT_VERIFIED) или аккаунт не активирован (ACCOUNT_NOT_ACTIVE).

Проверьте статус аккаунта в дашборде. Подтвердите email, если требуется, или обратитесь в поддержку при бане.

409

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

Заказ уже находится в конечном состоянии (completed, cancelled или failed) и не может быть изменён.

Получите актуальное состояние через GET /v1/orders/{id} перед повтором операции записи.

412

Цена изменилась

Фактическая цена номера превышает переданный вами лимит max_price_cents.

Удалите max_price_cents для размещения заказа по текущей рыночной цене, или увеличьте лимит и повторите попытку.

422

Запрос не может быть выполнен

Недостаточно баланса (INSUFFICIENT_BALANCE) или нет доступных номеров для запрошенного сервиса и страны (SERVICE_NOT_AVAILABLE).

INSUFFICIENT_BALANCE: пополните счёт в дашборде. SERVICE_NOT_AVAILABLE: повторите позже или выберите другую страну — инвентарь восстанавливается автоматически.

429

Превышен лимит запросов

Слишком много запросов в текущем временно́м окне.

Используйте экспоненциальный откат, сохраняйте Idempotency-Key и ставьте повторы в очередь.

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

Поддержка в Telegram

@dogesms_official

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

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

support@dogesms.com

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

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