Разработчикам
SMS API Sim7: покупка, статусы и безопасные вебхуки
Начинайте интеграцию с чтения каталога и параметров аккаунта: все доступные клиентские ключи Sim7 боевые. Для покупки сохраняйте Idempotency-Key до запроса, принимайте сообщения через подписанные вебхуки и сверку статуса. Повтор запроса или события не должен превращаться в повторную покупку либо повторную выдачу.

Фото: Luca Bravo / Unsplash
В этой статье
- Начните с ключа и запросов без списания
- Сначала каталог и цена, затем подтверждение пользователя
- Одна покупка — одна сохранённая логическая операция
- Как повторять запрос при потере ответа
- Статусы, несколько SMS и завершение
- Настройте вебхук до создания рабочих заказов
- Проверяйте подпись по исходному телу запроса
- Повтор уведомления не должен повторять бизнес-действие
- Лимиты и мониторинг без утечки сообщений
- Что проверить перед запуском интеграции
Начните с ключа и запросов без списания
Базовый адрес клиентского API — https://sim7.org/api/v1. Создайте отдельный ключ для интеграции в кабинете и выдайте ему только необходимые права: catalog:read для каталога, account:read для аккаунта, orders:read для чтения заказов, orders:write для покупки и действий, webhooks:write для настройки уведомлений. При необходимости ограничьте разрешённые IP или сети CIDR.
Полное значение ключа показывается при создании: сохраните его в серверном хранилище секретов. Не вставляйте ключ в клиентский JavaScript, мобильный пакет, публичный пример, строку URL или журнал ошибок. Передавайте его в заголовке Authorization как Bearer-токен. Если секрет попал в публичное место, отзовите его и выпустите отдельную замену.
Первую проверку делайте запросами чтения: GET /account, /balance, /services и /countries. Они позволяют проверить права, доступность и ограничения без создания номера. Все доступные клиентские ключи — production: POST /numbers выполняет реальную покупку с реальным балансом, а не бесплатную симуляцию.
Получайте действующие лимиты из /account. Не рассчитывайте увеличить пропускную способность созданием дополнительных ключей: ограничения применяются и на уровне аккаунта. В ответах используйте поле currency; суммы API выражены в USD, независимо от рублёвого отображения кабинета.
curl -sS "https://sim7.org/api/v1/account" \
-H "Authorization: Bearer $SIM7_API_KEY"Сначала каталог и цена, затем подтверждение пользователя
Получите ID сервиса из GET /services и ID страны из GET /countries. Не отправляйте вместо них произвольный перевод названия. Для актуальных маршрутов используйте GET /prices?service=... с необязательным параметром country. Ответ содержит итоговую цену, доступность и сведения об успешности, если они известны.
Цена уже включает применимую наценку Sim7. Не прибавляйте её повторно, если ваша задача — показать цену этого API. Если вы добавляете собственную комиссию в своём продукте, показывайте её пользователю явно и учитывайте отдельно от стоимости закупки.
Остаток и цена могут измениться между чтением каталога и покупкой. Поэтому котировку нужно обновлять перед подтверждением, а в запрос покупки передавать max_price — верхнюю допустимую итоговую цену в USD. Это ограничитель суммы, а не гарантия наличия номера по указанной цене.
Не выбирайте только самый дешёвый маршрут без оценки условий. Нулевая доступность и отсутствие статистики — разные ситуации. Данные об успехе относятся к наблюдавшимся доставкам и не обещают, что именно следующая активация сработает.
Одна покупка — одна сохранённая логическая операция
Создание номера выполняется POST /numbers. В JSON обязательны service и country; operator можно задать точно либо оставить автоматический выбор. Параметр max_price рекомендуем передавать всегда, чтобы изменение цены не приводило к неожиданной сумме для пользователя.
До сетевого вызова создайте у себя запись операции с внутренним ID, неизменяемыми параметрами и случайным Idempotency-Key. Если приложение перезапустится после отправки, эта запись позволит восстановить исходный запрос. Генерация нового ключа при каждом повторе сети уничтожает смысл защиты от дублей.
Успешный ответ содержит непрозрачный order_id. Сохраните его вместе со своим заказом, стоимостью и выбранным сервисом. Именно этот ID нужно использовать для чтения и управления в Sim7, а не номер телефона. Телефон не является устойчивым идентификатором бизнес-операции.
Ниже показана форма тела запроса, а не предложение выполнить покупку с этими параметрами. Замените значения результатами актуального каталога и лимитом, подтверждённым вашим пользователем.
POST /api/v1/numbers
Authorization: Bearer <server-side key>
Content-Type: application/json
Idempotency-Key: <persisted operation UUID>
{"service":"nvidia","country":"sweden","operator":"any","max_price":0.50}Как повторять запрос при потере ответа
Каждый изменяющий запрос публичного API требует Idempotency-Key. Точный повтор с тем же ключом возвращает сохранённый результат, если операция завершена. Использование ключа для другого пути, метода или тела вызывает idempotency_conflict. Не исправляйте конфликт слепой сменой ключа: сначала выясните, какой операции он уже принадлежит.
Таймаут соединения не доказывает, что номер не куплен. При idempotency_in_progress исходный запрос ещё выполняется либо его результат требует сверки. Сохраните ключ и параметры, не создавайте замену вслепую. Для поддержки нужны идентификатор вашей операции, время и код ошибки, но не Bearer-секрет.
Документированные отказы до выдачи номера, например insufficient_funds, no_numbers_available или price_changed, отличаются от неопределённого исхода. После устранения причины можно повторить тот же запрос с тем же ключом. Если вы изменили цену или другие параметры, это уже другой запрос: сначала убедитесь, что исходная операция однозначно не создала номер.
Завершённые ответы идемпотентности хранятся семь дней. Не используйте старый ключ как вечную защиту и не повторяйте давно завершённую покупку после этого окна. Ваш собственный журнал операций должен хранить её результат столько, сколько требует бизнес-процесс.
Статусы, несколько SMS и завершение
GET /orders/{order_id} возвращает текущее состояние и сообщения. waiting означает ожидание, code_received — наличие полученного SMS, completed — завершение. cancelled, banned и expired обозначают соответствующие конечные состояния. Не определяйте статус только по наличию номера или непустому полю code.
Используйте массив messages для отображения истории: на один активный номер могут поступить дополнительные SMS. Первое сообщение не должно автоматически запускать POST /orders/{order_id}/finish, если пользователь ещё ожидает повторное подтверждение. Завершение — отдельное осознанное действие.
Отмена и бан применяются к ожидающему заказу с учётом доступности действия, а finish — после получения кода. Для этих POST-запросов также нужен собственный Idempotency-Key. Нельзя считать любой ответ об отмене основанием вручную увеличить баланс: финансовый результат обрабатывается по состоянию заказа.
Для таймера используйте expires_at, а не одинаковые двадцать минут для всех заказов. После закрытия сохранённая история не даёт приёма новых сообщений. Чтение списка /orders с курсором подходит для сверки истории, а не для автоматического повторного создания отсутствующих записей.
Настройте вебхук до создания рабочих заказов
Через PUT /webhook зарегистрируйте свой публичный HTTPS-обработчик на стандартном порту и выберите события. Поддерживаются order.created, order.code_received, order.completed, order.cancelled, order.banned и order.expired. Адрес должен принадлежать вашей интеграции; это не входящий путь на домене Sim7.
Секрет подписи выдаётся при создании или ротации. Сохраните его сразу вместе с номером версии. Повтор идемпотентного ответа не служит хранилищем исходного секрета. Для проверки доступности конфигурации используйте GET /webhook, а не попытки получить секрет повторно.
Sim7 ожидает ответ 2xx в пределах пяти секунд. Уведомления могут повторяться; предусмотрены первая попытка и четыре повтора. Быстро проверяйте подпись, надёжно сохраняйте событие в очередь и подтверждайте приём только после успешного сохранения. Долгую бизнес-обработку выполняйте отдельно.
После отключения обработчика очередь отменяется; события до его создания или во время отключения не гарантированно появятся после включения. Поэтому уведомления дополняют, а не заменяют периодическую сверку состояния важных заказов.
Проверяйте подпись по исходному телу запроса
В X-Sim7-Signature приходит v1= и HMAC-SHA256 в нижнем шестнадцатеричном регистре. Подписывается точная строка времени из X-Sim7-Timestamp, точка и исходные байты JSON. Если сначала разобрать JSON, а затем сериализовать заново, пробелы или порядок полей могут измениться и проверка станет неверной.
Пример ниже проверяет подпись, формат заголовков, размер тела и допустимое отклонение времени пять минут. Этот интервал — политика примера, а не изменение контракта Sim7. Синхронизируйте часы сервера и подбирайте окно с учётом допустимого сетевого запаздывания.
При ротации учитывайте X-Sim7-Secret-Version: уже созданная доставка сохраняет прежнюю версию секрета, но повтор получает свежую метку времени. Храните нужные предыдущие секреты до завершения старой очереди. Не используйте первый попавшийся секрет при неизвестной версии.
Функция только проверяет подлинность. Ограничение размера на уровне HTTP-сервера, безопасный разбор JSON, проверка схемы, дедупликация и обновление вашего заказа остаются отдельными обязательными шагами.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifySim7(rawBody, headers, secretsByVersion, now = Date.now()) {
if (!Buffer.isBuffer(rawBody) || rawBody.length > 65536) return false;
const timestamp = headers.get("x-sim7-timestamp") ?? "";
const signature = headers.get("x-sim7-signature") ?? "";
const version = headers.get("x-sim7-secret-version") ?? "";
if (!/^\d{10}$/.test(timestamp) || !/^v1=[a-f0-9]{64}$/.test(signature)) return false;
if (!/^[1-9]\d{0,5}$/.test(version)) return false;
if (Math.abs(Math.floor(now / 1000) - Number(timestamp)) > 300) return false;
const secret = secretsByVersion.get(Number(version));
if (typeof secret !== "string" || !secret) return false;
const expected = createHmac("sha256", secret)
.update(timestamp).update(".").update(rawBody).digest();
const received = Buffer.from(signature.slice(3), "hex");
return received.length === expected.length && timingSafeEqual(received, expected);
}Повтор уведомления не должен повторять бизнес-действие
После проверки подписи разберите JSON и сопоставьте его id с X-Sim7-Delivery. Сохраните ID доставки в таблице с уникальным ограничением. В одной транзакции зарегистрируйте принятое событие и допустимое изменение своего заказа либо запись в надёжной очереди.
Если такой ID уже обработан, верните успешный ответ без повторной выдачи, покупки или начисления. Если база недоступна, не подтверждайте событие до сохранения: иначе отправитель посчитает доставку успешной, а ваше приложение потеряет её.
Проверьте, что data.order_id относится к ожидаемому заказу вашей интеграции. Новое событие не должно возвращать завершённую операцию в ожидание из-за устаревшего локального состояния. Сохраняйте историю сообщений отдельно от краткого статуса.
Журнал GET /webhook/deliveries помогает увидеть попытки и результат доставки. Если уведомление окончательно не доставлено, прочитайте состояние заказа и выполните контролируемую сверку. Не создавайте новый номер как способ исправить потерянное уведомление.
Лимиты и мониторинг без утечки сообщений
Обрабатывайте ошибки по error.code, а не поиском слов в человекочитаемом тексте. Для 401 проверяйте ключ, для 403 — права и IP, для 429 — ограничивайте нагрузку. Временные 5xx допускают осторожные повторы с задержкой, но при покупке всегда сохраняйте тот же ключ и учитывайте неопределённый результат.
Параллельное чтение статуса не означает столь же частую проверку внешнего маршрута: Sim7 использует локальные снимки и ограничение опроса. Опрос десятки раз в секунду увеличивает нагрузку без гарантии более быстрого кода. Используйте вебхуки и умеренный резервный опрос.
В метриках полезны число покупок, доля ошибок по коду, время ожидания SMS, возраст неподтверждённых операций и неуспешные доставки вебхуков. Не отправляйте тексты SMS, телефоны, токены или секреты подписи в общедоступные логи и стороннюю аналитику.
Настройте ограничения расходов на своей стороне и уведомления о неопределённых покупках. Цель мониторинга — заметить операцию, которая требует сверки, до того, как пользователь начнёт многократно нажимать покупку.
Что проверить перед запуском интеграции
Сначала протестируйте свой обработчик на локальных фикстурах: корректная подпись, изменённое тело, старая метка времени, неизвестная версия секрета и повтор одного ID. Эти тесты не требуют покупать номера. Затем проверьте запросы чтения с отдельным боевым ключом.
Контролируемая реальная покупка должна быть отдельным осознанным тестом с согласованным лимитом. После неё проверьте сохранение order_id, отображение messages, допустимые действия, повтор запроса с прежним ключом и восстановление после перезапуска собственного процесса.
Зафиксируйте дату проверки контракта и ссылку на актуальную документацию. При изменениях API обновляйте интеграционные тесты и тексты интерфейса вместе. Надёжность определяется обработкой повторов и неопределённых результатов, а не только красивым ответом на первый успешный запрос.
Назначьте ответственного за обработку таких инцидентов: у него должны быть безопасные ссылки на журнал операции и заказ, но не открытые секреты. Это сокращает время разбора и позволяет объяснить пользователю фактический результат.
Источники и проверка
Проверено: 2026-11-09 · Редакция Sim7. Интерфейсы и правила сервисов могут изменяться. Перед покупкой сверяйте требования в своём аккаунте.




