Автоматизація прийому 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. Якщо ви працюєте у великому масштабі — наприклад, підтримуєте процеси підтвердження одразу для десятків акаунтів — відлічуйте цикл опитування для кожного замовлення окремо. Не ставте їх в один послідовний цикл, інакше раніші номери спливуть, поки ви ще чекаєте на перший.