Dokumentacja API

REST API do wsadowego / zautomatyzowanego dostępu do jiema.my. Użyj go, aby zintegrować weryfikację SMS we własnych usługach. Wszystkie endpointy zwracają JSON.

Zaloguj się, aby utworzyć swój pierwszy klucz API.

Spis treści

Uwierzytelnianie
Błędy i limity częstotliwości
GET /v1/account
GET /v1/services
GET /v1/countries
GET /v1/prices
POST /v1/orders
GET /v1/orders/:id
POST /v1/orders/:id/cancel
POST /v1/orders/:id/next-sms
GET /v1/orders
Typowy przepływ pracy

Uwierzytelnianie

Każde żądanie musi zawierać Twój klucz API:

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternatywna forma nagłówka: X-API-Key: jm_xxx…

Twórz i unieważniaj klucze pod /account/api-keys. Każdy użytkownik może mieć do 10 aktywnych kluczy. Pełny token jest pokazywany tylko raz, przy tworzeniu — przechowuj go w bezpiecznym miejscu.

Błędy i limity częstotliwości

Wszystkie błędy zwracają JSON:

{ "ok": false, "code": "RATE_LIMITED", "message": "..." }

HTTP	kod	znaczenie
401	AUTH_MISSING / AUTH_INVALID	Brak klucza lub klucz unieważniony
403	FORBIDDEN	Zbanowany lub brak dostępu
400	BAD_REQUEST / INSUFFICIENT / NO_NUMBERS / …	Błąd walidacji lub logiki biznesowej
404	NOT_FOUND	Zamówienie nie istnieje (lub nie należy do Ciebie)
429	RATE_LIMITED	Limit częstotliwości na klucz
500	INTERNAL	Błąd serwera (automatycznie zgłoszony)

Limity częstotliwości: Na klucz, przesuwne okno 60s. Endpointy zapisu (orders, cancel, next-sms) 10 req/min; endpointy odczytu (account, services, prices, list) 60 req/min.

GET /v1/account

Pobierz bieżące saldo i podstawowy profil.

curl https://jiema.my/api/v1/account \
  -H "Authorization: Bearer jm_xxx"

# 200 OK
{ "ok": true, "data": {
  "id": "clxxxxxxxxxxx",
  "balanceCents": "1200",       // string to preserve precision; $12.00
  "referralCode": "abc123",
  "displayName": "Alice",
  "lang": "en"
}}

GET /v1/services

Lista usług z dostępnością. Cache po stronie serwera ~5 min.

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

{ "ok": true, "data": { "items": [
  { "code": "tg", "slug": "telegram", "name": "Telegram",
    "minCostUsd": 0.18, "totalCount": 1234, "countryCount": 24 },
  ...
] }}

Użyj code (lub przyjaznego slug) jako pola service przy tworzeniu zamówienia.

GET /v1/countries

curl https://jiema.my/api/v1/countries -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "items": [
  { "id": 7, "slug": "my", "name": "Malaysia" },
  ...
] }}

id to numeryczne id kraju u dostawcy; slug to krótki kod SEO (np. "my" / "us"). W polu country działa każda z form.

GET /v1/prices?service=tg

Cena i dostępność wg krajów dla danej usługi. Ceny uwzględniają już narzut/rabat skonfigurowany przez zespół ops.

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

{ "ok": true, "data": {
  "service": "tg",
  "items": [
    { "countryId": 7, "countrySlug": "my", "priceCents": "32", "count": 540 },
    ...
  ]
}}

POST /v1/orders

Utwórz zamówienie weryfikacji SMS. System rezerwuje numer u dostawcy i pobiera odpowiednią kwotę z Twojego salda.

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_xxx" \
  -H "content-type: application/json" \
  -d '{ "service": "tg", "country": 7 }'

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "WAITING",
  "service": "tg",
  "country": "7",
  "phone": "+60123456789",
  "expiresAt": "2026-05-22T08:30:00.000Z",
  "chargedCents": "32"
}}

Brak pól opcjonalnych poza service / country.

Typowe kody błędów: INSUFFICIENT (wymagane doładowanie), NO_NUMBERS, BAD_SERVICE, BAD_COUNTRY.

GET /v1/orders/:id

Odpytuj, aż status osiągnie RECEIVED, a smsBody będzie niepusty.

curl https://jiema.my/api/v1/orders/ckxxxxx -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "RECEIVED",
  "phone": "+60123456789",
  "smsBody": "Your verification code is 123456",
  "smsHistory": [
    { "body": "Your verification code is 123456", "receivedAt": "..." }
  ],
  "smsReceivedAt": "2026-05-22T08:12:34.000Z",
  ...
}}

Statusy: WAITING (numer aktywny, czeka na SMS) · RECEIVED (kod nadszedł) · COMPLETED / FAILED / CANCELLED są terminalne.

Sugerowane odpytywanie: co 3–5 sekund. Synchronizacja z dostawcą działa wewnątrz tego endpointu, więc odpytywanie posuwa stan do przodu nawet wtedy, gdy worker w tle jest zajęty.

POST /v1/orders/:id/cancel

Anuluj zamówienie, do którego nie nadszedł jeszcze żaden kod. Pełny zwrot na saldo.

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/cancel \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "CANCELLED" }}

Odrzucone z CODE_RECEIVED, jeśli numer otrzymał już jakikolwiek SMS, lub z ALREADY_CHANGED, jeśli status zmienił się równolegle.

POST /v1/orders/:id/next-sms

Po RECEIVED — poproś dostawcę o utrzymanie numeru aktywnym i czekaj na kolejny SMS (bez dodatkowej opłaty w aktywnym oknie).

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/next-sms \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "WAITING" }}

GET /v1/orders

Lista Twoich ostatnich zamówień z paginacją kursorową.

curl "https://jiema.my/api/v1/orders?limit=20" -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "items": [ { "id": "ck...", "status": "RECEIVED", "service": "tg", ... }, ... ],
  "nextCursor": "ck..." | null
}}

Parametry opcjonalne: status · limit 1–100 (domyślnie 20) · cursor = nextCursor z poprzedniej strony.

Typowy przepływ pracy

Doładuj saldo przez interfejs www → GET /v1/account, aby potwierdzić saldo.
Wybierz usługę: GET /v1/services i GET /v1/prices?service=tg.
Utwórz zamówienie: POST /v1/orders z service + country.
Odczytaj data.phone i wywołaj wysłanie SMS u dostawcy ze swojej strony (np. wklej numer do rejestracji Telegram).
Odpytuj GET /v1/orders/:id co 3–5s. Gdy status === "RECEIVED", odczytaj smsBody.
Jeśli SMS jest błędny lub chcesz drugi kod: POST /v1/orders/:id/next-sms → powrót do WAITING.
Gotowe. Jeśli anulujesz, zanim nadejdzie jakikolwiek SMS: POST /v1/orders/:id/cancel — pełny zwrot.

jiema.my