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.
$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:
| Qatlam | Manzil | Avtorizatsiya | Nima uchun |
|---|---|---|---|
| Supabase Auth | $SUPABASE_URL/auth/v1/* | apikey: $ANON_KEY | Kirish (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 + Bearer | get_my_role, get_my_tenant_id, my_modules, modullarni yoqish va h.k. |
| Supabase Realtime | wss://…/realtime/v1 (SDK orqali) | sessiya tokeni | Yangi buyurtma, status o‘zgarishi va h.k. jonli |
| Next.js server | https://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 —
tenantsjadvalidagi bitta qator. Deyarli barcha jadvallardatenant_idustuni bor. - Foydalanuvchining biznesi
profiles.tenant_idda; SQL funksiyasiget_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_idni o‘zingiz qo‘ying (rpc/get_my_tenant_iddan). Asosiy jadvallarda (branches,delivery_zones,menu_categories,menu_items,orders,customers,appointments,leads,knowledge_base,tenant_roles) ustunning standart qiymatiget_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 biznesningtenant_idsi bilan yozish RLS xatosi (42501) beradi. - Filial xodimi (
branch) RLS darajasida ham cheklangan:orders(va ularningorder_items) dan faqatbranch_id = profiles.branch_idbo‘lganlarini o‘qiydi,profilesdan faqat o‘zini,branches,tenants,tenant_modules,tenant_rolesni faqat o‘qiydi; boshqa jadvallar (mijozlar, qo‘ng‘iroqlar, sozlamalar…) unga yopiq. PostgREST orqali hech narsa yoza olmaydi — buyurtma statusi va kuryer faqatPATCH /api/orders/{id}orqali. Filial biriktirilmagan filial xodimi hech qanday buyurtmani ko‘rmaydi. tenantsjadvalini (balans, holat) brauzer/ilova sessiyasi o‘zgartira olmaydi — pul harakatlari faqat serverda.
Rollar#
| Rol | Kim | Nima qila oladi |
|---|---|---|
admin | Biznes egasi yoki boshqaruvchi | Butun kabinet: barcha bo‘limlar, sozlamalar, modullar, xodimlar, balans |
branch | Filial xodimi (kassir, operator) | Faqat o‘z filiali buyurtmalari (/branch paneli): ko‘rish va statusni keyingi bosqichga o‘tkazish |
superadmin | Platforma egasi | Barcha 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#
- Platforma jamoasidan
SUPABASE_URLvaANON_KEYni oling (bu ochiq qiymatlar — veb-kabinet ham brauzerda ishlatadi). - Foydalanuvchini email va parol bilan kiriting —
access_tokenvarefresh_tokenolasiz. get_my_role,get_my_tenant_id,my_modulesni chaqirib, qaysi ekranlarni ko‘rsatishni hal qiling.- Ma’lumotlarni PostgREST orqali o‘qing; server amallari uchun
/api/*gaAuthorization: Bearer <access_token>bilan murojaat qiling. - 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"flutter_secure_storage, desktop — OS keychain (Electron safeStorage).Joriy foydalanuvchi, rol, biznes va modullar#
Kirgandan keyin darhol uchta RPC chaqiring va natijani keshlang:
| RPC | Javob | Izoh |
|---|---|---|
get_my_role | "admin", "branch" yoki "superadmin" | Rol yo‘q bo‘lsa — null (veb /login?error=norole ga qaytaradi) |
get_my_tenant_id | biznes uuid | Yangi qatorlarda tenant_id sifatida ishlating |
my_modules | faol modul kalitlari massivi | To‘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-kabinet qanday kiradi (cookie)#
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
401oladi. Tokenni oldindangrant_type=refresh_tokenbilan yangilang (SDK’lar buni o‘zi qiladi) va401da bir marta yangilab qayta urining. - Bearer so‘roviga javobda
Set-Cookiebo‘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.
| Maydon | Tur | Qoida |
|---|---|---|
company_name | string | kamida 2 belgi |
email | string | to‘g‘ri email |
password | string | kamida 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
messageichida 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#
| Status | Ma’nosi |
|---|---|
200 | Muvaffaqiyat (/api/* yaratishda ham 200) |
206 | Qisman kontent (qo‘ng‘iroq yozuvi, Range) |
400 | Validatsiya xatosi, noto‘g‘ri holat o‘tishi, «O‘zgarish yo‘q» |
401 | Foydalanuvchi aniqlanmadi (Unauthorized) |
403 | Rol yetmaydi (Forbidden, Faqat admin) yoki modul yoqilmagan (Modul yoqilmagan) |
404 | Topilmadi (yoki boshqa biznesga tegishli — RLS uni ko‘rsatmaydi) |
410 | Eskirgan amal (subscribe_plan — tariflar o‘rniga endi modullar) |
429 | So‘rovlar limiti |
500 / 502 / 503 | Server, 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). Hisobotlardagifrom/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:
| Endpoint | Limit |
|---|---|
POST /api/auth/register | 5 / 10 daq, IP bo‘yicha |
POST /api/admin/import | 20 / 10 daq, foydalanuvchi bo‘yicha |
POST /api/admin/import/ai | 10 / 10 daq, foydalanuvchi bo‘yicha |
POST /api/admin/setup/draft | 6 / 10 daq, foydalanuvchi bo‘yicha |
POST /api/voice/preview | 30 / 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.
| Guruh | Modul kalitlari |
|---|---|
| Asosiy (doim bepul) | settings, users, billing, customers, branches |
| AI va telefoniya | ai_agent, phone_numbers, call_recordings, operator_transfer, campaigns, director_mode, ai_chat, web_widget, branch_routing |
| Avtomatlashtirish | reminder_calls, callback_calls, feedback_calls, owner_alerts, sms_notify, call_rules |
| Tillar | multilang (rus), lang_tg, lang_ky, lang_kaa (o‘zbek doim bor) |
| Savdo | menu, orders, delivery_zones, payment_links |
| Mijozlar bilan ishlash | appointments, leads, knowledge_base, knowledge_docs, telegram_bot, crm_integrations |
| Tahlil | analytics, call_analytics |
| Davlat va kommunal | appeals, 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"}'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#
| Maydon | Tur | Izoh |
|---|---|---|
id | uuid | |
order_number | int | Biznes ichidagi tartib raqami (mijozga aytiladi) |
status | string | new, accepted, delivering, done (+ eski: preparing, ready, cancelled) |
customer_id | uuid, null | customers ga bog‘lanish |
customer_name, customer_phone | string | Buyurtma paytidagi qiymatlar |
delivery_address | string | Geokod qilingan bo‘lsa — formatlangan manzil |
delivery_lat, delivery_lng | number, null | |
branch_id | uuid, null | Zona/eng yaqin filial bo‘yicha avtomatik yoki qo‘lda |
notes | string, null | |
subtotal, delivery_fee, total | number | so‘m |
source | string | voice_ai, admin, telegram, … |
transcript | string, null | AI suhbat matni (AI buyurtmasida) |
courier_id | uuid, null | Yangi Biriktirilgan kuryer |
accepted_at, delivering_at, delivered_at | timestamp, null | Yangi Status o‘zgargan vaqtlar |
courier_notified_at | timestamp, null | Yangi Kuryerga chek oxirgi marta yuborilgan vaqt |
deliver_on | date, null | Yangi Yetkazish kuni (AI agent ertangi kunga shakllantirgan buyurtmalar) |
payment_status | string | unpaid, pending, paid, refunded (to‘lov havolasi moduli) |
pay_provider, paid_at | string, timestamp | payme / click |
created_at, updated_at | timestamp |
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).
| Kim | Qoida |
|---|---|
admin | Istalgan joriy statusdan new, accepted, delivering, done ga |
branch | Faqat 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.
| Maydon | Tur | Qoida |
|---|---|---|
phone | string | majburiy, kamida 9 belgi, UZ raqami |
customer_name | string | ixtiyoriy |
delivery_address | string | majburiy, kamida 3 belgi |
notes | string | ixtiyoriy |
branch_id | uuid, null | ixtiyoriy; shu biznes filiali bo‘lishi shart |
items | massiv | 1–40 ta |
items[].menu_item_id | uuid | ixtiyoriy — bo‘lsa nom va narx menyudan |
items[].name | string | menu_item_id bo‘lmasa — menyudan nom bo‘yicha qidiriladi |
items[].quantity | int | 1–50 |
items[].unit_price | number | menyuda 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.
| Maydon | Tur | Kim | Izoh |
|---|---|---|---|
status | new, accepted, delivering, done | admin, branch | O‘tish qoidalari yuqorida |
courier_id | uuid, null | admin, branch | Shu biznesning faol kuryeri |
resend_receipt | boolean | admin, branch | Chekni kuryerga qayta yuborish |
notes | string (≤2000), null | faqat admin | |
branch_id | uuid, null | faqat admin |
Qoidalar:
acceptedga o‘tkazishda biznesda kamida bitta faol kuryer bo‘lsa, kuryer majburiy (courier_idshu so‘rovda yoki avval berilgan bo‘lishi kerak) — aks holda400 "Kuryerni tanlang".- Kuryerga chek quyidagi hollarda avtomatik ketadi: buyurtma
acceptedbo‘lganda; faol buyurtmada (accepted/preparing/ready/delivering) kuryer almashtirilganda;resend_receipt: truebo‘lganda. - Chek yuborilmasa ham o‘zgarishlar saqlanadi; sabab
courier.errorda: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 onlyDELETE/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#
| Maydon | Izoh |
|---|---|
id | majburiy, uuid |
name, phone | tahrirlash |
is_active | faolsizlantirilgan kuryer buyurtmaga tanlanmaydi |
new_link | yangi bir martalik kod (eski havola ishlamay qoladi) |
unlink | Telegram’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:
- Kuryer havolani ochadi va Start ni bosadi —
couriers.telegram_chat_idyoziladi, kod ishlatilgach o‘chadi. - Operator buyurtmani
acceptedqiladi — kuryerga chek: mijoz, telefon, manzil va xarita havolasi, mahsulotlar, jami, to‘lov holati. - Kuryer «📦 Bugungi zakazlar» ni bosadi — yo‘ldagilar, keyin kutayotganlar, keyin bugun yetkazilganlar va yig‘iladigan summa.
- «🛵 Yo‘lga chiqdim» →
status = delivering, «✅ Yetkazildi» →status = done. O‘zgarishordersRealtime 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
customersda bo‘lsa, AI mijozni kartadagi ism bilan kutib oladi va buyurtmada manzil so‘ramaydi — buyurtmaaddressga yoziladi (mijoz boshqa manzil aytmasa). Shuning uchunnamevaaddressni 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_transfermodullari yoqilgan bo‘lsa, telefoni kiritilgan faol filiallar AI uchun «ulash yo‘nalishi» bo‘ladi: mijoz aytgan filialga qo‘ng‘iroq ulanadi.- Filial xodimi (
branchroli)profiles.branch_idorqali 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 — avvallng).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/lngberilsa — 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, yokicancelled. - 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(moduloutages):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_ato‘tgach o‘zi to‘xtaydi.accounts(modulaccounts):account_number(biznes ichida yagona — upsertonConflict: tenant_id,account_number),holder_name,address,phone,balance(qarz — manfiy),status,updated_at. RPCaccounts_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):
| Maydon | Izoh |
|---|---|
id, tenant_id, created_at | |
caller_phone, did | Mijoz raqami va biznes raqami |
direction | inbound / outbound |
duration_seconds, billed_minutes, cost | Daqiqa yuqoriga yaxlitlanadi; no_speech va sinov hisoblanmaydi |
status | completed, no_speech, transferred, busy, failed, test, director |
language | Suhbat tili |
transcript | Suhbat matni |
recording_url | Yozuv mavjudligi belgisi |
campaign_id, order_id | Kampaniya / buyurtma bilan bog‘lanish |
analysis | Suhbat 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 yetChiqish qo‘ng‘iroqlari (kampaniyalar)#
Modul: campaigns (+ faol telefon raqam). Jadvallar:
campaigns:id,tenant_id,kind(custom— biznes tuzgan;reminder,callbackva 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_numbersgadid, SIP maydonlari,sip_passwordvastatus: "pending"bilan yozadi. PBX provisioner trunk’ni ulaydi va holatniactiveyokierrorga o‘zgartiradi (odatda bir daqiqa ichida) — holatni davriy o‘qing. - Platforma raqamlarini superadmin biriktiradi — ular ro‘yxatda ko‘rinadi.
- Ulangan raqamni o‘chirish:
provisioned = truebo‘lsastatus: "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.
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(modulknowledge_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(modulknowledge_docs) —/api/admin/kb-docsorqali.
/api/admin/kb-docs#
Faqat admin.
| Metod | Tana / so‘rov | Javob |
|---|---|---|
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):
| Maydon | Izoh |
|---|---|
business_name | Biznes nomi (tenant nomi ham yangilanadi) |
city | Asosiy shahar (geokod uchun) |
logo_url, brand_color, accent_color, panel_color, background_color | Brending |
currency_label | Valyuta belgisi (masalan, so‘m) |
support_phone | Aloqa telefoni |
default_delivery_fee | Standart yetkazish narxi |
map_default_lat, map_default_lng, map_default_zoom | Xarita markazi |
director_phones | Direktor 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).
| Metod | Tana | Izoh |
|---|---|---|
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) vabilling_transactions.billing_transactions:amount(+ kirim, − chiqim),type(topup,superadmin_topup,module_purchase,usage_deduction, eskisubscription_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/adminendi/admin/setupga 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#
| Voqea | Qachon | Webhook | Sheets | Bitrix24 / amoCRM |
|---|---|---|---|---|
order.created | Yangi buyurtma | ✓ | ✓ | ✓ |
appointment.created | Yangi qabul | ✓ | ✓ | ✓ |
appointment.changed | Qabul ko‘chirildi / bekor qilindi | ✓ | ✓ | — |
lead.created | Yangi lid | ✓ | ✓ | ✓ |
appeal.created | Yangi murojaat | ✓ | ✓ | ✓ |
appeal.changed | Murojaat holati o‘zgardi | ✓ | ✓ | — |
feedback.created | Mijoz bahosi | ✓ | ✓ | — |
call.ended | Qo‘ng‘iroq tugadi | ✓ | ✓ | — |
Webhook: POST, Content-Type: application/json, sarlavhalar:
| Sarlavha | Qiymat |
|---|---|
X-ErgeNext-Delivery | Voqea id’si (uuid, tanadagi id bilan bir xil) — qayta urinishlarda o‘zgarmaydi; takrorni shu bo‘yicha tashlang |
X-ErgeNext-Timestamp | Yuborilgan vaqt, Unix soniya |
X-ErgeNext-Signature-V2 | sha256=<HMAC-SHA256(kalit, "<timestamp>.<tana>")> — shuni tekshiring |
X-ErgeNext-Attempt | Urinish raqami: 1, 2 yoki 3 |
X-ErgeNext-Signature | sha256=<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 maydoniorder_id; summa tiyinda; tranzaksiya 12 soatda eskiradi.POST /api/pay/click/{tenant_id}— Click SHOP API (form-data),action0 = 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. KabinetsetWebhooknisecret_tokenbilan o‘rnatadi (bot tokenidan hosil qilinadi); sarlavhaX-Telegram-Bot-Api-Secret-Tokenmos 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_chatmoduli 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:
| Jadval | Hodisalar | Qayerda |
|---|---|---|
orders | INSERT, UPDATE, DELETE | Buyurtmalar (yangi buyurtmada ovozli signal), filial paneli (branch_id=eq.<id> filtri), kuryer statuslari |
appointments | * | Qabullar |
leads | * | Lidlar |
appeals | * | Murojaatlar |
billing_transactions | * | Balans sahifasi |
tenants | UPDATE | Balans 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)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#
| Endpoint | Izoh |
|---|---|
GET /api/health | {"ok": true, "service": "…"} — monitoring |
POST /api/contact | Saytdagi 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#
| Metod | Yo‘l | Kim | Modul |
|---|---|---|---|
| POST | /api/auth/login | ochiq (veb) | — |
| POST | /api/auth/register | ochiq | — |
| POST | /api/orders | admin | orders |
| GET, PATCH | /api/orders/{id} | admin, branch | orders |
| DELETE | /api/orders/{id} | admin | orders |
| GET | /orders/{id}/receipt (HTML) | admin, branch | orders |
| GET, POST, PATCH, DELETE | /api/admin/couriers | admin | orders |
| GET | /api/calls/{id}/recording | sessiya | call_recordings |
| GET, PUT, POST, PATCH | /api/admin/appeals | admin | appeals |
| GET, PUT | /api/admin/automations | admin | — (bo‘limlar o‘z modullari bilan) |
| GET, POST | /api/admin/billing | sessiya (POST — admin) | billing |
| POST | /api/admin/import, /api/admin/import/ai | admin | entity moduli |
| GET, PUT, POST | /api/admin/integrations | admin | crm_integrations |
| GET, POST, PATCH, DELETE | /api/admin/kb-docs | admin | knowledge_docs |
| GET, PUT | /api/admin/payments | admin | payment_links |
| GET | /api/admin/reports | admin | turga qarab |
| GET, POST, PATCH, DELETE | /api/admin/roles | sessiya (yozish — admin) | users |
| PUT | /api/admin/settings | admin | settings |
| POST | /api/admin/setup, /api/admin/setup/draft | admin | — |
| GET, POST | /api/admin/speech | sessiya (POST — admin) | — |
| POST, PATCH, DELETE | /api/admin/users | admin | users |
| GET, PUT | /api/admin/widget | admin | web_widget |
| POST | /api/voice/preview | admin | ai_agent |
| POST | /api/voice/test-token | admin | ai_agent |
| GET, POST | /api/chat/{tenant} | ochiq | web_widget |
| GET, PATCH | /api/org/{token} | token | appeal_routing |
| POST | /api/contact, /api/demo-call | ochiq | — |
| GET | /api/health | ochiq | — |