Только боевой API. Покупки списывают реальный баланс.
Файлы не содержат ключей. По умолчанию покупка требует явного подтверждения. Не включайте автоматическую замену заказа при таймауте.
Скачать sim7.mjs ↓1. Скачайте клиент и задайте окружение
Нужен Node.js 22.13 или новее с node:sqlite. Скачайте sim7.mjs; сторонние пакеты не нужны. Создайте боевой ключ Sim7 с account:read, catalog:read, orders:read и orders:write. Право webhooks:write нужно только при настройке адреса уведомлений. Ключ не должен попадать в браузер, URL, репозиторий и журнал ошибок.
Задайте SIM7_API_KEY через защищённое окружение процесса, SIM7_STATE_FILE — путь к приватному файлу SQLite на постоянном диске. Не размещайте его в public, временной директории или слое контейнера, который исчезнет при перезапуске. В нём хранятся исходные намерения, подтверждения покупок и входящие события. Ограничьте доступ к файлу и резервным копиям.
Команды ниже рассчитаны на sh/bash. Значения переменных задайте в своём окружении заранее; в PowerShell используйте синтаксис $env:ИМЯ. SIM7_BUSINESS_ID должен происходить из вашей системы заказов и оставаться неизменным при повторе. Сначала выполните только чтение баланса и каталога. Эти команды не создают покупок.
node sim7.mjs balance
node sim7.mjs prices --service openai --country usa2. Купите один номер с защитой повтора
Возьмите service, country и operator из каталога API. max_price задаётся в долларах США с учётом цен именно вашего API-ключа. Это предел, выше которого покупка не должна выполняться, а не сумма в рублях. Проверьте цену и доступность непосредственно перед решением о покупке. Пример ниже требует --confirm, потому что списывает реальный баланс.
До отправки POST клиент сохраняет business_id и точный запрос в SQLite. При повторном запуске после сетевой ошибки он использует тот же Idempotency-Key. Если чек уже сохранён, покупка повторно вообще не вызывается. Изменение параметров для прежнего business_id блокируется локально. Не удаляйте файл состояния и не придумывайте новый ID для проверки неизвестного результата.
Клиент получает стабильный account_id через /account и связывает намерение с отпечатком ключа. Если ключ заменили, а старая покупка не разрешена, отправка блокируется. Неизвестные операции старше шести дней тоже требуют ручной сверки до повторной отправки: нельзя рассчитывать на бесконечное хранение серверного ключа идемпотентности.
node sim7.mjs buy --business-id "$SIM7_BUSINESS_ID" --service openai --country usa --operator any --max-price 0.50 --confirm3. Получайте первый и последующие SMS
Команда покупки возвращает order_id, номер, цену и срок. Сохраните order_id в записи своего клиентского заказа. Номер телефона и внутренний ID вашей системы не заменяют этот идентификатор. Передайте его в watch: клиент читает messages[] каждые пять секунд, отмечает новые сообщения и продолжает работу в status=code_received.
По умолчанию в консоль выводятся статус и количество новых сообщений без текста кодов. Флаг --show-messages выводит содержимое явно: используйте его только в приватной консоли, не в общедоступном журнале CI. В библиотечном интерфейсе watch возвращает order и new_messages, чтобы вы могли показать сообщение авторизованному владельцу своего заказа.
Для второго кода запросите повтор на стороне выбранного сервиса, пока заказ активен. В API Sim7 нет универсального метода «отправить SMS от чужой платформы». Истечение локального времени наблюдения не завершает и не отменяет заказ. Получение кода также не вызывает finish: это отдельное осознанное действие, которое может прекратить дальнейшие сообщения.
node sim7.mjs watch --order-id "$SIM7_ORDER_ID" --seconds 1200
# Private console only:
node sim7.mjs watch --order-id "$SIM7_ORDER_ID" --seconds 1200 --show-messages
# Explicitly finish only when the user is done:
node sim7.mjs finish --order-id "$SIM7_ORDER_ID" --confirmИспользование в Node.js-приложении
ES-модуль экспортирует Client, State, verifyWebhook и webhookServer. Client использует fetch с AbortSignal и запретом redirects, watch — асинхронный итератор. node:sqlite выполняет локальные короткие операции синхронно; не переносите на него тяжёлую аналитику публичного веб-сервера. Для нескольких инстансов используйте общий бизнес-журнал, а не отдельные SQLite-файлы в контейнерах.
Следующий фрагмент действительно вызывает покупку с реального баланса. Запускайте его только после проверки цены и заполнения постоянного SIM7_BUSINESS_ID. В приложении замените вывод счётчика на безопасную выдачу new_messages владельцу своего заказа. Не записывайте сами коды в общий журнал и не вызывайте finish внутри цикла первого сообщения.
import { Client, State } from './sim7.mjs';
const state = new State(process.env.SIM7_STATE_FILE);
try {
const client = new Client(process.env.SIM7_API_KEY, state);
const order = await client.purchase(process.env.SIM7_BUSINESS_ID, {
service: 'openai', country: 'usa', max_price: 0.50,
});
for await (const update of client.watch(order.order_id)) {
console.log(update.order.status, update.new_messages.length);
}
} finally {
state.close();
}4. Примите подписанный вебхук
В том же файле есть HTTP-приёмник POST /webhooks/sim7. Он слушает только 127.0.0.1; поставьте перед ним свой HTTPS reverse proxy и закройте прямой доступ к порту извне. В Sim7 настройте свой публичный HTTPS URL через PUT /api/v1/webhook с отдельным Idempotency-Key или средствами кабинета. Секрет показывается при создании: сохраните его в защищённом окружении, не выводите в публичную консоль.
SIM7_WEBHOOK_SECRETS — JSON-объект версий, например ключ версии 1 со значением выданного whsec-секрета. При ротации сохраняйте нужные старые версии для уже поставленных в очередь доставок. Приёмник проверяет X-Sim7-Secret-Version, время с допуском пять минут и HMAC-SHA256 от timestamp, точки и исходных байтов тела. Нельзя сначала разобрать JSON и заново сериализовать его для подписи.
Затем проверяются подписанный ID и тип события, а запись попадает в inbox SQLite с уникальным ID доставки. Повторное событие получает 200 без новой записи. При ошибке сохранения ответ 503 оставляет возможность повторной доставки. Отправитель ожидает успешный HTTP-ответ, но такой ответ не должен предшествовать надёжной записи события.
node sim7.mjs webhook --port 80805. Подключите свою выдачу и учёт
Приёмник сохраняет события, но не начисляет деньги и не выдаёт товар автоматически. Ваш worker читает inbox WHERE processed=0. Изменение своего заказа, исключение повторной выдачи и processed=1 должны выполняться в одной бизнес-транзакции. Для внешней отправки используйте transactional outbox и стабильный ключ операции. Нельзя сначала отметить событие обработанным, а потом пробовать выполнить необратимое действие.
Сверяйте принадлежность order_id клиенту в своей базе, а не доверяйте ID из URL посетителя. Вебхуки могут повторяться и приходить не по порядку; при сомнении прочитайте актуальный GET /orders/{id}. Храните свою историю переходов и не позволяйте позднему событию вернуть завершённый заказ в ожидание. Статусы completed, cancelled, banned и expired терминальные, code_received — нет.
Обработчик не обеспечивает магическое exactly-once для внешних действий: это зависит от транзакции и идемпотентности вашей системы. Защита покупки также требует сохранного состояния и прежнего ключа при повторах. Для нескольких серверов замените локальный SQLite общей транзакционной базой с теми же уникальными ограничениями; не заводите отдельную независимую историю заказов на каждом инстансе.
Ошибки: когда остановиться
Сеть, 5xx, idempotency_in_progress и 429 обрабатываются ограниченным числом повторов с тем же ключом. Retry-After учитывается; чрезмерный или непонятный интервал останавливает автоматический повтор. idempotency_conflict, price_changed, insufficient_funds и ошибки входных данных не должны создавать новую покупку автоматически. Сначала выясните результат первоначальной операции.
Результат неизвестен — не значит, что покупки не было. Сохраните business_id, order_id при наличии и время, затем сверяйте историю своего аккаунта или обращайтесь в поддержку. Не используйте смену ключа, удаление SQLite или увеличение max_price как способ проверить старый результат. Отдельная новая покупка должна быть отдельным подтверждённым решением клиента.

