Asosiy matnga o‘tish
ErgeNext Platforma API
Mundarija

ErgeNext Platforma API

Bu hujjat kompaniyaning o‘z mobil (Android, iOS, Flutter) va desktop ilovalari dasturchilari uchun. Unda ErgeNext platformasining haqiqiy HTTP API’si — veb-kabinet ishlatadigan aynan o‘sha endpointlar, jadvallar va qoidalar — yozilgan. Hammasi platforma kodi (src/app/api/**, src/lib/**) bo‘yicha tekshirilgan; bu yerda yo‘q endpoint yoki maydonni taxmin qilib ishlatmang.

Diqqat: hujjatda hech qanday maxfiy qiymat yo‘q. $SUPABASE_URL, $ANON_KEY kabi o‘rinbosarlarni platforma jamoasidan oling. service_role kalit, platformaning ichki kalitlari, bot tokenlari va kassa kalitlari hech qachon ilovaga (APK/IPA/desktop build) qo‘yilmaydi.

Umumiy tuzilma#

Platforma ikki qatlamdan iborat. Ilova ikkalasidan ham foydalanadi:

QatlamManzilAvtorizatsiyaNima uchun
Supabase Auth$SUPABASE_URL/auth/v1/*apikey: $ANON_KEYKirish (email + parol), tokenni yangilash, chiqish
Supabase PostgREST$SUPABASE_URL/rest/v1/*apikey + Authorization: Bearer <access_token>Ma’lumotlarni o‘qish va yozish (buyurtmalar, mijozlar, menyu…) — Row Level Security bilan
Supabase RPC$SUPABASE_URL/rest/v1/rpc/<funksiya>apikey + Bearerget_my_role, get_my_tenant_id, my_modules, modullarni yoqish va h.k.
Supabase Realtimewss://…/realtime/v1 (SDK orqali)sessiya tokeniYangi buyurtma, status o‘zgarishi va h.k. jonli
Next.js serverhttps://app.ergenext.uz/api/*Authorization: Bearer <access_token> (veb — sessiya cookie’si)Server mantig‘i kerak bo‘lgan amallar: buyurtma yaratish (geokod, filial), kuryerga chek, hisobotlar, to‘lov havolasi, importlar

Asosiy qoida: oddiy CRUD — to‘g‘ridan-to‘g‘ri Supabase (PostgREST + RLS). Server mantig‘i bor amallar — /api/* endpointlari. Veb-kabinet ham aynan shunday ishlaydi: masalan, mijozlar, menyu, filiallar, lidlar, qabullar va kampaniyalar brauzerdan PostgREST orqali yoziladi, buyurtma statusi va kuryer esa PATCH /api/orders/{id} orqali.

Biznes izolyatsiyasi (multi-tenant)#

  • Har bir biznes — tenants jadvalidagi bitta qator. Deyarli barcha jadvallarda tenant_id ustuni bor.
  • Foydalanuvchining biznesi profiles.tenant_id da; SQL funksiyasi get_my_tenant_id() uni joriy JWT bo‘yicha qaytaradi.
  • Row Level Security (RLS) siyosatlari har bir so‘rovni shu funksiya bilan cheklaydi: ilova boshqa biznes qatorini ko‘ra ham, o‘zgartira ham olmaydi — so‘rovda filtr yozmasangiz ham.
  • Yangi qator yozganda tenant_id ni o‘zingiz qo‘ying (rpc/get_my_tenant_id dan). Asosiy jadvallarda (branches, delivery_zones, menu_categories, menu_items, orders, customers, appointments, leads, knowledge_base, tenant_roles) ustunning standart qiymati get_my_tenant_id(), lekin keyin qo‘shilgan jadvallarda (campaigns, campaign_contacts, phone_numbers, outages, accounts, appeal_* …) veb uni aniq yuboradi — siz ham doim yuboring. Boshqa biznesning tenant_id si bilan yozish RLS xatosi (42501) beradi.
  • Filial xodimi (branch) RLS darajasida ham cheklangan: orders (va ularning order_items) dan faqat branch_id = profiles.branch_id bo‘lganlarini o‘qiydi, profiles dan faqat o‘zini, branches, tenants, tenant_modules, tenant_roles ni faqat o‘qiydi; boshqa jadvallar (mijozlar, qo‘ng‘iroqlar, sozlamalar…) unga yopiq. PostgREST orqali hech narsa yoza olmaydi — buyurtma statusi va kuryer faqat PATCH /api/orders/{id} orqali. Filial biriktirilmagan filial xodimi hech qanday buyurtmani ko‘rmaydi.
  • tenants jadvalini (balans, holat) brauzer/ilova sessiyasi o‘zgartira olmaydi — pul harakatlari faqat serverda.

Rollar#

RolKimNima qila oladi
adminBiznes egasi yoki boshqaruvchiButun kabinet: barcha bo‘limlar, sozlamalar, modullar, xodimlar, balans
branchFilial xodimi (kassir, operator)Faqat o‘z filiali buyurtmalari (/branch paneli): ko‘rish va statusni keyingi bosqichga o‘tkazish
superadminPlatforma egasiBarcha bizneslar. Mijoz ilovalari uchun emas

Rol rpc/get_my_role bilan olinadi (zaxira: profiles.role, so‘ngra app_metadata.role). Admin uchun qo‘shimcha cheklov: maxsus rol (tenant_roles.modules) yoki profiles.allowed_modules berilgan bo‘lsa, kabinet menyusida faqat shu modullar ko‘rinadi. Ilovangizda ham shunday qiling: ko‘rinadigan bo‘limlar = my_modules ∩ rol modullari (rol modullari bo‘sh bo‘lsa — hammasi).

Tez boshlash#

  1. Platforma jamoasidan SUPABASE_URL va ANON_KEY ni oling (bu ochiq qiymatlar — veb-kabinet ham brauzerda ishlatadi).
  2. Foydalanuvchini email va parol bilan kiriting — access_token va refresh_token olasiz.
  3. get_my_role, get_my_tenant_id, my_modules ni chaqirib, qaysi ekranlarni ko‘rsatishni hal qiling.
  4. Ma’lumotlarni PostgREST orqali o‘qing; server amallari uchun /api/* ga Authorization: Bearer <access_token> bilan murojaat qiling.
  5. Jonli yangilanishlar uchun Realtime kanaliga obuna bo‘ling.
# Get these from the platform team (both are public values - the web dashboard ships them to the browser too):
export SUPABASE_URL="https://<project-ref>.supabase.co"   # NEXT_PUBLIC_SUPABASE_URL
export ANON_KEY="<anon public key>"                       # NEXT_PUBLIC_SUPABASE_ANON_KEY
export SITE="https://app.ergenext.uz"                     # Next.js server (/api/*)
# NEVER put the service_role key into an app.

Autentifikatsiya#

Platformada faqat email + parol (Supabase Auth) ishlatiladi. Hisoblarni biznes admini kabinetda yaratadi (Foydalanuvchilar bo‘limi) yoki biznes o‘zi ro‘yxatdan o‘tadi. Telefon/SMS orqali kirish yo‘q.

Kirish: email va parol#

POST $SUPABASE_URL/auth/v1/token?grant_type=password — sarlavhalar: apikey: $ANON_KEY, Content-Type: application/json. Tana: {"email": "...", "password": "..."}.

curl -s -X POST "$SUPABASE_URL/auth/v1/token?grant_type=password" \
  -H "apikey: $ANON_KEY" -H "Content-Type: application/json" \
  -d '{"email":"operator@example.uz","password":"********"}'

Javob (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "expires_at": 1791100000,
  "refresh_token": "v1-r3fr3sh...",
  "user": {
    "id": "6f1c2b9e-0000-4000-8000-000000000001",
    "email": "operator@example.uz",
    "app_metadata": { "provider": "email", "role": "admin" },
    "user_metadata": { "full_name": "Dilnoza Karimova" }
  }
}

Xato login — 400 va «Invalid login credentials» xabari (SDK’larda AuthApiError; aniq JSON maydonlari Supabase Auth versiyasiga bog‘liq). Email serverda kichik harfga o‘tkaziladi — ilovada ham trim().toLowerCase() qiling.

Tokenni yangilash va chiqish#

access_token taxminan 1 soat yashaydi (expires_at — Unix soniya). SDK’lar uni o‘zi yangilaydi; qo‘lda ishlasangiz grant_type=refresh_token dan foydalaning. Chiqishda POST /auth/v1/logout.

# access_token lives ~1 hour - refresh it before it expires (the SDKs do this automatically)
curl -s -X POST "$SUPABASE_URL/auth/v1/token?grant_type=refresh_token" \
  -H "apikey: $ANON_KEY" -H "Content-Type: application/json" \
  -d '{"refresh_token":"v1-r3fr3sh..."}'

# Sign out (revokes the refresh token)
curl -s -X POST "$SUPABASE_URL/auth/v1/logout" \
  -H "apikey: $ANON_KEY" -H "Authorization: Bearer $ACCESS_TOKEN"
Maslahat: tokenlarni xavfsiz joyda saqlang: Android — EncryptedSharedPreferences / DataStore + Keystore, iOS — Keychain, Flutter — flutter_secure_storage, desktop — OS keychain (Electron safeStorage).

Joriy foydalanuvchi, rol, biznes va modullar#

Kirgandan keyin darhol uchta RPC chaqiring va natijani keshlang:

RPCJavobIzoh
get_my_role"admin", "branch" yoki "superadmin"Rol yo‘q bo‘lsa — null (veb /login?error=norole ga qaytaradi)
get_my_tenant_idbiznes uuidYangi qatorlarda tenant_id sifatida ishlating
my_modulesfaol modul kalitlari massiviTo‘lov muddati o‘tgan modul kirmaydi (3 kunlik imtiyozdan keyin)
H=(-H "apikey: $ANON_KEY" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json")
curl -s -X POST "$SUPABASE_URL/rest/v1/rpc/get_my_role"      "${H[@]}" -d '{}'   # "admin"
curl -s -X POST "$SUPABASE_URL/rest/v1/rpc/get_my_tenant_id" "${H[@]}" -d '{}'   # "3b0d…-uuid"
curl -s -X POST "$SUPABASE_URL/rest/v1/rpc/my_modules"       "${H[@]}" -d '{}'   # ["ai_agent","orders",…]
curl -s "$SUPABASE_URL/rest/v1/profiles?select=id,full_name,role,branch_id,custom_role_id,allowed_modules,tenant_roles(name,modules)" "${H[@]}"

profiles jadvali: id (auth foydalanuvchi id’si), tenant_id, full_name, email, role, custom_role_id, allowed_modules, branch_id (filial xodimi uchun majburiy), created_at, updated_at; bog‘lanish tenant_roles(*).

Veb POST /api/auth/login ({email, password}) ni chaqiradi. Server Supabase’ga kiradi, sessiyani httpOnly bo‘lmagan cookie sifatida o‘rnatadi (path=/, SameSite=Lax, prod’da Secure) va {"ok": true, "role": "admin", "dest": "/admin"} qaytaradi. Keyingi barcha /api/* so‘rovlari sessiyani shu cookie’dan o‘qiydi (@supabase/ssr).

Sessiyasiz /api/* so‘roviga server 401 {"error": "Unauthorized"} qaytaradi (sahifalar esa /login ga redirect qiladi).

Ilovadan /api/* ni chaqirish#

Ilova /api/* ga Supabase’dan olingan access_token ni Authorization: Bearer <access_token> sarlavhasida yuboradi — PostgREST bilan bir xil token. Cookie kerak emas.

# /api/* takes the same access_token as PostgREST
curl -s -X PATCH "$SITE/api/orders/$ORDER_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"accepted","courier_id":"d4c3…"}'
# 401 {"error":"Unauthorized"} - token missing, invalid or (almost) expired: refresh it and retry once
  • Token GoTrue’da tekshiriladi; soxta, chaqirib olingan yoki muddati o‘tgan token — 401.
  • Server bu yo‘lda tokenni yangilamaydi: muddati tugashiga 100 soniyadan kam qolgan token ham 401 oladi. Tokenni oldindan grant_type=refresh_token bilan yangilang (SDK’lar buni o‘zi qiladi) va 401 da bir marta yangilab qayta urining.
  • Bearer so‘roviga javobda Set-Cookie bo‘lmaydi.

POST/api/auth/register#

Yangi biznes ochish (ochiq). Biznes, uning admini va AI asosiy modullari yaratiladi; boshlang‘ich balans 50 000 so‘m. Soha so‘ralmaydi — modullar kabinetdagi sozlash oynasida tanlanadi.

MaydonTurQoida
company_namestringkamida 2 belgi
emailstringto‘g‘ri email
passwordstringkamida 8 belgi
curl -s -X POST "$SITE/api/auth/register" -H "Content-Type: application/json" \
  -d '{"company_name":"Shirin Somsa","email":"owner@example.uz","password":"kamida8belgi"}'
# 200 {"ok":true,"tenant_id":"…"}   400 {"error":"Parol kamida 8 ta belgi bo'lishi kerak"}   429 (5 attempts / 10 min / IP)

Cheklov: bitta IP’dan 10 daqiqada 5 ta urinish (429). Ro‘yxatdan o‘tgach auth/v1/token bilan kiring.

POST/api/auth/login#

Faqat veb uchun (cookie o‘rnatadi). Ilovada to‘g‘ridan-to‘g‘ri auth/v1/token dan foydalaning. Xatolar: 400 {"error":"Email va parolni kiriting"}, 400 {"error":"Invalid login credentials"}, 500.

Xatolar, validatsiya va limitlar#

Javob formatlari#

  • /api/* xatosi: {"error": "<matn yoki kod>"} va HTTP status. Matnlar ko‘pincha o‘zbekcha (kabinetda ko‘rsatiladi); ba’zi endpointlar qisqa kod qaytaradi ("forbidden", "rate", "module", "bad").
  • PostgREST xatosi: {"code","message","details","hint"}.
  • RPC biznes xatolari message ichida kod sifatida keladi (modullar bo‘limiga qarang).
// RLS: writing a row of another business, or no permission
{ "code": "42501", "message": "new row violates row-level security policy for table \"customers\"", "details": null, "hint": null }

// Duplicate value (e.g. a phone number that is already connected)
{ "code": "23505", "message": "duplicate key value violates unique constraint \"…\"", "details": "Key (…)=(…) already exists.", "hint": null }

// .single() found no row
{ "code": "PGRST116", "message": "JSON object requested, multiple (or no) rows returned", "details": "The result contains 0 rows", "hint": null }

HTTP statuslar#

StatusMa’nosi
200Muvaffaqiyat (/api/* yaratishda ham 200)
206Qisman kontent (qo‘ng‘iroq yozuvi, Range)
400Validatsiya xatosi, noto‘g‘ri holat o‘tishi, «O‘zgarish yo‘q»
401Foydalanuvchi aniqlanmadi (Unauthorized)
403Rol yetmaydi (Forbidden, Faqat admin) yoki modul yoqilmagan (Modul yoqilmagan)
404Topilmadi (yoki boshqa biznesga tegishli — RLS uni ko‘rsatmaydi)
410Eskirgan amal (subscribe_plan — tariflar o‘rniga endi modullar)
429So‘rovlar limiti
500 / 502 / 503Server, AI dvigatel yoki tashqi xizmat xatosi

Telefon raqamlar#

Platforma O‘zbekiston raqamlarini +998XXXXXXXXX ko‘rinishida saqlaydi. Server qabul qiladigan kirishlar: 998XXXXXXXXX (12 raqam), XXXXXXXXX (9 raqam) yoki 0XXXXXXXXX (10 raqam); bo‘sh joy, chiziqcha, qavslar e’tiborsiz qoldiriladi. Boshqa formatlar rad etiladi (Telefon noto‘g‘ri). PostgREST’ga to‘g‘ridan-to‘g‘ri yozganda raqamni o‘zingiz shu ko‘rinishga keltiring — aks holda AI mijozni raqami bo‘yicha taniy olmaydi.

Vaqt va pul#

  • Barcha vaqtlar ISO 8601, UTC (2026-10-04T09:05:13.000Z). Kabinet Toshkent vaqtida ko‘rsatadi (UTC+5, yozgi vaqt yo‘q). Hisobotlardagi from/to — Toshkent kunlari.
  • Summalar so‘mda (butun son yoki o‘nlik). Istisno: Payme/Click tranzaksiyalari (order_payments.amount) — tiyinda.

So‘rovlar limiti#

Limitlar server xotirasida hisoblanadi (server qayta ishga tushganda nolga tushadi), oshib ketsa 429:

EndpointLimit
POST /api/auth/register5 / 10 daq, IP bo‘yicha
POST /api/admin/import20 / 10 daq, foydalanuvchi bo‘yicha
POST /api/admin/import/ai10 / 10 daq, foydalanuvchi bo‘yicha
POST /api/admin/setup/draft6 / 10 daq, foydalanuvchi bo‘yicha
POST /api/voice/preview30 / daq, foydalanuvchi bo‘yicha
POST /api/chat/{tenant}30 xabar / 10 daq sessiyaga va 80 / 10 daq IP ga
GET /api/org/{token}120 / daq, IP
PATCH /api/org/{token}60 / daq, IP

Modullar#

Biznes imkoniyatlari modullar bilan yoqiladi. Ilova faqat faol modul bo‘limlarini ko‘rsatishi kerak: server ham tekshiradi va modul yo‘q bo‘lsa 403 ("Modul yoqilmagan", "module") qaytaradi.

GuruhModul kalitlari
Asosiy (doim bepul)settings, users, billing, customers, branches
AI va telefoniyaai_agent, phone_numbers, call_recordings, operator_transfer, campaigns, director_mode, ai_chat, web_widget, branch_routing
Avtomatlashtirishreminder_calls, callback_calls, feedback_calls, owner_alerts, sms_notify, call_rules
Tillarmultilang (rus), lang_tg, lang_ky, lang_kaa (o‘zbek doim bor)
Savdomenu, orders, delivery_zones, payment_links
Mijozlar bilan ishlashappointments, leads, knowledge_base, knowledge_docs, telegram_bot, crm_integrations
Tahlilanalytics, call_analytics
Davlat va kommunalappeals, appeal_routing, appeal_sla, appeal_feedback, outages, accounts

Jadvallar: platform_modules (katalog: key, name_uz/ru/en, description_uz/ru/en, price_monthly, is_core, depends_on, icon, sort_order, is_active) va tenant_modules (tenant_id, module_key, status = active / past_due / expired / cancelled, auto_renew, price_monthly, activated_at, paid_until). Modul faol: status active yoki past_due va paid_until (+ past_due uchun 3 kun) hali o‘tmagan. Asosiy (is_core) modullar doim faol.

RPCactivate_module / cancel_module / deactivate_module#

Faqat biznes admini. activate_module birinchi oy narxini balansdan yechadi va 30 kunga yoqadi; cancel_module avto-yangilashni o‘chiradi (muddat oxirigacha ishlaydi; qayta chaqirish — davom ettirish); deactivate_module darhol o‘chiradi, bog‘liq modullarni ham o‘chiradi va ishlatilmagan kunlar pulini qaytaradi. p_dry_run: true — hech narsani o‘zgartirmasdan nima bo‘lishini ko‘rsatadi.

H=(-H "apikey: $ANON_KEY" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json")
# Catalog and the business's modules
curl -s "$SUPABASE_URL/rest/v1/platform_modules?select=*&is_active=eq.true&order=sort_order" "${H[@]}"
curl -s "$SUPABASE_URL/rest/v1/tenant_modules?select=*&tenant_id=eq.$TENANT_ID" "${H[@]}"

# Activate (first month is charged from the balance), toggle auto-renew, deactivate immediately
curl -s -X POST "$SUPABASE_URL/rest/v1/rpc/activate_module"   "${H[@]}" -d '{"p_key":"orders"}'
curl -s -X POST "$SUPABASE_URL/rest/v1/rpc/cancel_module"     "${H[@]}" -d '{"p_key":"orders"}'
curl -s -X POST "$SUPABASE_URL/rest/v1/rpc/deactivate_module" "${H[@]}" -d '{"p_key":"orders","p_dry_run":true}'
curl -s -X POST "$SUPABASE_URL/rest/v1/rpc/deactivate_module" "${H[@]}" -d '{"p_key":"orders"}'
Diqqat: modul yoqilgach kabinet menyusi o‘zgaradi — ilovada my_modules ni qayta o‘qing.

Buyurtmalar#

Modul: orders. Jadvallar: orders va order_items. Yangi buyurtmalar AI operatordan (source: "voice_ai"), kabinetdan ("admin"), Telegram botdan ("telegram") va boshqa manbalardan keladi.

Buyurtma maydonlari#

MaydonTurIzoh
iduuid
order_numberintBiznes ichidagi tartib raqami (mijozga aytiladi)
statusstringnew, accepted, delivering, done (+ eski: preparing, ready, cancelled)
customer_iduuid, nullcustomers ga bog‘lanish
customer_name, customer_phonestringBuyurtma paytidagi qiymatlar
delivery_addressstringGeokod qilingan bo‘lsa — formatlangan manzil
delivery_lat, delivery_lngnumber, null
branch_iduuid, nullZona/eng yaqin filial bo‘yicha avtomatik yoki qo‘lda
notesstring, null
subtotal, delivery_fee, totalnumberso‘m
sourcestringvoice_ai, admin, telegram, …
transcriptstring, nullAI suhbat matni (AI buyurtmasida)
courier_iduuid, nullYangi Biriktirilgan kuryer
accepted_at, delivering_at, delivered_attimestamp, nullYangi Status o‘zgargan vaqtlar
courier_notified_attimestamp, nullYangi Kuryerga chek oxirgi marta yuborilgan vaqt
deliver_ondate, nullYangi Yetkazish kuni (AI agent ertangi kunga shakllantirgan buyurtmalar)
payment_statusstringunpaid, pending, paid, refunded (to‘lov havolasi moduli)
pay_provider, paid_atstring, timestamppayme / click
created_at, updated_attimestamp

order_items: id, order_id, menu_item_id (null bo‘lishi mumkin), name, quantity, unit_price, line_total, created_at.

{
  "id": "a3f0c1d2-1111-4a4a-9b9b-000000000042",
  "tenant_id": "3b0d7e55-2222-4c4c-8d8d-000000000007",
  "order_number": 1042,
  "status": "accepted",
  "customer_id": "c9e1…",
  "customer_name": "Abduqodir aka",
  "customer_phone": "+998901234567",
  "delivery_address": "Chilonzor 9-kvartal, 12-uy",
  "delivery_lat": 41.2856,
  "delivery_lng": 69.2034,
  "notes": "Domofon ishlamaydi",
  "subtotal": 76000,
  "delivery_fee": 15000,
  "total": 91000,
  "source": "voice_ai",
  "branch_id": "b7a2…",
  "courier_id": "d4c3…",
  "accepted_at": "2026-10-04T09:12:40.000Z",
  "delivering_at": null,
  "delivered_at": null,
  "courier_notified_at": "2026-10-04T09:12:41.000Z",
  "deliver_on": null,
  "payment_status": "unpaid",
  "created_at": "2026-10-04T09:05:13.000Z",
  "updated_at": "2026-10-04T09:12:40.000Z",
  "branches": { "id": "b7a2…", "name": "Chilonzor filiali" },
  "order_items": [
    { "id": "…", "order_id": "a3f0…", "menu_item_id": "m1…", "name": "Lavash klassik", "quantity": 2, "unit_price": 28000, "line_total": 56000 },
    { "id": "…", "order_id": "a3f0…", "menu_item_id": "m2…", "name": "Coca-Cola 1 l", "quantity": 2, "unit_price": 10000, "line_total": 20000 }
  ]
}

Statuslar va o‘tishlar#

Operator tanlaydigan statuslar: Yangi (new) → Qabul qilindi (accepted) → Yetkazilmoqda (delivering) → Yetkazildi (done). preparing, ready, cancelled faqat eski buyurtmalarda uchraydi (ko‘rsating, lekin yangidan tanlatmang).

KimQoida
adminIstalgan joriy statusdan new, accepted, delivering, done ga
branchFaqat keyingi bosqichga: new→accepted, accepted/preparing/ready→delivering, delivering→done; faqat o‘z filiali buyurtmasi

Statusga o‘tganda vaqt belgisi yoziladi: accepted_at, delivering_at, delivered_at.

Buyurtmalarni o‘qish (PostgREST)#

Ro‘yxat uchun PostgREST’dan foydalaning (veb ham shunday — oxirgi 150 ta). Filial xodimiga RLS faqat o‘z filiali buyurtmalarini qaytaradi; branch_id=eq.<profiles.branch_id> filtri shart emas, lekin indeks uchun foydali.

curl -s "$SUPABASE_URL/rest/v1/orders?select=*,branches(id,name),order_items(*)&order=created_at.desc&limit=50" \
  -H "apikey: $ANON_KEY" -H "Authorization: Bearer $ACCESS_TOKEN"

# Active orders only, restricted to the branch of a branch user:
curl -s "$SUPABASE_URL/rest/v1/orders?select=id,order_number,status,total,customer_name,created_at&status=in.(new,accepted,delivering)&branch_id=eq.$BRANCH_ID&order=created_at.desc" \
  -H "apikey: $ANON_KEY" -H "Authorization: Bearer $ACCESS_TOKEN"

POST/api/orders#

Kabinetdan qo‘lda buyurtma yaratish. Faqat admin. Server: telefonni normallashtiradi, manzilni geokod qiladi, branch_id berilmasa — nuqta tushgan yetkazish zonasi yoki eng yaqin filialni tanlaydi, narxlarni menyudan oladi, app_settings.default_delivery_fee ni qo‘shadi, mijozni telefon bo‘yicha topadi yoki yaratadi (ism/manzilni yangilaydi) va source: "admin", status: "new" bilan yozadi.

MaydonTurQoida
phonestringmajburiy, kamida 9 belgi, UZ raqami
customer_namestringixtiyoriy
delivery_addressstringmajburiy, kamida 3 belgi
notesstringixtiyoriy
branch_iduuid, nullixtiyoriy; shu biznes filiali bo‘lishi shart
itemsmassiv1–40 ta
items[].menu_item_iduuidixtiyoriy — bo‘lsa nom va narx menyudan
items[].namestringmenu_item_id bo‘lmasa — menyudan nom bo‘yicha qidiriladi
items[].quantityint1–50
items[].unit_pricenumbermenyuda topilmagan mahsulot uchun narx
POST /api/orders
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "phone": "90 123 45 67",
  "customer_name": "Abduqodir aka",
  "delivery_address": "Chilonzor 9-kvartal, 12-uy",
  "notes": "Domofon ishlamaydi",
  "branch_id": null,
  "items": [
    { "menu_item_id": "m1…", "quantity": 2 },
    { "name": "Coca-Cola", "quantity": 2 },
    { "name": "Maxsus salat", "quantity": 1, "unit_price": 18000 }
  ]
}

GET/api/orders/{id}#

admin yoki branch (filial xodimi — faqat o‘z filiali). Javob: {"order": {...}} — branches(id, name), order_items(*), customers(*) bilan (filial xodimiga customers — null; mijoz ma’lumoti buyurtmaning customer_name, customer_phone, delivery_address maydonlarida). 404 {"error":"Topilmadi"}.

PATCH/api/orders/{id}#

Status, kuryer, izoh va filialni o‘zgartirish; kuryerga Telegram chekini yuborish.

MaydonTurKimIzoh
statusnew, accepted, delivering, doneadmin, branchO‘tish qoidalari yuqorida
courier_iduuid, nulladmin, branchShu biznesning faol kuryeri
resend_receiptbooleanadmin, branchChekni kuryerga qayta yuborish
notesstring (≤2000), nullfaqat admin
branch_iduuid, nullfaqat admin

Qoidalar:

  • accepted ga o‘tkazishda biznesda kamida bitta faol kuryer bo‘lsa, kuryer majburiy (courier_id shu so‘rovda yoki avval berilgan bo‘lishi kerak) — aks holda 400 "Kuryerni tanlang".
  • Kuryerga chek quyidagi hollarda avtomatik ketadi: buyurtma accepted bo‘lganda; faol buyurtmada (accepted/preparing/ready/delivering) kuryer almashtirilganda; resend_receipt: true bo‘lganda.
  • Chek yuborilmasa ham o‘zgarishlar saqlanadi; sabab courier.error da: Kuryer tanlanmagan, Kuryer faol emas, Kuryer Telegram botga ulanmagan, Telegram bot ulanmagan (Telegram bo‘limi), Buyurtma faol emas, Telegram: ….
PATCH /api/orders/a3f0c1d2-1111-4a4a-9b9b-000000000042
Content-Type: application/json
Authorization: Bearer <access_token>

{ "status": "accepted", "courier_id": "d4c3…" }

// other variants:
{ "status": "delivering" }
{ "status": "done" }
{ "courier_id": "e5f6…" }            // change courier (on an accepted order the receipt goes to the new courier)
{ "resend_receipt": true }           // resend the receipt to the courier
{ "notes": "Eshik oldida kutadi", "branch_id": "b7a2…" }   // admin only

DELETE/api/orders/{id}#

Faqat admin. 200 {"ok": true}; filial xodimi — 403 "Faqat admin o‘chira oladi".

Chek / invoys sahifasi#

GET /orders/{id}/receipt — chop etish uchun HTML sahifa (buyurtma, mahsulotlar, filial, kuryer, biznes rekvizitlari). Sessiya kerak; filial xodimi faqat o‘z filiali chekini ochadi. Ilovada uni WebView’da Authorization: Bearer <access_token> sarlavhasi bilan oching (masalan, Android loadUrl(url, headers)) yoki PDF/chop etish uchun ishlating.

Jonli yangilanish#

orders jadvali Realtime’da: INSERT (yangi buyurtma — kabinet ovozli signal chaladi), UPDATE (status, kuryer, to‘lov), DELETE. Kodni Realtime bo‘limida ko‘ring.

Kuryerlar Yangi#

Modul: orders + biznesning Telegram boti (token, username va webhook ulangan). Kuryer kabinetda qo‘shiladi va bir martalik havola orqali botga ulanadi; operator buyurtmani qabul qilganda kuryerga chek boradi, kuryer botda «🛵 Yo‘lga chiqdim» / «✅ Yetkazildi» ni bosadi va buyurtma statusi kabinetda jonli o‘zgaradi.

couriers jadvali: id, tenant_id, name, phone, telegram_chat_id, telegram_name, link_code, is_active, created_at. Barcha endpointlar — faqat admin, orders moduli kerak (aks holda 403 "Buyurtmalar moduli yoqilmagan").

GET/api/admin/couriers#

Ro‘yxat va bot holati. link — kuryerga yuboriladigan havola https://t.me/<bot_username>?start=c_<link_code> (bot username kiritilmagan bo‘lsa null; u holda kuryer botga /start c_<link_code> yozadi).

C=(-H "Content-Type: application/json" -H "Authorization: Bearer $ACCESS_TOKEN")
curl -s "$SITE/api/admin/couriers" "${C[@]}"
curl -s -X POST  "$SITE/api/admin/couriers" "${C[@]}" -d '{"name":"Jasur","phone":"+998 90 123 45 67"}'
curl -s -X PATCH "$SITE/api/admin/couriers" "${C[@]}" -d '{"id":"d4c3…","new_link":true}'
curl -s -X PATCH "$SITE/api/admin/couriers" "${C[@]}" -d '{"id":"d4c3…","unlink":true,"new_link":true}'
curl -s -X PATCH "$SITE/api/admin/couriers" "${C[@]}" -d '{"id":"d4c3…","is_active":false}'
curl -s -X DELETE "$SITE/api/admin/couriers?id=d4c3…" "${C[@]}"

POST/api/admin/couriers#

{"name": "Jasur", "phone": "+998 90 123 45 67"} — name 1–120 belgi, phone ixtiyoriy (UZ raqami). Bir biznesda ko‘pi bilan 200 kuryer. Javob: {"courier": {...}}. Xatolar: 400 "Ism kerak (120 belgigacha)", 400 "Telefon raqami noto‘g‘ri", 400 "Kuryerlar soni chegarasi: 200".

PATCH/api/admin/couriers#

MaydonIzoh
idmajburiy, uuid
name, phonetahrirlash
is_activefaolsizlantirilgan kuryer buyurtmaga tanlanmaydi
new_linkyangi bir martalik kod (eski havola ishlamay qoladi)
unlinkTelegram’dan uzish (telegram_chat_id tozalanadi) — odatda new_link bilan birga

Javob: {"courier": {...}}; 404 "Topilmadi", 400 "O‘zgarish yo‘q".

DELETE/api/admin/couriers?id={id}#

Kuryerni o‘chiradi; unga biriktirilgan buyurtmalarda kuryer bo‘sh qoladi. 200 {"ok": true}.

Kuryer bot oqimi#

Bu qism Telegram webhook ichida ishlaydi (ilova chaqirmaydi), lekin ma’lumotlar o‘zgarishini tushunish uchun:

  1. Kuryer havolani ochadi va Start ni bosadi — couriers.telegram_chat_id yoziladi, kod ishlatilgach o‘chadi.
  2. Operator buyurtmani accepted qiladi — kuryerga chek: mijoz, telefon, manzil va xarita havolasi, mahsulotlar, jami, to‘lov holati.
  3. Kuryer «📦 Bugungi zakazlar» ni bosadi — yo‘ldagilar, keyin kutayotganlar, keyin bugun yetkazilganlar va yig‘iladigan summa.
  4. «🛵 Yo‘lga chiqdim» → status = delivering, «✅ Yetkazildi» → status = done. O‘zgarish orders Realtime orqali kabinetga darhol keladi.

Mijozlar#

Modul: customers (asosiy). Jadval customers: id, tenant_id, phone (+998…), name, address, lat, lng, notes, call_count, last_called_at, created_at, updated_at.

  • Telefon — biznes ichida mijozning kaliti: import, AI va buyurtma yaratish mijozni telefon bo‘yicha topadi.
  • Doimiy mijoz Yangi: qo‘ng‘iroq qilgan raqam customers da bo‘lsa, AI mijozni kartadagi ism bilan kutib oladi va buyurtmada manzil so‘ramaydi — buyurtma address ga yoziladi (mijoz boshqa manzil aytmasa). Shuning uchun name va address ni toza saqlang (masalan, «Abduqodir aka 40/50 (415-Jar)» dan AI «Abduqodir aka» deb aytadi).
  • O‘qish, yaratish, tahrirlash, o‘chirish — PostgREST.
H=(-H "apikey: $ANON_KEY" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json")

# Create (Prefer returns the created row):
curl -s -X POST "$SUPABASE_URL/rest/v1/customers" "${H[@]}" -H "Prefer: return=representation" \
  -d '{"tenant_id":"'$TENANT_ID'","phone":"+998901234567","name":"Abduqodir aka","address":"Chilonzor 9-kvartal, 12-uy"}'

# Update:
curl -s -X PATCH "$SUPABASE_URL/rest/v1/customers?id=eq.$CUSTOMER_ID" "${H[@]}" -H "Prefer: return=representation" \
  -d '{"address":"Yunusobod 4-mavze, 7-uy","notes":"Domofon 12"}'

# Delete:
curl -s -X DELETE "$SUPABASE_URL/rest/v1/customers?id=eq.$CUSTOMER_ID" "${H[@]}"

# Search + pagination (total count comes in the Content-Range header):
curl -s "$SUPABASE_URL/rest/v1/customers?select=*&or=(name.ilike.*aziz*,phone.ilike.*90123*)&order=updated_at.desc" \
  "${H[@]}" -H "Range-Unit: items" -H "Range: 0-49" -H "Prefer: count=exact"

Menyu#

Modul: menu. Jadvallar:

  • menu_categories: id, tenant_id, name_uz, name_ru, sort_order, is_active, created_at.
  • menu_items: id, tenant_id, category_id, name_uz, name_ru, description_uz, description_ru, price, unit, is_available (vaqtincha yo‘q), archived_at (to‘ldirilgan — arxivda: mijozga ko‘rsatilmaydi, buyurtmaga qo‘shib bo‘lmaydi), archived_by, sort_order, created_at, updated_at.

AI operator va Telegram bot faqat is_available = true mahsulotlarni taklif qiladi. Ko‘p mahsulotni bir martada yuklash uchun Ommaviy import dan foydalaning.

Filiallar#

Modul: branches (asosiy). Jadval branches: id, tenant_id, name, address, phone, lat, lng, is_active, created_at, updated_at.

  • Buyurtma filialga zona yoki eng yaqin masofa bo‘yicha biriktiriladi.
  • branch_routing + operator_transfer modullari yoqilgan bo‘lsa, telefoni kiritilgan faol filiallar AI uchun «ulash yo‘nalishi» bo‘ladi: mijoz aytgan filialga qo‘ng‘iroq ulanadi.
  • Filial xodimi (branch roli) profiles.branch_id orqali bog‘lanadi.

Yetkazish zonalari va mahalliy nomlar#

Modul: delivery_zones.

  • delivery_zones: id, tenant_id, name, branch_id (null — avtomatik eng yaqin filial), polygon, is_active, created_at, updated_at. polygon — GeoJSON uslubidagi yopiq halqa: [[[lng, lat], [lng, lat], …, [birinchi nuqta]]] (kamida 3 ta nuqta; diqqat — avval lng).
  • address_aliases: id, tenant_id, alias (kichik harfda), canonical_address, city, lat, lng, notes, is_active. Mijoz «shestnadsat» desa, tizim rasmiy manzil bilan geokod qiladi; lat/lng berilsa — aniq nuqta.

Qabullar va bronlar#

Modul: appointments. Jadval appointments: id, tenant_id, customer_id, branch_id, customer_name, customer_phone, service_name, specialist_name, appointment_date (YYYY-MM-DD), appointment_time (HH:MM), duration_minutes, price, status, notes, source, transcript, created_at, updated_at.

  • Statuslar: new → confirmed → completed, yoki cancelled.
  • Kabinet qo‘lda yozuvni status: "confirmed", source: "manual" bilan yaratadi; AI — source: "voice_ai".
  • Eslatma qo‘ng‘iroqlari (reminder_calls) natijasi qabul kartasida ko‘rinadi (tasdiqladi, ko‘chirdi, bekor qildi, javob bermadi).
  • Realtime: appointments.

Lidlar#

Modul: leads. Jadval leads: id, tenant_id, customer_id, customer_name, customer_phone, interest_topic, budget, status, notes, source, transcript, created_at, updated_at.

  • Statuslar: new, contacted, converted, rejected.
  • Qo‘lda: source: "manual"; importdan: "import"; AI: "voice_ai".
  • Realtime: leads.

Murojaatlar (davlat va kommunal)#

Modul: appeals (+ appeal_routing, appeal_sla, appeal_feedback). Jadvallar:

  • appeals: id, tenant_id, appeal_number, type_id, type_name, org_id, citizen_name, citizen_phone, address, district, details, fields (jsonb), priority (normal/urgent), status (new, in_progress, resolved, rejected), due_at, resolved_at, resolution, source, call_id, created_at.
  • appeal_types: name, description (AI uchun), fields (qo‘shimcha so‘raladigan maydonlar, ≤12), org_id, sla_hours (1–2160), is_active, sort_order.
  • appeal_orgs: name, description, phone, telegram_chat_id, access_token (tashkilot portali), is_active.
  • appeal_events: appeal_id, kind (created, status, comment, routed, reminded, escalated, notified, survey), text, actor, created_at.

Realtime: appeals. RPC: appeals_summary, appeals_report (kabinet statistikasi).

GET/ PUT /api/admin/appeals#

Faqat admin, appeals moduli. GET — sozlamalar (sms_on_create, sms_on_close, andozalar, survey_on_resolve, escalate_after_hours, cluster_threshold, cluster_minutes), Telegram ulanganmi va bog‘liq modullar holati. PUT {"settings": {...}} — saqlash (qiymatlar serverda chegaralanadi).

POST/api/admin/appeals#

Qo‘lda ariza (operator telefon yoki qabulda yozadi) — AI bilan bir xil yo‘l: raqam beriladi, tur bo‘yicha tashkilot va muddat qo‘yiladi, xabarlar yuboriladi.

{"type": "Ko‘cha chirog‘i", "citizen_name": "…", "citizen_phone": "+998…", "address": "…", "district": "…", "details": "…", "fields": {"mahalla": "…"}, "urgent": false} → {"ok": true, "appeal_number": 1287, ...}. Telefon kamida 9 raqam.

PATCH/api/admin/appeals#

{"id": "…", "status": "resolved", "resolution": "Chiroq almashtirildi", "org_id": "…"} — holat, fuqaroga javob, tashkilot (appeal_routing bo‘lsa). Javob {"ok": true, "appeal": {...}}.

Tashkilot portali: GET / PATCH /api/org/{token}#

Parolsiz, 64 belgili access_token bo‘yicha (kabinetdagi «Kabinet havolasi»). GET — tashkilot nomi va unga yo‘naltirilgan arizalar. PATCH {"id", "status", "resolution"} — status faqat in_progress, resolved, rejected; resolved/rejected uchun javob matni kamida 3 belgi. Havola yangilansa eskisi darhol ishlamaydi.

O‘chirishlar va abonentlar#

  • outages (modul outages): id, tenant_id, kind (planned/emergency), area, message (AI aytadigan matn), starts_at, ends_at, is_active, source (auto — murojaatlar to‘planishidan yaratilgan qoralama), created_at, updated_at. Faol e’lonni AI shu hududdan qo‘ng‘iroq qilganlarga aytadi; ends_at o‘tgach o‘zi to‘xtaydi.
  • accounts (modul accounts): account_number (biznes ichida yagona — upsert onConflict: tenant_id,account_number), holder_name, address, phone, balance (qarz — manfiy), status, updated_at. RPC accounts_stats → {total, debtors, debt}.
  • meter_readings: account_number, value, phone, source, created_at — AI qabul qilgan hisoblagich ko‘rsatkichlari.

Qo‘ng‘iroqlar#

Modul: ai_agent. Jadval call_logs (faqat o‘qish uchun — yozuvlarni ovoz dvigateli qo‘shadi):

MaydonIzoh
id, tenant_id, created_at
caller_phone, didMijoz raqami va biznes raqami
directioninbound / outbound
duration_seconds, billed_minutes, costDaqiqa yuqoriga yaxlitlanadi; no_speech va sinov hisoblanmaydi
statuscompleted, no_speech, transferred, busy, failed, test, director
languageSuhbat tili
transcriptSuhbat matni
recording_urlYozuv mavjudligi belgisi
campaign_id, order_idKampaniya / buyurtma bilan bog‘lanish
analysisSuhbat tahlili (call_analytics): kayfiyat, natija, sabab, mavzular, vazifalar

O‘qish — PostgREST, buyurtmalar ro‘yxati kabi: call_logs?select=id,created_at,caller_phone,did,direction,duration_seconds,billed_minutes,cost,status,language,transcript,recording_url,campaign_id,analysis&created_at=gte.<sana>&order=created_at.desc va sahifalash uchun Prefer: count=exact + Range. Analitika ekranlari odatda status=not.in.(test,director) filtrini qo‘shadi.

GET/api/calls/{id}/recording#

Qo‘ng‘iroq yozuvi, audio/ogg. Sessiya kerak; faqat o‘z biznesi (RLS) va call_recordings moduli yoqilgan bo‘lishi shart. Range sarlavhasi qo‘llanadi (206 Partial Content).

# Call recording (audio/ogg, supports Range so players can seek)
curl -s "$SITE/api/calls/$CALL_ID/recording" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Range: bytes=0-" -o call.ogg
# 401 Unauthorized | 403 Module disabled (no call_recordings) | 404 Not found / recording not ready yet

Chiqish qo‘ng‘iroqlari (kampaniyalar)#

Modul: campaigns (+ faol telefon raqam). Jadvallar:

  • campaigns: id, tenant_id, kind (custom — biznes tuzgan; reminder, callback va h.k. — avtomatlashtirish tizim kampaniyalari), name, phone_number_id, goal_prompt (AI uchun ko‘rsatma), greeting ([ism] o‘rniga mijoz ismi), status (draft, running, paused, completed), max_concurrent, window_start, window_end (HH:MM), max_attempts, retry_minutes, created_at.
  • campaign_contacts: id, campaign_id, tenant_id, phone, name, note, status (pending, calling, answered, no_answer, failed, skipped), attempts, result, last_attempt_at, next_attempt_at.

Amallar (PostgREST): kampaniya yaratish/tahrirlash; status ni running/paused ga o‘zgartirish; kontaktlarni upsert (onConflict: campaign_id,phone, ignoreDuplicates) bilan 500 tadan qo‘shish; javobsizlarni qayta navbatga qo‘yish — status: "pending", attempts: 0, next_attempt_at: null. Qo‘ng‘iroqlarni ovoz dvigateli navbatdan o‘zi oladi.

Telefon raqamlar#

Modul: phone_numbers. O‘qish uchun phone_numbers_safe ko‘rinishidan foydalaning (SIP paroli o‘rniga has_password): id, did (faqat raqamlar, 998…), label, provider, sip_host, sip_port, sip_username, sip_transport (udp/tcp/tls), register, status (pending, active, error, disabled, deleting), status_detail, has_password, provisioned.

  • Biznes faqat o‘z SIP trunk’ini qo‘shadi: phone_numbers ga did, SIP maydonlari, sip_password va status: "pending" bilan yozadi. PBX provisioner trunk’ni ulaydi va holatni active yoki error ga o‘zgartiradi (odatda bir daqiqa ichida) — holatni davriy o‘qing.
  • Platforma raqamlarini superadmin biriktiradi — ular ro‘yxatda ko‘rinadi.
  • Ulangan raqamni o‘chirish: provisioned = true bo‘lsa status: "deleting" qo‘ying (provisioner o‘zi o‘chiradi), aks holda qatorni o‘chiring. Takroriy raqam — 23505.

AI operator sozlamalari#

Modul: ai_agent. Jadval voice_agents (bitta biznesga bitta qator, upsert tenant_id bo‘yicha): is_active, greeting, system_prompt (qat’iy ko‘rsatma), voice, voice_ru, voice_tg, voice_ky, voice_kaa, languages (har doim uz bor), enabled_tools, transfer_phone (operator_transfer), recording_enabled, max_call_minutes (1–60), voice_settings, pronunciations. max_concurrent_calls ni faqat superadmin o‘zgartiradi.

enabled_tools qiymatlari: lookup_customer, upsert_customer, get_menu, query_knowledge, create_order, get_order_status, book_appointment, manage_appointment, create_lead, search_documents, save_feedback, create_appeal, get_appeal_status, lookup_account, submit_meter_reading — har biri o‘z moduli faol bo‘lsagina ishlaydi.

Diqqat: veb system_prompt ni saqlashdan oldin bazadagisi bilan solishtiradi — boshqa joyda o‘zgartirilgan bo‘lsa, foydalanuvchidan tasdiq so‘raydi. Ilovada ham shunday qiling, aks holda boshqa operatorning o‘zgarishi jimgina o‘chadi.

POST/api/voice/preview#

«Eshitish»: saqlanmagan diktor sozlamalari bilan matnni telefon sifatida (8 kHz WAV) qaytaradi. admin yoki superadmin, 30 so‘rov/daq. Tana: {"text": "…≤400 belgi", "voice": "…", "voice_settings": {...}, "pronunciations": [...]} → audio/wav. Xatolar: 400 "Matn bo‘sh", 429, 502/503 (ovoz dvigateli).

POST/api/voice/test-token#

«Sinab ko‘rish»: brauzer/ilova to‘g‘ridan-to‘g‘ri ovoz dvigateliga WebSocket orqali ulanadi. admin (superadmin ?tenant_id= bilan). ai_agent moduli kerak. Javob: {"token": "…", "ws_url": "wss://…"}. Sinov qo‘ng‘iroqlari pullik emas.

Bilimlar bazasi va hujjatlar#

  • knowledge_base (modul knowledge_base): category, question, answer, keywords, is_active. Hozir savol-javoblar asosan AI operatorning «Qat’iy ko‘rsatma»sida yoziladi; eski yozuvlar ko‘rsatmaga avtomatik qo‘shiladi.
  • kb_documents (modul knowledge_docs) — /api/admin/kb-docs orqali.

/api/admin/kb-docs#

Faqat admin.

MetodTana / so‘rovJavob
GET—{docs: [{id, title, source, filename, chars, is_active, created_at, preview}], active_chars, prompt_limit, tenant_max}
POST{title, text} yoki {title, filename, data: <base64>} (PDF, DOCX, XLSX, CSV, TXT, ≤10 MB){ok, id, chars}
PATCH{id, is_active?, title?}{ok}
DELETE?id=<uuid>{ok}

Cheklovlar: matn kamida 20 belgi ("empty"), bitta hujjat 200 000 belgigacha kesiladi, biznesga jami 400 000 belgi ("limit"). Fayl xatolari: "format", "size", "parse" (masalan, skanerlangan PDF).

Sozlamalar#

PUT/api/admin/settings#

Faqat admin. Biznes sozlamalari (app_settings) va brending (tenants):

MaydonIzoh
business_nameBiznes nomi (tenant nomi ham yangilanadi)
cityAsosiy shahar (geokod uchun)
logo_url, brand_color, accent_color, panel_color, background_colorBrending
currency_labelValyuta belgisi (masalan, so‘m)
support_phoneAloqa telefoni
default_delivery_feeStandart yetkazish narxi
map_default_lat, map_default_lng, map_default_zoomXarita markazi
director_phonesDirektor rejimi raqamlari (≤5, normallashtiriladi)

Javob: {"success": true}. app_settings ni o‘qish PostgREST orqali (select=*&tenant_id=eq.<id>); maxfiy qiymatlarni (bot tokeni, kassa kalitlari) ilovada ko‘rsatmang.

Avtomatlashtirish: GET / PUT /api/admin/automations#

Faqat admin. GET — settings (reminders, callbacks, alerts, sms, surveys, rules), modullar holati, SMS statistikasi (30 kun), baholar, Telegram ulanganmi, chiqish uchun SIP raqam bormi va tizim kampaniyalari statistikasi. PUT {"settings": {...}} — serverda tozalanib saqlanadi.

Muhim maydonlar: reminders.days_before (0–3), callbacks.delay_minutes, alerts.daily_report_time, alerts.low_balance_amount, sms.tpl_* ({business} {name} {number} {total} {date} {time} {service} {phone}), rules.blacklist, rules.hours (mon…sun: {on, from, to}), rules.after_hours (no_orders / lead_only).

Foydalanuvchilar va rollar#

/api/admin/users#

admin (yoki superadmin).

MetodTanaIzoh
POST{email, password (≥8), full_name, role: "admin"/"branch", custom_role_id?, allowed_modules?, branch_id?}branch uchun branch_id majburiy. Hisob darhol tasdiqlangan holda yaratiladi. Javob {profile}
PATCH{id, role?, custom_role_id?, allowed_modules?, branch_id?, full_name?}Javob {profile}
DELETE{id}Hisob o‘chiriladi

Ro‘yxat — PostgREST: profiles?select=*,tenant_roles(*).

/api/admin/roles#

Maxsus rollar (tenant_roles: name, description, modules, is_system). GET → {roles}; POST {name (≥2), description?, modules (≥1)}; PATCH {id, name?, description?, modules?}; DELETE {id} (tizim rollari o‘chmaydi).

Balans va billing#

Narx tuzilmasi: oylik = yoqilgan pullik modullar + gaplashilgan daqiqalar. Daqiqa narxi pog‘onali — oy boshidan jami daqiqa qaysi pog‘onaga yetsa, keyingi daqiqalar o‘sha narxda (pog‘onalar superadmin sozlamasida; standart: 1000 daqiqagacha 450, 5000 gacha 400, undan keyin 350 so‘m). Qo‘ng‘iroq yuqoriga yaxlitlangan daqiqada hisoblanadi; gapirilmagan va sinov qo‘ng‘iroqlari bepul. Balans manfiy bo‘lsa, AI operator yangi qo‘ng‘iroqlarni qabul qilmaydi.

  • tenants.balance — joriy balans (faqat o‘qish). Realtime: tenants (UPDATE) va billing_transactions.
  • billing_transactions: amount (+ kirim, − chiqim), type (topup, superadmin_topup, module_purchase, usage_deduction, eski subscription_purchase), provider (payme, click, superadmin, system), status, description, metadata, created_at.

GET/ POST /api/admin/billing#

GET — balans, faol pullik modullar, daqiqa pog‘onalari, shu oy foydalanish, oxirgi 50 tranzaksiya va qaysi to‘lov tizimlari ulangan. POST {"action": "create_checkout", "amount": ≥1000, "provider": "payme" | "click"} — faqat admin; javobdagi url ni brauzer yoki WebView’da oching. To‘lov tushgach balans avtomatik oshadi (Realtime orqali ko‘rinadi).

curl -s "$SITE/api/admin/billing" -H "Authorization: Bearer $ACCESS_TOKEN"

# Top-up link (admin only, minimum 1 000 UZS) - open the returned url in a browser / WebView
curl -s -X POST "$SITE/api/admin/billing" -H "Content-Type: application/json" -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"action":"create_checkout","amount":200000,"provider":"payme"}'

Xatolar: 400 "Minimal to‘lov summasi 1 000 so‘m", 400 "Payme integratsiyasi Super Admin tomonidan sozlanmagan.", 403 "Faqat biznes admini", 410 (subscribe_plan — eskirgan), 403 (mock_topup — prod’da o‘chiq).

Hisobotlar#

GET/api/admin/reports#

Faqat admin. type: calls (ai_agent), orders (orders), appointments, leads, campaigns (o‘z modullari), finance (hamma). from, to — YYYY-MM-DD (Toshkent kuni). Natija 10 000 yozuv bilan cheklanadi (truncated: true).

curl -s "$SITE/api/admin/reports?type=orders&from=2026-09-01&to=2026-09-30" -H "Authorization: Bearer $ACCESS_TOKEN"
# type: calls | orders | appointments | leads | campaigns | finance   (dates are Tashkent days, both inclusive)

Xatolar: 403 "forbidden" (admin emas), 400 "type", 403 "module".

Ommaviy import#

POST/api/admin/import#

Faqat admin, 20 so‘rov / 10 daq. {"entity": "customers" | "menu" | "leads", "rows": [{...}]} — 1–5000 qator (har bir tur uchun o‘z chegarasi bor). Kerakli modul yoqilgan bo‘lishi shart.

  • customers: phone (majburiy), name, address, notes — telefon bo‘yicha takrorlanmaydi; bor mijozda faqat to‘ldirilgan maydonlar yangilanadi.
  • menu: name, price (majburiy), category (yo‘q bo‘lsa «Asosiy»), name_ru, description — kategoriya+nom bo‘yicha takrorlanmaydi; bor mahsulotda narx yangilanadi.
  • leads: name, phone, topic, notes → source: "import".

Javob: {"inserted", "updated", "invalid", "duplicates"}. Xatolar: "forbidden", "rate", "bad", "too_many", "module".

POST/api/admin/import/ai#

Tartibsiz matnni (masalan, WhatsApp’dagi menyu) AI yordamida qatorlarga ajratadi — hech narsa saqlanmaydi, natijani foydalanuvchi ko‘rib, keyin /api/admin/import ga yuboradi. {"entity", "text": 3–12000 belgi}; 10 so‘rov / 10 daq. Xatolar: "busy" (429), "llm" (502), "engine" (503).

Sozlash oynasi#

  • POST /api/admin/setup — sozlash oynasini yakunlash (keyin /admin endi /admin/setup ga yo‘naltirmaydi). Faqat admin.
  • POST /api/admin/setup/draft — «AI bilan tez boshlash»: {"text": "≤4000", "url": "sayt yoki Instagram (ixtiyoriy)"} → modullar, salomlashuv, tillar va ko‘rsatma qoralamasi (page_read — havola o‘qildimi). Hech narsa saqlanmaydi. 6 so‘rov / 10 daq; xatolar "empty", "url" (422), "busy", "llm", "engine".

Integratsiyalar va webhook’lar#

Modul: crm_integrations. AI olgan buyurtma, qabul, lid, murojaat va qo‘ng‘iroqlar biznes ulagan tizimlarga avtomatik yuboriladi: webhook (o‘z serveringiz), Bitrix24 (lid), amoCRM (bitim + kontakt), Google Sheets (Apps Script).

Voqealar#

VoqeaQachonWebhookSheetsBitrix24 / amoCRM
order.createdYangi buyurtma✓✓✓
appointment.createdYangi qabul✓✓✓
appointment.changedQabul ko‘chirildi / bekor qilindi✓✓—
lead.createdYangi lid✓✓✓
appeal.createdYangi murojaat✓✓✓
appeal.changedMurojaat holati o‘zgardi✓✓—
feedback.createdMijoz bahosi✓✓—
call.endedQo‘ng‘iroq tugadi✓✓—

Webhook: POST, Content-Type: application/json, sarlavhalar:

SarlavhaQiymat
X-ErgeNext-DeliveryVoqea id’si (uuid, tanadagi id bilan bir xil) — qayta urinishlarda o‘zgarmaydi; takrorni shu bo‘yicha tashlang
X-ErgeNext-TimestampYuborilgan vaqt, Unix soniya
X-ErgeNext-Signature-V2sha256=<HMAC-SHA256(kalit, "<timestamp>.<tana>")> — shuni tekshiring
X-ErgeNext-AttemptUrinish raqami: 1, 2 yoki 3
X-ErgeNext-Signaturesha256=<HMAC-SHA256(kalit, tana)> — eski integratsiyalar uchun qoldirilgan; vaqt belgisi yo‘q, qayta yuborilgan (replay) so‘rovdan himoya qilmaydi

Imzoni xom tana (qayta serializatsiya qilmasdan) bo‘yicha hisoblang va vaqt belgisi 5 daqiqadan eski bo‘lsa so‘rovni rad eting. Har urinishga 8 soniya; tarmoq xatosi, 408, 429 yoki 5xx bo‘lsa 30 soniya va 5 daqiqadan keyin qayta yuboriladi (jami 3 urinish); boshqa 4xx javoblarida qayta yuborilmaydi. Har urinish kabinetdagi «Yuborishlar jurnali»da (integration_logs). Webhook URL faqat https://. Kalit birinchi saqlashda avtomatik yaratiladi. Bitrix24, amoCRM va Google Sheets’ga qayta yuborilmaydi (takroriy lid yaratmaslik uchun).

data maydonlari (voqeaga qarab): id, phone, name, title, amount, date, time, service, notes, rating, comment, duration_seconds, status, items[] (name, quantity, price).

POST https://your-server.example/ergenext-hook
Content-Type: application/json
X-ErgeNext-Delivery: 7c9e6679-7425-40de-944b-e07fc1f90ae7
X-ErgeNext-Timestamp: 1791100114
X-ErgeNext-Attempt: 1
X-ErgeNext-Signature-V2: sha256=9f86d081884c7d659a2feaa0c55ad015…
X-ErgeNext-Signature: sha256=5d41402abc4b2a76b9719d911017c592…

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "event": "order.created",
  "tenant_id": "3b0d7e55-…",
  "business": "Shirin Somsa",
  "occurred_at": "2026-10-04T09:05:14.120Z",
  "data": {
    "id": "a3f0…",
    "phone": "+998901234567",
    "name": "Abduqodir aka",
    "title": "Buyurtma #1042",
    "amount": 91000,
    "notes": "Domofon ishlamaydi",
    "items": [ { "name": "Lavash klassik", "quantity": 2, "price": 28000 } ]
  }
}

Imzoni tekshirish:

import crypto from "node:crypto";
import express from "express";

const app = express();
const seen = new Set();   // use your DB / Redis in production
// The signature is computed over the RAW body - do not re-serialize the JSON
app.post("/ergenext-hook", express.raw({ type: "application/json" }), (req, res) => {
  const ts = req.get("X-ErgeNext-Timestamp") || "";
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(401).end();
  const expected = "sha256=" + crypto.createHmac("sha256", process.env.ERGENEXT_WEBHOOK_SECRET)
    .update(`${ts}.`).update(req.body).digest("hex");
  const got = req.get("X-ErgeNext-Signature-V2") || "";
  const ok = got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
  if (!ok) return res.status(401).end();
  const id = req.get("X-ErgeNext-Delivery");
  if (seen.has(id)) return res.status(200).end();   // retry of an event we already handled
  seen.add(id);
  const event = JSON.parse(req.body.toString("utf8"));
  // event.event, event.data ...
  res.status(200).end();   // answer within 8 seconds; network errors / 5xx are retried after 30 s and 5 min
});

GET/ PUT / POST /api/admin/integrations#

Faqat admin. GET — sozlamalar (amoCRM tokeni va Bitrix24 webhook’ining maxfiy qismi •••• bilan yashiriladi) va oxirgi 30 ta yuborish. PUT {"settings": {webhook: {enabled, url, secret, events[]}, bitrix24: {enabled, webhook_url}, amocrm: {enabled, subdomain, token}, sheets: {enabled, url}}} — bo‘sh yoki •••• bilan kelgan maxfiy qiymat o‘zgarmaydi. POST {"target": "webhook" | "bitrix24" | "amocrm" | "sheets"} — namunaviy lid yuborib sinash → {ok, status, error} (400 "not_configured").

To‘lov havolalari (Payme / Click)#

Modul: payment_links. AI buyurtma olganda mijozga biznesning o‘z Payme yoki Click kassasiga to‘lov havolasi yuboriladi (SMS — sms_notify bilan). Pul to‘g‘ridan-to‘g‘ri biznes kassasiga tushadi, buyurtma payment_status: "paid" bo‘ladi va Telegram guruhga xabar ketadi.

Payme:  https://checkout.paycom.uz/<base64("m=<merchant_id>;ac.order_id=<order uuid>;a=<amount in tiyin>")>
Click:  https://my.click.uz/services/pay?service_id=<id>&merchant_id=<id>&amount=<UZS, 2 decimals>&transaction_param=<order uuid>

Merchant endpoints of the business cashbox (entered in the Payme / Click merchant cabinet):
  Payme:  POST https://app.ergenext.uz/api/pay/payme/<tenant_id>   (account field: order_id)
  Click:  POST https://app.ergenext.uz/api/pay/click/<tenant_id>   (same URL for Prepare and Complete)

GET/ PUT /api/admin/payments#

Faqat admin. GET → {settings (kalitlar ••••1234 ko‘rinishida), endpoints: {payme, click}, sms_module, payments: [oxirgi 20 ta]}. PUT {"settings": {enabled, provider: "payme"|"click", payme_merchant_id, payme_key, click_service_id, click_merchant_id, click_secret, sms_after_order}} — yashirilgan yoki bo‘sh kalit o‘zgarmaydi.

order_payments jadvali: order_id, provider, ext_id, amount (tiyin), state (1 yaratilgan, 2 to‘langan, -1 to‘lovdan oldin bekor, -2 to‘lovdan keyin qaytarilgan), create_time, perform_time, cancel_time, reason.

Merchant endpointlari (Payme / Click chaqiradi)#

  • POST /api/pay/payme/{tenant_id} — Payme Merchant API (JSON-RPC 2.0): CheckPerformTransaction, CreateTransaction, PerformTransaction, CancelTransaction, CheckTransaction, GetStatement. Authorization: Basic base64("Paycom:<kassa kaliti>"); hisob maydoni order_id; summa tiyinda; tranzaksiya 12 soatda eskiradi.
  • POST /api/pay/click/{tenant_id} — Click SHOP API (form-data), action 0 = Prepare, 1 = Complete; merchant_trans_id = buyurtma id; MD5 imzo har doim tekshiriladi.

Bu endpointlarni ilova chaqirmaydi — ular kassa sozlamasiga yoziladi.

Sayt chati va ilovadagi AI chat#

Modul: web_widget. Saytga bitta qator qo‘yiladi: <script src="https://app.ergenext.uz/widget.js" data-tenant="<tenant_id>" async></script>. Xuddi shu ochiq API’ni mobil ilova ham ishlatishi mumkin (masalan, «Yordam» chat ekrani) — avtorizatsiya kerak emas.

GET/ POST /api/chat/{tenant_id}#

CORS ochiq. Sozlamada ruxsat etilgan domenlar ko‘rsatilgan bo‘lsa, so‘rov Origin shu domenlardan bo‘lishi shart — Origin yubormaydigan mobil ilova uchun domenlar ro‘yxati bo‘sh bo‘lishi kerak. Xabar 1000 belgigacha kesiladi. phone berilsa (9–15 raqam), AI buyurtma/qabul uchun undan foydalanadi. Suhbat tarixi serverda session_id bo‘yicha saqlanadi.

# Widget appearance ({"enabled":false} if web_widget is off or the origin is not allowed)
curl -s "$SITE/api/chat/$TENANT_ID"

# Send a message: session_id = 16-64 chars [A-Za-z0-9_-], persist it on the device
curl -s -X POST "$SITE/api/chat/$TENANT_ID" -H "Content-Type: application/json" \
  -d '{"session_id":"app_7Hq2kLmN0pQrStUv","message":"Bugun soat nechagacha ishlaysiz?","phone":"+998901234567"}'

GET/PUT /api/admin/widget (admin): sozlamalar (title ≤60, color #RRGGBB, greeting ≤300, domains ≤20), tenant_id, tayyor <script> kodi va oxirgi 20 ta suhbat.

Telegram bot#

Modul: telegram_bot. Sozlamalar app_settings da: telegram_bot_token, telegram_bot_username, telegram_chat_id (xodimlar guruhi), telegram_welcome_message, telegram_is_active.

  • Webhook: POST /api/telegram/webhook?tenant_id=<uuid> — faqat Telegram chaqiradi. Kabinet setWebhook ni secret_token bilan o‘rnatadi (bot tokenidan hosil qilinadi); sarlavha X-Telegram-Bot-Api-Secret-Token mos kelmasa — 401.
  • Guruhga yangi buyurtma, qabul, lid va murojaat xabarlari tugmalar bilan keladi (holatni guruhdan o‘zgartirish mumkin).
  • Mijozlar boti: menyu/savatcha (buyurtmalar), qabul, lid; ai_chat moduli bilan erkin yozilgan savollarga AI javob beradi.
  • Kuryerlar shu bot orqali ishlaydi (Kuryerlar).

Speech API kalitlari#

TTS / STT / ovoz klonlash API’si alohida hujjatda: Speech API. Kalitlarni boshqarish: GET /api/admin/speech (kalitlar, klon ovozlar, 30 kunlik foydalanish, narxlar, limitlar, balans) va POST /api/admin/speech — {"action": "create_key", "name"} (faqat admin; kalit faqat shu javobda ko‘rsatiladi, bazada sha256), {"action": "revoke_key", "id"}, {"action": "delete_voice", "voice_id"}. Speech API kalitini mobil ilovaga qo‘ymang — ilova uchun vaqtinchalik token bor (Speech API hujjatiga qarang).

Realtime#

Supabase Realtime (postgres_changes) RLS bilan ishlaydi: foydalanuvchi faqat o‘z biznesi qatorlari o‘zgarishini oladi. Veb-kabinet obuna bo‘ladigan jadvallar:

JadvalHodisalarQayerda
ordersINSERT, UPDATE, DELETEBuyurtmalar (yangi buyurtmada ovozli signal), filial paneli (branch_id=eq.<id> filtri), kuryer statuslari
appointments*Qabullar
leads*Lidlar
appeals*Murojaatlar
billing_transactions*Balans sahifasi
tenantsUPDATEBalans o‘zgarishi
const channel = supabase
  .channel("orders-live")
  .on("postgres_changes", { event: "*", schema: "public", table: "orders" }, (payload) => {
    // payload.eventType: "INSERT" | "UPDATE" | "DELETE"; payload.new / payload.old
    if (payload.eventType === "INSERT") playChime();
  })
  .subscribe();
// For a branch user: { event: "*", schema: "public", table: "orders", filter: `branch_id=eq.${branchId}` }
// Stop: supabase.removeChannel(channel)
Maslahat: INSERT hodisasida order_items kelmaydi — yangi buyurtmani select=*,branches(id,name),order_items(*) bilan qayta o‘qing (veb ham shunday qiladi). Ilova fonga o‘tganda kanalni yoping, qaytganda ro‘yxatni qayta yuklab, qayta obuna bo‘ling.

Ochiq endpointlar#

EndpointIzoh
GET /api/health{"ok": true, "service": "…"} — monitoring
POST /api/contactSaytdagi aloqa formasi: {full_name (≥2), phone (≥7), company_name?, business_type?, message?} → {lead, message}
POST /api/demo-call, GET /api/demo-call?id=&key=Sayt «Sinab ko‘ring»: platforma demo qo‘ng‘irog‘i (bot himoyasi va kunlik limit bilan). Biznes ilovalari uchun emas
GET/POST /api/chat/{tenant}AI chat (yuqorida)
GET/PATCH /api/org/{token}Tashkilot portali (yuqorida)

Bu hujjatda yozilmagan /api/* yo‘llari platformaning ichki qismlari (ovoz dvigateli, to‘lov tizimlari, Telegram, platforma egasi paneli) uchun — ularni ilovada chaqirmang.

Barcha endpointlar#

MetodYo‘lKimModul
POST/api/auth/loginochiq (veb)—
POST/api/auth/registerochiq—
POST/api/ordersadminorders
GET, PATCH/api/orders/{id}admin, branchorders
DELETE/api/orders/{id}adminorders
GET/orders/{id}/receipt (HTML)admin, branchorders
GET, POST, PATCH, DELETE/api/admin/couriersadminorders
GET/api/calls/{id}/recordingsessiyacall_recordings
GET, PUT, POST, PATCH/api/admin/appealsadminappeals
GET, PUT/api/admin/automationsadmin— (bo‘limlar o‘z modullari bilan)
GET, POST/api/admin/billingsessiya (POST — admin)billing
POST/api/admin/import, /api/admin/import/aiadminentity moduli
GET, PUT, POST/api/admin/integrationsadmincrm_integrations
GET, POST, PATCH, DELETE/api/admin/kb-docsadminknowledge_docs
GET, PUT/api/admin/paymentsadminpayment_links
GET/api/admin/reportsadminturga qarab
GET, POST, PATCH, DELETE/api/admin/rolessessiya (yozish — admin)users
PUT/api/admin/settingsadminsettings
POST/api/admin/setup, /api/admin/setup/draftadmin—
GET, POST/api/admin/speechsessiya (POST — admin)—
POST, PATCH, DELETE/api/admin/usersadminusers
GET, PUT/api/admin/widgetadminweb_widget
POST/api/voice/previewadminai_agent
POST/api/voice/test-tokenadminai_agent
GET, POST/api/chat/{tenant}ochiqweb_widget
GET, PATCH/api/org/{token}tokenappeal_routing
POST/api/contact, /api/demo-callochiq—
GET/api/healthochiq—