Миграция со smsc.ru и SigmaSMS¶
Страница для интегратора, который сейчас шлёт SMS через smsc.ru или SigmaSMS: что меняется в подходе, как соотносятся статусы и коды ошибок и как переключиться, не потеряв путь назад.
Коды и статусы сторонних шлюзов взяты из их публичной документации на 2026-09-21:
- smsc.ru — «Отправка сообщений. Ответ сервера и коды ошибок» и «Коды статусов»;
- SigmaSMS — перечень состояний в официальном репозитории примеров
sigmasms/api-examples.
Если у вас в логах встречается код, которого здесь нет, пришлите его нам: таблица дополнится.
Что меняется в подходе¶
| Было | Стало | Почему |
|---|---|---|
| Текст сообщения целиком в запросе | шаблон и значения переменных | оператор принимает только зарегистрированные шаблоны; свободный текст отклонил бы он, мы отклоняем раньше |
| Имя отправителя — любое из заведённых в личном кабинете | отправитель регистрируется у оператора через нас | сообщение с незарегистрированным именем оператор не пропустит |
| Опрос статуса по ID | вебхуки, опрос — как запасной путь | опрос даёт задержку и лишнюю нагрузку, а вебхук приходит сам |
| Защита от дублей — на стороне шлюза и по времени (smsc.ru: ошибка 9) | Idempotency-Key и client_ref |
повтор с тем же ключом безопасен 24 часа, а не минуту; дольше — пока хранится сообщение — защищает client_ref |
| Каскад SMS → звонок → flashcall (SigmaSMS) | только SMS | голосовых каналов и flashcall у хаба нет; каскад, если он нужен, остаётся у вас |
Отложенная отправка (time у smsc.ru) |
не поддерживается, 422 send_at_not_supported |
см. Ограничения MVP |
| Баланс шлюза | предел расхода, поставленный заказчиком | хаб внутренний и ничего не продаёт; граница — договорённость, а не деньги на счёте |
Статусы¶
Статусы хаба описаны в Статусах и их проверке. У хаба их шесть,
и терминальный — окончательный: признак final не откатывается. Причина
неудачи — в отдельном поле reason_code, а не в номере статуса.
smsc.ru¶
| smsc.ru | Статус хаба | Примечание |
|---|---|---|
-3 Сообщение не найдено |
404 not_found на GET /v1/messages/{id} |
чужое и несуществующее сообщение отвечают одинаково |
-2 Остановлено |
— | остановки рассылки у хаба нет; сообщение, принятое к отправке, уходит |
-1 Ожидает отправки |
accepted |
принято, оператору ещё не передано |
0 Передано оператору |
sent |
|
1 Доставлено |
delivered |
|
2 Прочитано |
delivered + событие message.seen |
прочтение не статус: delivered остаётся терминальным |
3 Просрочено |
expired |
причина различает три случая: «оператор сам перестал ждать» (dlr_timeout — доставки не будет), «отчёта не было до нашего срока» (dlr_timeout_local — могло дойти, ждать позднего отчёта) и «оператору не передавали вовсе» (ttl_expired_before_submit — повтор безопасен). См. Статусы |
4 Нажата ссылка |
— | сокращения ссылок у хаба нет |
20 Невозможно доставить |
undelivered |
причина в reason_code: недоступен, не существует, заблокирован |
22 Неверный номер |
422 recipient_invalid на приёме |
номер проверяется до создания сообщения, сообщение не создаётся |
23 Запрещено |
зависит от причины, см. ниже | у smsc.ru это один код на пять разных ситуаций |
24 Недостаточно средств |
422 spend_limit_reached на приёме |
повтор не поможет, предел двигает человек |
25 Недоступный номер |
undelivered или rejected |
причина в reason_code |
Код 23 у smsc.ru объединяет разное. В хабе это разные ответы, и реагировать
на них нужно по-разному:
Что стояло за 23 |
В хабе | Что делать |
|---|---|---|
| дубль | повтор с тем же Idempotency-Key возвращает прежний ответ, второго сообщения нет |
ничего: это и есть защита |
| частые сообщения на один номер | 422 recipient_flood_limited, обычно с retry_after |
подождать retry_after; для кодов — обратный отсчёт в интерфейсе. Если счётчик временно недоступен, отказ приходит без retry_after — отсчёт от несуществующего поля строить нельзя, нужен запасной интервал |
| номер в чёрном списке | 422 recipient_opted_out |
не отправлять; на одноразовые коды отписка не действует |
| запрещённый текст | rejected, spam_filter_content |
исправить шаблон |
| запрещённое имя отправителя | 422 sender_not_registered на приёме или rejected, spam_filter_sender |
отправитель регистрируется через нас |
SigmaSMS¶
| SigmaSMS | Статус хаба | Примечание |
|---|---|---|
pending, processing |
accepted |
|
paused |
— | приостановки у хаба нет |
sent |
sent |
|
delivered |
delivered |
|
seen |
delivered + событие message.seen |
прочтение не статус |
failed |
undelivered или rejected |
rejected — в эфир не ушло и не тарифицируется; причина в reason_code |
Ответ SigmaSMS pending на отправке означает «принято шлюзом», а не
«доставлено». Ровно так же 202 хаба со статусом accepted. Доставку
подтверждает только delivered.
Коды ошибок отправки smsc.ru¶
| smsc.ru | В хабе | Примечание |
|---|---|---|
1 Ошибка в параметрах |
422 с конкретным кодом |
хаб называет, какой параметр и что с ним не так, см. Ошибки |
2 Неверный логин или пароль (или адрес не из разрешённых) |
401 invalid_api_key |
адрес вне списка ключа даёт тот же 401: иначе ответ подтверждал бы, что ключ верен |
3 Недостаточно средств |
422 spend_limit_reached |
|
4 IP временно заблокирован из-за частых ошибок |
429 rate_limited |
блокировка есть только за неудачные входы: больше 20 за минуту с одного адреса. Темп обычных запросов ограничивается тем же 429 rate_limited на ключ, см. Лимиты |
5 Неверный формат даты |
422 send_at_not_supported |
отложенной отправки нет |
6 Сообщение запрещено (текст или отправитель) |
422 template_* или sender_not_registered на приёме, rejected у оператора |
свободного текста нет, поэтому запрещённый текст ловится на регистрации шаблона |
7 Неверный формат номера |
422 recipient_invalid |
формат — E.164, +79… |
8 Сообщение не может быть доставлено |
422 recipient_opted_out на приёме или undelivered позже |
|
9 Одинаковые запросы или слишком много одновременных |
повтор с тем же Idempotency-Key — прежний ответ, превышение темпа — 429 rate_limited с Retry-After |
отдельно — 429 hub_daily_limit_reached (исчерпан суточный предел хаба, пауза до полуночи UTC) и 503 provider_unavailable (временно не можем принять; одноразовый код — повторить с тем же ключом), см. Ошибки |
Главное отличие: у smsc.ru код ошибки — число в теле ответа 200. У хаба
отказ — HTTP-статус и объект ошибки с кодом, ссылкой на
документацию и request_id. Обработчик вида «если в ответе есть ERROR» при
переезде надо переписать под HTTP-статусы.
Переключение¶
- Шаблоны и отправитель. Пришлите нам тексты и имя отправителя. Мы
регистрируем их у оператора; модерацию проводит оператор, это занимает
время. Параллельно считаем число частей
(
POST /v1/templates/{id}/render): кириллица помещается в 70 символов, если часть одна, и в 67 на часть, если частей несколько (латиница — 160 и 153). - Песочница. Тестовым ключом интеграция проверяется целиком, без отправки живым людям и без ожидания модерации (Песочница).
- Сертификация. По чек-листу, который мы присылаем вместе с ключом. По его итогам выпускается боевой ключ.
- Переключение по частям, за флагом на вашей стороне: сначала малая доля одноразовых кодов, затем все коды, затем рассылки.
- Старый контракт живёт не меньше 30 дней после полного переключения. Пока он жив, откат — это ваш флаг, без нашего участия. После отключения старого контракта откатываться некуда.
Параллельно два шлюза для одного и того же сообщения не используйте: абонент получит два экземпляра. Флаг решает, через какой шлюз уходит сообщение, а не «через оба на всякий случай».