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 из ответа — он нужен для сопоставления webhook-событий и возможной отмены.

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

Зарегистрируйте и проверьте webhook, чтобы получать события order.number_allocated (phone_number готов) и order.completed (sms_code готов) в реальном времени. Запрос статуса заказа по умолчанию отключён; не используйте polling.

Состояния 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. Отслеживайте жизненный цикл через webhook-события.

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

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.

Мониторинг доставки

Отслеживайте неуспешные события в истории доставок дашборда. Запрос статуса заказа по умолчанию отключён; для отдельного процесса сверки обратитесь в поддержку.

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

Базовый 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 Заказ создан. Получайте номер, SMS и терминальные состояния через webhook-события. / 400 Отсутствуют или неверно указаны параметры (нет service_code или country_code, неверный формат Idempotency-Key и т.д.). / 412 Фактическая цена превышает лимит стоимости (max_price_cents). Код ошибки: PRICE_CHANGED. / 422 Недостаточно средств (INSUFFICIENT_BALANCE), кошелёк не инициализирован (WALLET_NOT_INITIALIZED) или номера для данной комбинации сервис/страна временно недоступны (SERVICE_NOT_AVAILABLE).
POST	/v1/orders/{id}/cancel	Отменить заказ	200 Отмена принята. Если заказ уже в конечном состоянии (completed/expired/failed/cancelled) и его состояние доступно для чтения — возвращает текущий объект заказа идемпотентно, без побочных эффектов. / 404 Заказ не найден или не принадлежит текущему аккаунту. / 409 Заказ уже находится в терминальном состоянии (ORDER_ALREADY_TERMINAL). Используйте полученное терминальное webhook-событие или обратитесь в поддержку для сверки. / 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

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

Создаёт заказ на номер для указанного сервиса и страны. Готовность номера и SMS передаётся событиями order.number_allocated и order.completed. Добавьте X-Idempotency-Key для защиты от дублирования при ретраях.

Параметры

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

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

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

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

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

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

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

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

Коды ответов

201

Заказ создан. Получайте номер, SMS и терминальные состояния через webhook-события.

400

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

412

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

422

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

POST/v1/orders/{id}/cancel

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

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

Параметры

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

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

Коды ответов

200

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

404

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

409

Заказ уже находится в терминальном состоянии (ORDER_ALREADY_TERMINAL). Используйте полученное терминальное webhook-событие или обратитесь в поддержку для сверки.

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…"
}
// Receive lifecycle updates through Webhook events:
//   order.number_allocated → phone_number is ready
//   order.completed        → sms_code is ready
//   order.failed / order.expired → terminal error states

Open API включает 50 пробных вызовов. После пробного периода требуется включённый и проверенный webhook. Получайте номер и SMS через webhook-события.

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

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

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

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

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

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

401

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

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

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

403

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

API Key действителен, но доступ заблокирован: пробный период исчерпан без проверенного webhook (WEBHOOK_REQUIRED) или статус аккаунта ограничен.

Включите и проверьте webhook в дашборде. Если ограничение сохраняется, обратитесь в поддержку.

409

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

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

Используйте терминальное webhook-событие и не повторяйте операции записи вслепую. Для сверки обратитесь в поддержку.

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, обработка в рабочие часы

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