Автоматизация приёма SMS-кодов: полное руководство по API

Сайта достаточно для случайной разовой регистрации: пара кликов, ожидание одной смс. Этого недостаточно, когда вы пишете автоматизированные тесты, скрипт массовой регистрации, CI-пайплайн или бота, которому нужно самостоятельно получить код подтверждения без участия человека. Сайт для этого не годится. API — годится. Здесь есть всё необходимое, чтобы пройти путь от нуля до работающего процесса.

Шаг 1: получите API-ключ

Войдите в аккаунт и перейдите на /account/api-keys, чтобы создать ключ. Ключи выглядят как jm_, за которым следует случайная строка. Ключ в открытом виде показывается только один раз — мы храним его хеш, а не сам ключ, поэтому функции «восстановить ключ» не существует, если вы его потеряли. Удалите его и создайте новый.

Каждый запрос использует стандартную Bearer-авторизацию:

Authorization: Bearer jm_your_key

Относитесь к ключу как к паролю — не публикуйте его в открытом репозитории, не отправляйте в чат, чтобы кто-то помог вам с отладкой. Если подозреваете утечку, вернитесь на /account/api-keys, удалите ключ и выпустите новый; старый перестанет работать немедленно.

Шаг 2: выберите сервис и страну

Для размещения заказа нужны два параметра: service (код сервиса) и country (идентификатор страны). Начните со списка каталога:

curl https://jiema.my/api/v1/services \
  -H "Authorization: Bearer jm_your_key"

У каждого элемента есть поле code (для Telegram это tg) — передавайте его прямо в эндпоинт заказа, это надёжнее, чем самостоятельно собирать slug. Чтобы увидеть актуальные цены и наличие номеров для конкретного сервиса по всем странам, добавьте параметр service:

curl "https://jiema.my/api/v1/prices?service=tg" \
  -H "Authorization: Bearer jm_your_key"

У каждой записи в items есть countryId / priceCents / count (текущее количество доступных номеров). Проверяйте count перед заказом — ноль означает, что заказ не пройдёт, так что не тратьте лишний запрос, чтобы убедиться в этом на практике.

Шаг 3: разместите заказ

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"6"}'

Успешный заказ возвращает номер телефона и время истечения:

{
  "ok": true,
  "data": {
    "id": "cm...",
    "status": "WAITING",
    "phone": "62812xxxxxxx",
    "expiresAt": "2026-08-01T12:15:00.000Z",
    "chargedCents": "40"
  }
}

Списание происходит именно на этом шаге — chargedCents — это сумма, которая была фактически списана (в центах). Передайте этот номер целевому приложению для получения кода подтверждения, а затем переходите к следующему шагу.

Шаг 4: опрашивайте, чтобы получить код

Здесь нет ни WebSocket, ни webhook-уведомлений — содержимое SMS вы получаете, опрашивая GET /api/v1/orders/:id, пока smsBody не перестанет быть null:

while true; do
  RESP=$(curl -s https://jiema.my/api/v1/orders/$ORDER_ID \
    -H "Authorization: Bearer jm_your_key")
  BODY=$(echo "$RESP" | jq -r '.data.smsBody')
  if [ "$BODY" != "null" ]; then
    echo "Code received: $BODY"
    break
  fi
  sleep 5
done

Пять секунд — разумная отправная точка: номер действителен 15 минут, а лимит в 60 запросов в минуту на чтение оставляет большой запас. Три секунды тоже подойдут, если не терпится; опрос раз в секунду не приближает получение кода, а просто быстрее расходует лимит запросов.

Подводные камни

• Лимиты запросов действуют на пользователя, а не на ключ. Эндпоинты записи (order / cancel / next-sms) ограничены 10 запросами в минуту на пользователя; запросы на чтение — 60 в минуту. Создание дополнительных ключей не поднимает потолок — все они делят один и тот же лимит.
• Номера истекают через 15 минут. Неиспользованный номер, который истёк без получения кода, возвращается автоматически — просить об этом не нужно. Но если ваш собственный пайплайн держит номер слишком долго перед тем, как его использовать (застрял в очереди, например), к моменту использования он уже будет недействителен.
• Один номер может принять больше одного кода. Если целевое приложение отправляет SMS в два этапа (сначала подтверждение регистрации, затем отдельный код входа), вызовите POST /api/v1/orders/:id/next-sms после получения первого кода, чтобы сообщить нам «с этим готово, продолжайте слушать» — новый заказ для нового номера не потребуется.
• После получения кода отмена перестаёт работать. POST /api/v1/orders/:id/cancel мгновенно возвращает деньги, пока номер ещё ждёт код. Но как только smsBody хотя бы раз становится непустым, тот же вызов вместо этого возвращает ошибку CODE_RECEIVED — вы уже получили то, за что платили, откатить это нельзя.
• Не проверяйте статус один раз и не бросайте попытки. status меняется с WAITING на RECEIVED. Если он остаётся WAITING до истечения срока — это обычно проблема с показателем доставки для конкретной пары страна/сервис: новый заказ в другой стране обычно решает вопрос быстрее, чем ожидание.

Что дальше

Это покрывает основной путь от заказа до получения кода. Полный список полей, кодов ошибок и граничных случаев для каждого эндпоинта — на странице /api-docs. Если вы работаете в большом масштабе — например, поддерживаете процессы подтверждения сразу для десятков аккаунтов — отсчитывайте цикл опроса для каждого заказа независимо. Не ставьте их в один последовательный цикл, иначе более ранние номера истекут, пока вы всё ещё ждёте первый.