Документація API

REST API для пакетного / автоматизованого доступу до jiema.my. Використовуйте його, щоб інтегрувати SMS-верифікацію у власні сервіси. Усі ендпоінти повертають JSON.

Увійдіть, щоб створити свій перший API-ключ.

Зміст

Автентифікація
Помилки та обмеження частоти
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
Типовий робочий процес

Автентифікація

Кожен запит повинен містити ваш API-ключ:

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Альтернативна форма заголовка: X-API-Key: jm_xxx…

Створюйте та відкликайте ключі на /account/api-keys. Кожен користувач може мати до 10 активних ключів. Повний токен показується лише один раз під час створення — зберігайте його надійно.

Помилки та обмеження частоти

Усі помилки повертаються у JSON:

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

HTTP	код	значення
401	AUTH_MISSING / AUTH_INVALID	Ключ відсутній або відкликаний
403	FORBIDDEN	Заблоковано або немає доступу
400	BAD_REQUEST / INSUFFICIENT / NO_NUMBERS / …	Помилка валідації або бізнес-логіки
404	NOT_FOUND	Замовлення не існує (або не ваше)
429	RATE_LIMITED	Обмеження частоти по ключу
500	INTERNAL	Помилка сервера (автоматично зареєстрована)

Обмеження частоти: На ключ, ковзне вікно 60s. Ендпоінти запису (orders, cancel, next-sms) 10 req/min; ендпоінти читання (account, services, prices, list) 60 req/min.

GET /v1/account

Отримати поточний баланс і базовий профіль.

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

Список сервісів із наявністю номерів. Кешується на сервері ~5 хв.

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 },
  ...
] }}

Використовуйте code (або зручний slug) у полі service під час створення замовлення.

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 — це числовий id країни постачальника; slug — це короткий SEO-код (наприклад, "my" / "us"). У полі country приймається будь-який варіант.

GET /v1/prices?service=tg

Ціна та наявність по країнах для заданого сервісу. Ціни вже включають націнку/знижку, налаштовану операторами.

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

Створити замовлення на SMS-верифікацію. Система резервує номер у постачальника та списує відповідну суму з вашого балансу.

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

Окрім service / country, інших необов'язкових полів немає.

Поширені коди помилок: INSUFFICIENT (потрібне поповнення), NO_NUMBERS, BAD_SERVICE, BAD_COUNTRY.

GET /v1/orders/:id

Опитуйте, доки status не стане RECEIVED, а smsBody не буде непорожнім.

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",
  ...
}}

Статуси: WAITING (номер активний, очікування SMS) · RECEIVED (код отримано) · COMPLETED / FAILED / CANCELLED — кінцеві.

Рекомендований інтервал опитування: кожні 3–5 секунд. Синхронізація з постачальником виконується всередині цього ендпоінта, тож опитування просуває стан, навіть якщо фоновий воркер зайнятий.

POST /v1/orders/:id/cancel

Скасувати замовлення, за яким ще не надійшов код. Повне повернення коштів на баланс.

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

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

Відхиляється з CODE_RECEIVED, якщо номер уже отримав будь-яке SMS, або з ALREADY_CHANGED, якщо статус було змінено паралельно.

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

Після RECEIVED — попросити постачальника тримати номер активним і чекати на ще одне SMS (без додаткової оплати в межах активного вікна).

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

Список ваших нещодавніх замовлень з курсорною пагінацією.

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

Необов'язкові параметри: status · limit 1–100 (за замовчуванням 20) · cursor = nextCursor попередньої сторінки.

Типовий робочий процес

Поповніть баланс через веб-інтерфейс → GET /v1/account для підтвердження балансу.
Виберіть сервіс: GET /v1/services та GET /v1/prices?service=tg.
Створіть замовлення: POST /v1/orders з service + country.
Прочитайте data.phone і ініціюйте надсилання SMS у постачальника зі свого боку (наприклад, вставте номер у форму реєстрації Telegram).
Опитуйте GET /v1/orders/:id кожні 3–5s. Коли status === "RECEIVED", читайте smsBody.
Якщо SMS прийшло не те або потрібен другий код: POST /v1/orders/:id/next-sms → назад до WAITING.
Готово. Якщо хочете скасувати до отримання будь-якого SMS: POST /v1/orders/:id/cancel — повне повернення коштів.

jiema.my