Automatyzacja odbierania kodów SMS: kompletny przewodnik po API

Strona wystarcza do sporadycznej, jednorazowej rejestracji: kilka kliknięć, czekanie na jednego SMS-a. To już nie wystarcza, gdy piszesz automatyczne testy, skrypt do masowej rejestracji, pipeline CI albo bota, który musi samodzielnie odebrać kod weryfikacyjny bez udziału człowieka. Strona tego nie zrobi. API — tak. Tu znajdziesz wszystko, czego potrzebujesz, aby przejść od zera do działającego procesu.

Krok 1: zdobądź klucz API

Zaloguj się i przejdź do /account/api-keys, aby go utworzyć. Klucze wyglądają jak jm_ plus losowy ciąg znaków. Klucz w postaci zwykłego tekstu jest pokazywany tylko raz — przechowujemy jego hash, nie sam klucz, więc nie ma opcji „przywróć mój klucz", jeśli go zgubisz. Usuń go i utwórz nowy.

Każde żądanie korzysta ze standardowej autoryzacji Bearer:

Authorization: Bearer jm_your_key

Traktuj klucz jak hasło — nie commituj go do publicznego repozytorium, nie wklejaj go na czacie, żeby ktoś pomógł ci debugować. Jeśli podejrzewasz wyciek, wróć do /account/api-keys, usuń go i wygeneruj nowy; stary przestaje działać natychmiast.

Krok 2: wybierz usługę i kraj

Do złożenia zamówienia potrzebne są dwie rzeczy: service (kod usługi) i country (identyfikator kraju). Zacznij od pobrania listy katalogu:

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

Każdy element ma pole code (dla Telegrama to tg) — przekaż je bezpośrednio do endpointu zamówienia, to pewniejsze niż samodzielne odtwarzanie slug-a. Aby zobaczyć aktualne ceny i dostępność dla konkretnej usługi we wszystkich krajach, dodaj parametr service:

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

Każdy wpis w items ma countryId / priceCents / count (aktualną liczbę dostępnych numerów). Sprawdź count przed złożeniem zamówienia — zero oznacza, że zamówienie się nie powiedzie, więc nie trać zapytania, żeby się o tym przekonać na własnej skórze.

Krok 3: złóż zamówienie

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"}'

Poprawne zamówienie zwraca numer telefonu i czas wygaśnięcia:

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

Obciążenie następuje właśnie na tym etapie — chargedCents to kwota, która została faktycznie pobrana (w centach). Przekaż ten numer do docelowej aplikacji, aby odebrać kod weryfikacyjny, a potem przejdź do kolejnego kroku.

Krok 4: odpytuj, aby uzyskać kod

Nie ma tu WebSocketu ani powiadomień webhook — treść SMS-a otrzymujesz, odpytując GET /api/v1/orders/:id, aż smsBody przestanie być 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

Pięć sekund to rozsądny punkt wyjścia — numer jest aktywny 15 minut, a limit 60 zapytań na minutę dla odczytu daje duży zapas. Trzy sekundy też się sprawdzą, jeśli nie masz cierpliwości; odpytywanie co sekundę nie przyspiesza otrzymania kodu, tylko szybciej zużywa limit zapytań.

Pułapki

• Limity zapytań dotyczą użytkownika, nie klucza. Endpointy zapisu (order / cancel / next-sms) są ograniczone do 10 zapytań na minutę na użytkownika; zapytania odczytu — do 60 na minutę. Tworzenie kolejnych kluczy nie podnosi limitu — wszystkie dzielą ten sam limit.
• Numery wygasają po 15 minutach. Nieużywany numer, który wygasł bez odebrania kodu, jest zwracany automatycznie — nie musisz o to prosić. Ale jeśli twój własny pipeline trzyma numer za długo, zanim faktycznie go wykorzysta (np. zawiśnie w kolejce), do czasu jego użycia numer będzie już nieaktywny.
• Jeden numer może odebrać więcej niż jeden kod. Jeśli docelowa aplikacja wysyła SMS-y w dwóch etapach (potwierdzenie rejestracji, a potem osobny kod logowania), wywołaj POST /api/v1/orders/:id/next-sms po otrzymaniu pierwszego, aby poinformować nas „z tym koniec, słuchaj dalej" — nie trzeba składać nowego zamówienia na nowy numer.
• Po otrzymaniu kodu anulowanie przestaje działać. POST /api/v1/orders/:id/cancel zwraca środki natychmiast, dopóki numer wciąż czeka na kod. Gdy jednak smsBody choć raz stanie się niepuste, to samo wywołanie zwróci zamiast tego błąd CODE_RECEIVED — już otrzymałeś to, za co zapłaciłeś, więc nie da się tego wycofać.
• Nie sprawdzaj statusu tylko raz i nie poddawaj się. status zmienia się z WAITING na RECEIVED. Jeśli utrzymuje się na WAITING do momentu wygaśnięcia, to zwykle problem ze wskaźnikiem dostarczalności dla konkretnej kombinacji kraj/usługa — złożenie nowego zamówienia w innym kraju zazwyczaj rozwiązuje sprawę szybciej niż czekanie.

Co dalej

To pokrywa główny przepływ od zamówienia do odebrania kodu. Pełna lista pól, kodów błędów i przypadków granicznych dla każdego endpointu znajduje się na stronie /api-docs. Jeśli działasz w większej skali — na przykład utrzymujesz procesy weryfikacji dla dziesiątek kont jednocześnie — mierz czas odpytywania dla każdego zamówienia niezależnie. Nie ustawiaj ich w jednej sekwencyjnej kolejce, bo wcześniejsze numery wygasną, gdy wciąż będziesz czekać na pierwszy.