Документация

1. Как это устроено

1. Вы регистрируетесь, подтверждаете почту, указываете номер SIM и получаете ссылку настройки в разделе «Телефон».
2. На Android-телефоне с этой SIM стоит приложение «СМС-шлюз» (ru.teamcraft.smsgate). Открытая на телефоне ссылка подставляет адрес очереди и токен; вы нажимаете «Сохранить» и включаете рассылку.
3. Приложение раз в 15 минут забирает очередь (pull), отправляет СМС и сообщает результат по каждому (ack). Всё через HTTPS, токен только в заголовке.
4. Ваша система кладёт сообщения в очередь через API с ключом из раздела «API-ключ» или вы делаете это вручную в «Сообщениях».

Тестовое СМС с кодом на ваш же номер SIM подтверждает, что номер указан верно; до этого API сообщения не принимает.

2. Лимиты и правила

• Не больше 15 СМС в час на телефон — считает сервер, по числу выдач приложению. Паузу «не чаще 1 СМС в минуту» держит само приложение, сервер сообщает её в поле min_gap_sec. Это защита номера от блокировки оператором.
• Суточная квота — по тарифу: на тарифе «Бесплатный» 10 сообщений за календарные сутки, с 00:00 по московскому времени. Сообщение засчитывается, когда телефон впервые его забрал, и остаётся засчитанным при любом исходе: отправлено, ошибка, отказ, отмена после ошибки. Автоповтор и «Повторить» после ошибки квоту не тратят; «Повторить» для отказа, засчитанного в прошлые сутки, засчитывается в сегодняшние. Тестовые СМС проверки номера не считаются.
• Страховочный потолок: не больше 100 выдач телефону за 24 часа, считая повторные выдачи и неудачные попытки. Если телефон несколько часов подряд не может отправить (нет денег на SIM, нет сети), потолок выбирается и без отправленных СМС; отказ называет время, когда место начнёт освобождаться.
• Не больше 3 сообщений одному получателю в сутки. Текст — до 4 частей СМС (268 символов кириллицей, 612 латиницей).
• Только служебные уведомления людям, с которыми у вас есть отношения (заказы, записи, доставка). Реклама запрещена условиями.
• Сообщение, выданное телефону, но не подтверждённое сетью, получает статус «без подтверждения»: сервер и телефон его повторно не шлют, решение за вами.
• Тексты и номера получателей хранятся 30 дней после финального статуса, потом затираются.

3. API для вашей системы

Базовый адрес https://freesms.myantares.ru/api/v1, ключ в заголовке Authorization: Bearer fs_live_…. Тело и ответы — JSON, кодировка UTF-8.

POST https://freesms.myantares.ru/api/v1/messages
{"to": "+79990000000", "text": "Заказ 127001 прибыл в пункт выдачи", "ref": "order-127001"}
→ 201 {"ok":true,"id":42,"status":"queued","parts":1,"duplicate":false}
→ 200 {"ok":true,"id":42,"status":"sent","parts":1,"duplicate":true}   (тот же ref повторно)
→ 422 {"ok":false,"code":"recipient_cap","error":"потолок на номер: 3 в сутки"}

GET  https://freesms.myantares.ru/api/v1/messages/42
GET  https://freesms.myantares.ru/api/v1/messages?status=queued&since=0&limit=50
POST https://freesms.myantares.ru/api/v1/messages/42/cancel        (пока телефон не забрал, а также failed до автоповтора)
GET  https://freesms.myantares.ru/api/v1/status                    (телефон, очередь, окна лимитов)

В ответе /status поле limits: plan — тариф; hour — выдачи телефону за последний час; day — квота тарифа за календарные сутки ("max": null — тариф без суточной квоты); attempts — страховочный потолок выдач за 24 часа; can_enqueue — сколько ещё сообщений допускают квота тарифа и страховочный потолок с учётом ждущих в очереди (потолок на получателя, 3 в сутки, и повторы здесь не учтены).

Коды отказа 422 (запрос принят, но отклонён по существу): bad_phone, bad_text, bad_ref, bad_status, no_phone, phone_revoked, sim_unconfirmed, recipient_cap, daily_cap, stopword.
400 bad_json · 401 unauthorized · 403 email_unconfirmed, blocked · 404 not_found · 405 method_not_allowed · 409 already_pulled, already_final · 429 rate_limited (60 запросов в минуту на ключ) · 500 internal.

ref — ваш идентификатор (до 120 символов): повтор с тем же ref в течение 30 дней не создаёт второго сообщения. Без ref одинаковый текст на тот же номер в течение 10 минут считается повтором; отключается "allow_repeat": true.

Статусы: queued → sent · failed (повтор через 30 минут, после 5 подряд — rejected) · rejected · unknown · cancelled.

4. Контракт телефона (для разработчиков)

Адрес очереди https://freesms.myantares.ru/gate.php, токен в заголовках Authorization: Bearer и X-Auth-Token. Полное описание — в исходниках приложения (android/smsgate/README.md).

GET  https://freesms.myantares.ru/gate.php?action=pull&limit=10
→ {"ok":true,"messages":[{"id":42,"phone":"+79990000000","text":"…"}],"limits":{"hour":{"used":3,"max":15},"day":{"used":3,"max":10},"attempts":{"used":4,"max":100},"next_at":null}}
→ {"ok":true,"messages":[],"throttled":true,"queued_left":4,"limits":{…,"next_at":"2026-09-05T12:30:00+03:00"}}

POST https://freesms.myantares.ru/gate.php?action=ack     {"results":[{"id":42,"status":"sent"},{"id":43,"status":"failed","error":"нет сети"}]}
POST https://freesms.myantares.ru/gate.php?action=log     text/plain — отчёт приложения для разбора
POST https://freesms.myantares.ru/gate.php?action=claim   {"code":"…"} без токена — обмен кода из ссылки настройки на токен

Неподтверждённое выдаётся снова, но не раньше чем через 30 минут после выдачи (это 2–3 прохода приложения): пачку из 15 сообщений телефон отправляет до четверти часа, и выдавать её заново раньше нельзя. Повторную отправку предотвращает журнал приложения. Когда очередь непуста, но выдавать нечего — из-за лимита или из-за этой паузы, — ответ приходит с "throttled": true, queued_left и сроком в limits.next_at; пустой ответ без throttled означает, что очередь действительно пуста. Все ошибки — JSON {"ok":false,"error":"…"} с кодами 400/403/429.

5. Приложение

Скачать: APK. Приложение не читает входящие СМС, контакты и другие данные; из разрешений ему нужны отправка СМС, уведомления и исключение из энергосбережения. Обновления ставятся поверх, удалять приложение не нужно: в нём журнал отправленных.

Отчёт для разбора: в приложении «Отчёт → Отправить на сервер» — появится в разделе «Отчёты».