Hujjatlar

Umumiy ma'lumot

ownsms — o'z telefoningiz SIM'i orqali oddiy REST API bilan SMS yuborish imkonini beradi. API xabarni navbatga qo'yadi; unga ulangan Android telefon xabarni oladi va o'z SIM'idan jo'natadi.

Ikki yo'l bor:

Tayyor server: https://sms.omadli.uz — hech narsa o'rnatmasdan ro'yxatdan o'tib, telefoningizni ulaysiz (pastda).
O'z serveringiz: pip install ownsms — Django loyihangizga ulaysiz, to'liq nazorat (pastda).

Har bir so'rov Authorization: Bearer <osk_...> API kaliti bilan autentifikatsiya qilinadi. API kalitni Android ilovadan yoki register endpoint'dan olasiz.

Quickstart

API kalit oling (akkaunt + qurilma yaratadi, kalitni bir marta qaytaradi):

curl -X POST https://sms.omadli.uz/api/v1/register \ -H "Content-Type: application/json" \ -d '{"device_name":"Mening telefonim"}'

So'ng quyidagi bo'limdagi namunalar bilan SMS yuboring.

SMS yuborish — kod namunalari

Bitta SMS yuborish. osk_YOUR_KEY o'rniga o'z kalitingizni qo'ying.

curl -X POST https://sms.omadli.uz/api/v1/messages \ -H "Authorization: Bearer osk_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"to":"+998901234567","text":"Salom!"}'

<?php $ch = curl_init("https://sms.omadli.uz/api/v1/messages"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer osk_YOUR_KEY", "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "to" => "+998901234567", "text" => "Salom!", ]), ]); echo curl_exec($ch);

import requests r = requests.post( "https://sms.omadli.uz/api/v1/messages", headers={"Authorization": "Bearer osk_YOUR_KEY"}, json={"to": "+998901234567", "text": "Salom!"}, ) print(r.json())

const res = await fetch("https://sms.omadli.uz/api/v1/messages", { method: "POST", headers: { "Authorization": "Bearer osk_YOUR_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ to: "+998901234567", text: "Salom!" }), }); console.log(await res.json());

Javob: {"id":"msg_1","status":"queued","to":"+998901234567","text":"Salom!", ...}. Keyin GET /api/v1/messages/msg_1 bilan statusni tekshiring.

Parametrlar

Parametr	Turi	Ma'nosi
`to`	string	Qabul qiluvchi, E.164 (`+998901234567`). Majburiy.
`text`	string	Xabar matni. Majburiy.
`from`	string	Muayyan SIM raqami; berilmasa standart SIM.
`queued`	bool	`true` = telefon onlayn bo'lganda yubor. Standart: darrov (telefon oflayn bo'lsa 409).
`ttl`	int	Amal qilish muddati (soniya).
`send_at`	date-time	Keyinga rejalash.
`idempotency_key`	string	Takroriy so'rovni oldini olish.
`callback_url`	string	Shu xabar uchun webhook.

Status sikli

queued→ sending→ sent→ ✓✓ delivered

Status	Ma'nosi
`queued`	Qabul qilindi, telefon kutilmoqda.
`sending`	Telefonga berildi; SIM orqali yuborilmoqda.
`sent`	Operator qabul qildi — buni muvaffaqiyat deb qabul qiling.
`delivered`	Operator yetkazish hisobotini qaytardi. Bonus — ko'p tarmoqlar qaytarmaydi, kutib qolmang.
`failed` / `expired` / `canceled`	Yuborilmadi / TTL o'tdi / bekor qilindi.

Rassilka — ommaviy kampaniya

Bitta shablon va qabul qiluvchilar ro'yxatidan kampaniya yarating. Shablondagi {o'zgaruvchi} o'rinlari har bir raqam uchun alohida to'ldiriladi.

curl -X POST https://sms.omadli.uz/api/v1/campaigns \ -H "Authorization: Bearer osk_..." \ -H "Content-Type: application/json" \ -d '{ "text": "Salom {name}! Chegirma kodingiz: {code}", "recipients": [ {"to": "+998901112233", "vars": {"name": "Aziz", "code": "A50"}}, {"to": "+998907654321", "vars": {"name": "Laylo", "code": "B30"}} ] }'

Javob — 202 va kampaniya identifikatori:

{ "id": "camp_1", "status": "running", "total": 2 }

Fail-fast: agar biror raqam noto'g'ri bo'lsa, butun kampaniya 422 bilan rad etiladi va xato qatorlar bad_rowsda qaytariladi — hech biri yuborilmaydi. Raqamlarni oldindan tekshiring.

Progressni kuzatish

Kampaniya holatini so'rang; foiz = (sent + delivered + failed + expired + canceled) / total.

curl https://sms.omadli.uz/api/v1/campaigns/camp_1 \ -H "Authorization: Bearer osk_..." # messages ro'yxati: GET /api/v1/campaigns/camp_1/messages (?before=&limit=)

Pauza / davom / bekor

curl -X POST https://sms.omadli.uz/api/v1/campaigns/camp_1/pause \ -H "Authorization: Bearer osk_..." # amallar: pause · resume · cancel

To'liq retsept — CSV import, {var} shablon, idempotency — QUICKSTARTda.

Django loyihaga ulash

O'z serveringizni ko'tarish uchun ownsms paketini Django loyihangizga ulang.

Paketni o'rnating
pip install ownsms
INSTALLED_APPS'ga qo'shing (settings.py)
INSTALLED_APPS = [ ... "ownsms", ]
URL'larni ulang (urls.py)
from django.urls import include, path urlpatterns = [ path("", include("ownsms.urls")), ]
Migratsiya qiling
python manage.py migrate
Serverni ishga tushiring va API kalit oling — POST /api/v1/register (yuqorida), yoki Django admin orqali akkaunt/kalit yarating.
Telefonni ulang — Android ilovada server URL'ingizni kiriting (localhost bo'lsa ngrok/jprq) va ro'yxatdan o'ting.

Xizmat vazifalari (cron / systemd timer bilan davriy ishga tushiring): python manage.py ownsms_housekeeping (TTL/lease) va python manage.py ownsms_webhooks (webhook yetkazish).

Localhost'ni ochish (ngrok / jprq)

Telefon localhost'ga ula olmaydi — dev serveringizni internetga chiqaring, so'ng chiqqan HTTPS manzilni Android ilovada API URL sifatida kiriting.

# Django dev server 8000-portda ishlayotgan bo'lsin python manage.py runserver 0.0.0.0:8000 # boshqa terminalda ngrok http 8000 # → https://abc123.ngrok-free.app — shuni Android ilovaga kiriting

jprq http 8000 # → https://xxxx.jprq.io — shuni Android ilovaga kiriting

Eslatma: tunnel URL'ini ALLOWED_HOSTS va CSRF_TRUSTED_ORIGINS'ga qo'shing (Django), aks holda 400 qaytishi mumkin.

Python'dan to'g'ridan (HTTP so'rovsiz)

Agar backend Django loyihangizning o'zi bo'lsa — HTTP so'rov qilmasdan, xizmatni to'g'ridan-to'g'ri chaqirib SMS navbatga qo'ying:

# Django ichida — HTTP round-trip yo'q from ownsms.models import ApiKey from ownsms.services.messaging import create_message key = ApiKey.objects.filter(scopes__contains=["send"]).first() msg, _ = create_message(key, to="+998901234567", text="Salom!", queued=True) print(msg.id, msg.status)

queued=True — telefon o'sha payt onlayn bo'lmasa ham xabar navbatda turadi va telefon ulanganda yuboriladi. Xabarni ulangan telefon o'z SIM'idan jo'natadi.

sms.omadli.uz serveri

O'z serveringizni ko'tarmoqchi bo'lmasangiz — sms.omadli.uz tayyor turibdi. Ro'yxatdan o'tasiz, o'z Android telefoningizni shu serverga ulaysiz va o'z SIM'ingizdan yuborasiz. Barcha API namunalari shu server bilan ishlaydi.

Muhim: ownsms — o'z-o'zi uchun model. sms.omadli.uz umumiy server bo'lsa ham, SMS aynan sizning ulangan telefoningiz orqali ketadi — server o'zi SMS jo'natmaydi. Telefon ulanmagan bo'lsa, xabar queuedda qoladi.

Narx va cheklovlar

	sms.omadli.uz (demo)	O'z serveringiz
Narx	Bepul	Bepul (ochiq kod, MIT)
Kunlik limit	Adolatli foydalanish — ~100 SMS/kun/akkaunt	Cheklovsiz
SMS narxi	Operatoringiz tarifi (o'z SIM'ingiz) — ownsms qo'shimcha to'lov olmaydi
Haqiqiy cheklov	SIM tarifingiz + qurilmada sozlagan rate/jitter/ish-soati/kunlik kvota
Nazorat	Umumiy demo server	To'liq — o'z domeningiz, ma'lumotlaringiz

Ko'proq kerakmi? Kafolatli imkoniyat va cheksizlik uchun o'z serveringizni ko'taring — bir necha daqiqada.

Android ilovani sozlash

SMS aynan telefon orqali ketadi, shuning uchun bitta Android telefonni serverga ulash kerak. Bu bir martalik sozlash.

Ilovani yuklab o'rnating — so’nggi APKni yuklab, telefonda oching. "Noma'lum manbadan o'rnatish"ga ruxsat bering (brauzer/fayl menejeri uchun).
API URL kiriting — ilova ochilgach https://sms.omadli.uz (yoki o'z serveringiz / tunnel manzili) kiriting va URL saqlash.
Ro'yxatdan o'ting — Yangi qurilma ro'yxatdan o'tkazish tugmasini bosing. Qurilma serverga ulanadi va akkaunt + API kalit yaratiladi.
Ruxsatlarni bering — Sozlamalar → Tayyorlikda Ruxsatlarni so'rash: SMS yuborish, telefon holati, bildirishnomalar. Hammasiga ruxsat bering (SMS yuborish uchun shart).
SIM tanlang — SIM bo'limida standart SIM'ni tanlang (SMS shu raqamdan ketadi).
API kalitni oling — Sozlamalar → Akkauntda API kalit yonidagi 👁 bilan ochib, 📋 bilan nusxa oling. Shu kalitni yuqoridagi kod namunalarida osk_YOUR_KEY o'rniga qo'yasiz.
Fonda ishlashini yoqing — telefon uxlaganda ham xabarlarni qabul qilishi uchun:
- Sozlamalar → Batareya optimizatsiyasini o'chirish (ownsms uchun).
- Xiaomi/Oppo/Vivo/Huawei bo'lsa — OEM Autostart tugmasi orqali avtoishga tushishni yoqing.
Xizmatni ishga tushiring — Bosh ekranda Boshlash. Holat "Faol — xabarlar kutilmoqda" bo'lsa, telefon tayyor. Endi API orqali yuborilgan SMS'lar shu telefondan ketadi.

Test: Sozlamalar → Test SMS bo'limidan o'zingizga bitta SMS yuborib ko'ring. Status Yuborildi bo'lsa — hammasi ishlayapti.

Asosiy endpointlar

Metod	Yo'l	Tavsif
POST	`/api/v1/register`	Akkaunt + qurilma yaratish (token + kalit).
POST	`/api/v1/messages`	Bitta SMS yuborish.
GET	`/api/v1/messages` / `/{id}`	Ro'yxat / bitta xabar statusi.
POST	`/api/v1/messages/{id}/cancel`	Navbatdagi xabarni bekor qilish.
POST	`/api/v1/campaigns`	Kampaniya (rassilka).
GET	`/api/v1/device`	Qurilma holati + `today_sent`.
GET	`/api/v1/audit`	Audit jurnali.

To'liq interaktiv ma'lumotnoma — Swagger UI (/api/v1/openapi.yaml — sxema).

Tayyormisiz?

Telefoningizni ulang, kalit oling, birinchi SMS'ingizni yuboring.

Android ilovani yuklab olish Jonli API