Документация 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