Biznes uchun YONA API
Salon YONA’ga o‘z dasturini ulashi mumkin — 1C, o‘z CRM, bot yoki sayt. Ikki tomoni bor: siz bizdan so‘raysiz (REST so‘rovlar) va biror narsa yuz berganda biz o‘zimiz sizga murojaat qilamiz (vebhuklar). Har daqiqada so‘rab turish shart emas: hodisalarga obuna bepul va so‘rov chegarasini sarflamaydi.
Kimga ochiq
API va vebhuklar PRO hamda ENTERPRISE tariflariga kiradi. Sinov davrida qum solingan maydon ishlaydi: kalit chiqariladi, so‘rovlar past chegarada ishlaydi, sinov hodisasi tugma orqali yuboriladi, lekin haqiqiy yozuvlar tarqatilmaydi. SOLO tarifida API ishlamaydi.
Kalit
Kalitni salon egasi «Интеграции» bo‘limida chiqaradi. Kalit bir marta ko‘rsatiladi — biz faqat izini saqlaymiz va qaytadan ko‘rsata olmaymiz. Kalitning huquqlari bor: dasturingizga nima kerak bo‘lsa, o‘shani bering. Bekor qilingan kalit keyingi so‘rovdan ishlamaydi.
Qanday murojaat qilinadi
Barcha yo‘llar /api/v1 bilan boshlanadi. Kalit Authorization sarlavhasida yuboriladi. Kalitni tekshirish — GET /api/v1/me: saloningiz, kalit huquqlari va so‘rov chegarasi qaytadi.
curl -H "Authorization: Bearer yona_ab12cd34_…" \
https://yona.uz/api/v1/servicesChegaralar
PRO — bir daqiqada 120 so‘rov, ENTERPRISE — 600, sinov davri — 20. Oshib ketsa 429 va Retry-After sarlavhasi qaytadi. Har bir chaqiruv uchun pul olinmaydi.
Yo‘llar
| HTTP | Huquq | Nima qiladi |
|---|---|---|
| GET /api/v1/me | catalog:read | Salon, kalit huquqlari va chegara |
| GET /api/v1/services | catalog:read | Narx va davomiylik bilan xizmatlar (?archived=1 — arxiv bilan) |
| GET /api/v1/masters | catalog:read | Xodimlar va ulardan kim mijoz qabul qiladi |
| GET /api/v1/slots?serviceId&date&masterId | schedule:read | Salon kunidagi bo‘sh vaqt (YYYY-MM-DD) |
| GET /api/v1/bookings?from&to&status&masterId&customerId&limit&cursor | bookings:read | Yozuvlar sahifalab |
| GET /api/v1/bookings/{id} | bookings:read | Bitta yozuv |
| POST /api/v1/bookings | bookings:write | Yozuv yaratish: serviceId, startTime va customerId yoki customerName bilan customerPhone |
| POST /api/v1/bookings/{id}/cancel | bookings:write | Yozuvni bekor qilish |
| GET /api/v1/customers?limit&cursor | customers:read | Salon mijozlari sahifalab |
Vebhuklar
Manzilni salon egasi o‘sha bo‘limda qo‘shadi. Biz JSON tanasi bilan POST yuboramiz. Iloji boricha tez 2xx javob bering: javob tanasini o‘qimaymiz, ishni esa o‘z navbatingizga qo‘ying. Manzil https bo‘lishi va internetdan ochilishi kerak — ichki tarmoqqa bormaymiz va yo‘naltirishlarga ergashmaymiz.
Hodisalar
booking.created— Yangi yozuvbooking.confirmed— Yozuv tasdiqlandibooking.changed— Yozuv ko‘chirildibooking.cancelled— Yozuv bekor qilindibooking.completed— Tashrif yakunlandi
Imzo
Har bir yuborish sizning maxfiy kalitingiz bilan imzolanadi. X-Yona-Signature sarlavhasida t=<vaqt>,v1=<imzo> keladi, imzo — «vaqt.tana» satridan olingan HMAC-SHA256. Uni tekshiring va besh daqiqadan eskisini rad eting — aks holda yuborishni boshqa birov takrorlashi mumkin.
Imzoni tekshirmaslik — manzilingizni bilgan har kimdan yozuv qabul qilish demakdir.
const signature = request.headers['x-yona-signature']; // t=1758297600,v1=…
const [, timestamp, given] = /^t=(\d+),v1=([0-9a-f]+)$/.exec(signature) ?? [];
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return reject();
const expected = crypto
.createHmac('sha256', YOUR_WEBHOOK_SECRET)
.update(timestamp + '.' + rawBody) // the raw body, before JSON.parse
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(given, 'hex'))) return reject();Takrorlar
Agar 2xx javob bermasangiz yoki umuman javob bermasangiz, oltitagacha marta, oraliqni uzaytirib takrorlaymiz. Bitta hodisa ikki marta kelishi mumkin — X-Yona-Delivery sarlavhasiga tayanib, takrorni bajarilgan deb hisoblang. Ketma-ket o‘n besh yuborishni rad etgan manzilni o‘chirib qo‘yamiz va ekrandagi jurnalda yozamiz.
Rad javoblari
Xato javobi — `error` va `code` maydonli JSON. `code` bo‘yicha shoxlang: `error` matni jurnal o‘qiydigan odam uchun yozilgan va o‘zgarishi mumkin.
Nimadir noto‘g‘ri bo‘lsa
«Интеграции» ekranidagi yuborishlar jurnali har bir yuborishni ko‘rsatadi: vaqti, hodisasi, serveringiz javobi va «Qayta yuborish» tugmasi. Shundan boshlang.