Maktab API

Umumiy ko‘rinish

School API tizimingizga (CRM, to‘lov xizmati, o‘z saytingiz) talabalarni Courstore’dagi maktab kurslariga qabul qilish va ularning kirishini tekshirish imkonini beradi. To‘lovni o‘zingiz qabul qilasiz — API faqat kursga kirishni ochadi.

• Asosiy URL: https://api.courstore.com/v1/school-api
• Format: JSON. So‘rov tanasi — Content-Type: application/json, hajmi 4 KB gacha.
• Avtorizatsiya: X-School-Key sarlavhasidagi maktab kaliti.
• Kirish: Pro (yillik), Lifetime va Enterprise tariflari. Boshqa tariflarda API 403 tariff_not_allowed qaytaradi — tarif har bir so‘rovda tekshiriladi.
• Xatolar doim JSON ko‘rinishida keladi: {"error": "kod", "message": "matn"}.

To‘liq mashina o‘qiydigan spetsifikatsiya: Swagger.

Tez boshlash

1. Tarifni tekshiring. API Pro (yillik), Lifetime va Enterprise tariflarida mavjud.
2. Kalit oling. Maktab kabinetida «Integratsiyalar» → «Maktab API» → «Kalit yaratish» bo‘limini oching. cs_live_… ko‘rinishidagi kalit faqat bir marta ko‘rsatiladi — darhol ishonchli joyga saqlab qo‘ying. 3 tagacha faol kalit saqlash mumkin, istalganini bekor qilish mumkin.
3. Birinchi so‘rovni yuboring. Maktab kurslari ro‘yxatini oling — javobda qabul qilish uchun kerak bo‘ladigan kurslarning id qiymatlari bo‘ladi.

export KEY="cs_live_..."
export BASE="https://api.courstore.com/v1/school-api"

curl -s "$BASE/courses" \
  -H "X-School-Key: $KEY"

[
  {
    "id": 1234,
    "title": "Основы маркетинга",
    "slug": "osnovy-marketinga",
    "status": "publish",
    "access": {
      "mode": "months",
      "amount": 3
    }
  },
  {
    "id": 1301,
    "title": "Мастер-класс",
    "slug": "master-klass",
    "status": "publish",
    "access": {
      "mode": "unlimited",
      "amount": null
    }
  }
]

Keyin talabani kursga qabul qiling — batafsil «Kursga qabul qilish» metodida:

curl -s -X POST "$BASE/enrollments" \
  -H "X-School-Key: $KEY" \
  -H "Idempotency-Key: order-0042" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+77001234567","courseId":1234,"access":{"mode":"days","amount":30},"notify":true,"orderRef":"CRM-0042"}'

{
  "requestId": "req_882",
  "status": "queued",
  "studentId": 118350,
  "enrollmentId": null,
  "expireDate": null,
  "lastDay": null
}

queued holatidagi 202 javobi qabul navbatga olinganini bildiradi. Natijani «Qabul holati» metodidan oling (odatda bir necha soniyada tayyor bo‘ladi).

Autentifikatsiya

Har bir so‘rovda maktab kaliti bilan X-School-Key sarlavhasi bo‘lishi kerak:

curl -s "https://api.courstore.com/v1/school-api/courses" \
  -H "X-School-Key: cs_live_..."

• Kalit kabinetda yaratiladi: «Integratsiyalar» → «Maktab API». Formati — cs_live_…, bir marta ko‘rsatiladi.
• Maktabga 3 tagacha faol kalit beriladi. Istalgan kalitni shu kartochkada bekor qilish mumkin; uni ishlatadigan integratsiyalar ishlashdan to‘xtaydi.
• Kalitni o‘z serveringizda saqlang. Uni mobil ilovalarga, brauzer kodiga va ochiq repozitoriylarga joylashtirmang.
• Muddat majburiy emas: kalit yaratishda «gacha amal qiladi» sanasini ko‘rsatish mumkin (shu kun ham kiradi). Undan keyin kalit 401 key_expired qaytaradi — yangisini yarating.
• Maktab tarifi tugasa, uning barcha kalitlari avtomatik va butunlay bekor qilinadi; tarifni uzaytirgach yangi kalit yarating. Bekor qilingan kalit 401 bad_key oladi.
• Kalit berilmasa, noto‘g‘ri bo‘lsa yoki bekor qilingan bo‘lsa — 401 javobi keladi:

{
  "error": "bad_key",
  "message": "Неверный ключ API"
}

Kalit to‘g‘ri, lekin maktab tarifi API’ga kirishni bermasa — 403 tariff_not_allowed. «Maktab API» kartochkasida bugungi kalit ishlatilishi va oxirgi xatolar ko‘rinadi.

Metodlar

Quyidagi misollarda «Tez boshlash» bo‘limidagi $BASE va $KEY o‘zgaruvchilari ishlatiladi. Yo‘llar asosiy URL — https://api.courstore.com/v1/school-api — ga nisbatan ko‘rsatilgan.

curl -s "$BASE/courses" \
  -H "X-School-Key: $KEY"

[
  {
    "id": 1234,
    "title": "Основы маркетинга",
    "slug": "osnovy-marketinga",
    "status": "publish",
    "access": {
      "mode": "months",
      "amount": 3
    }
  },
  {
    "id": 1301,
    "title": "Мастер-класс",
    "slug": "master-klass",
    "status": "publish",
    "access": {
      "mode": "unlimited",
      "amount": null
    }
  }
]

curl -s -X POST "$BASE/students" \
  -H "X-School-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+7 (700) 123-45-67","name":"Анна","email":"anna@example.com","lang":"ru"}'

{
  "studentId": 118350,
  "created": true
}

{
  "studentId": 118347,
  "created": false
}

curl -s -X POST "$BASE/enrollments" \
  -H "X-School-Key: $KEY" \
  -H "Idempotency-Key: order-0042" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+77001234567","name":"Анна","courseId":1234,"orderRef":"CRM-2026-0042"}'

{
  "requestId": "req_882",
  "status": "queued",
  "studentId": 118350,
  "enrollmentId": null,
  "expireDate": null,
  "lastDay": null
}

{
  "requestId": "req_881",
  "status": "done",
  "studentId": 118347,
  "enrollmentId": 902113,
  "expireDate": "2026-12-01",
  "lastDay": "2026-11-30"
}

curl -s "$BASE/enrollments/req_882" \
  -H "X-School-Key: $KEY"

{
  "requestId": "req_882",
  "status": "done",
  "studentId": 118350,
  "courseId": 1234,
  "expireDate": "2027-01-20",
  "lastDay": "2027-01-19",
  "notified": true,
  "error": null
}

curl -s "$BASE/enrollments?phone=%2B77001234567&courseId=1234" \
  -H "X-School-Key: $KEY"

{
  "active": true,
  "expireDate": "2026-12-01",
  "lastDay": "2026-11-30",
  "progress": 35
}

O‘quvchi uchun kirish havolasi

Servisingiz o‘quvchiga bir martalik havola bera oladi: u parolsiz Courstore’dagi maktabingiz kabinetini ochadi. Havoladagi token — 32 tasodifiy bayt, bizda faqat xesh saqlanadi, birinchi ishlatilgandan keyin havola o‘chadi.

curl -s -X POST "$BASE/students/login-link" \
  -H "X-School-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+77001234567","redirect":1234,"ttlSeconds":120}'

{
  "url": "https://myschool.courstore.com/ru/login-via-token?token=csl_...&returnUrl=courses%2Fosnovy-marketinga",
  "expiresAt": "2026-10-16T10:02:00Z"
}

curl -s -X POST "$BASE/students/login-link" \
  -H "X-School-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+77001234567","ttlSeconds":86400}'

app.get("/go-to-courstore", requireLogin, async (req, res) => {
  const r = await fetch(`${API}/students/login-link`, {
    method: "POST",
    headers: { "X-School-Key": KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ phone: req.user.phone, redirect: 1234 }),
  });
  if (r.status !== 200) return res.redirect("https://myschool.courstore.com/ru/login");
  const { url } = await r.json();
  res.redirect(url);
});

Vebxuklar

Vebxuklar tizimingizga qabul qilishlar va kirish o‘zgarishlari haqida API’ni so‘ramasdan darhol xabar beradi: Courstore manzilingizga o‘zi POST yuboradi.

{
  "id": "evt_8f3a1c0e2b7d4a91",
  "type": "enrollment.created",
  "createdAt": "2026-10-16T10:00:00Z",
  "schoolId": 7,
  "data": {
    "enrollmentId": 501,
    "student": {
      "id": 118347,
      "name": "Анна",
      "phone": "+77001234567",
      "email": null
    },
    "course": {
      "id": 1234,
      "title": "Основы маркетинга"
    },
    "accessUntil": "2026-12-31"
  }
}

{
  "id": "evt_1b9e44d07c2f8e30",
  "type": "access.revoked",
  "createdAt": "2026-10-20T08:15:00Z",
  "schoolId": 7,
  "data": {
    "enrollmentId": 501,
    "student": {
      "id": 118347,
      "name": "Анна",
      "phone": "+77001234567",
      "email": null
    },
    "course": {
      "id": 1234,
      "title": "Основы маркетинга"
    }
  }
}

POST /courstore/webhook HTTP/1.1
Content-Type: application/json
X-Courstore-Event: enrollment.created
X-Courstore-Delivery: evt_8f3a1c0e2b7d4a91
X-Courstore-Signature: t=1792144800,v1=5f0c2b…

const crypto = require("crypto");
const express = require("express");
const app = express();

app.post("/courstore/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries(
    String(req.get("X-Courstore-Signature") || "").split(",").map((p) => p.split("="))
  );
  const expected = crypto
    .createHmac("sha256", process.env.COURSTORE_WEBHOOK_SECRET)
    .update(sig.t + "." + req.body.toString("utf8"))
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) < 300;
  const ok = fresh && typeof sig.v1 === "string" && sig.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString("utf8"));
  // event.id — idempotency key; event.type — enrollment.created | access.extended | ...
  res.sendStatus(200);
});

<?php
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_COURSTORE_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('COURSTORE_WEBHOOK_SECRET'));

if (abs(time() - (int)($sig['t'] ?? 0)) > 300 || !hash_equals($expected, (string)($sig['v1'] ?? ''))) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
// $event['id'] — idempotency key; $event['type'] — event type
http_response_code(200);

import hashlib, hmac, os, time
from flask import Flask, request

app = Flask(__name__)

@app.post("/courstore/webhook")
def courstore_webhook():
    body = request.get_data()
    header = request.headers.get("X-Courstore-Signature", "")
    sig = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    expected = hmac.new(os.environ["COURSTORE_WEBHOOK_SECRET"].encode(),
                        sig.get("t", "").encode() + b"." + body, hashlib.sha256).hexdigest()
    t = sig.get("t", "")
    fresh = t.isdigit() and abs(time.time() - int(t)) <= 300
    if not fresh or not hmac.compare_digest(expected, sig.get("v1", "")):
        return "", 401
    event = request.get_json()
    # event["id"] — idempotency key; event["type"] — event type
    return "", 200

Idempotentlik

POST /enrollments metodi Idempotency-Key sarlavhasini talab qiladi — operatsiyaning noyob kaliti, masalan CRM’dagi buyurtma raqami (128 belgigacha: harflar, raqamlar, . _ : -). U so‘rovni takrorlashni xavfsiz qiladi: taym-aut sababli javob yo‘qolsa, so‘rovni shu kalit bilan takrorlang — talaba ikki marta qabul qilinmaydi.

{
  "error": "idempotency_conflict",
  "message": "Этот Idempotency-Key уже использован с другим телом запроса"
}

Buni qayta xarid bilan adashtirmang: talaba kursga allaqachon qabul qilingan bo‘lsa va siz yangi operatsiya yuborsangiz (boshqa Idempotency-Key), kirish muddati uzaytiriladi — «Kirish muddati» bo‘limiga qarang.

Kirish muddati

Kirish muddati quyidagicha aniqlanadi:

• So‘rovda access obyekti berilsa, muddat undan olinadi: mode = days (amount 1 dan 3650 gacha) yoki months (amount 1 dan 120 gacha).
• access berilmasa, muddat kurs sozlamalaridan olinadi. Ularni GET /courses javobidagi access maydonida ko‘rish mumkin: mode = days / months va amount, yoki unlimited (muddatsiz kirish, amount = null).

{
  "phone": "+77001234567",
  "courseId": 1234,
  "access": {
    "mode": "months",
    "amount": 3
  }
}

Javoblarda va qabul holatida: lastDay — kirishning oxirgi kuni, expireDate — kirish yopiladigan chegara; null — muddatsiz kirish yoki sana hali noma’lum.

Qayta xarid. Talaba bu kursga avval qabul qilingan bo‘lsa, kirish darhol uzaytiriladi: hisob ikki sananing kattasidan — bugundan yoki kirishning joriy tugashidan — boshlanadi. Javob — 200, status: done (navbatsiz).

Talabaga xabarnomalar

API orqali qabul kabinetdan qo‘lda qabul qilish bilan bir xil navbat orqali o‘tadi. Talaba bir xil xabarlarni oladi: WhatsApp / WABA / Telegram / pochta.

• notify parametri (odatiy true); false qiymati shu qabul uchun xabarnomalarni o‘chiradi.
• Qayta xaridda (uzaytirish) talaba Telegram’da xabarnoma oladi — kabinetdagi «Kirishni uzaytirish» kabi.
• Qabul holatida notified: true xabarnoma yuborishga qo‘yilganini bildiradi. WhatsApp/Telegram’ga yetkazilishini xizmat tasdiqlamaydi.

{
  "phone": "+77001234567",
  "courseId": 1234,
  "notify": false
}

Limitlar

Cheklovlar platformani va talabalaringizni integratsiyadagi tasodifiy sikllardan himoya qiladi.

So‘rovlar limiti oshib ketsa, javobda Retry-After sarlavhasi bo‘ladi — takrorlashgacha soniyalar soni. Bugungi foydalanish kabinetdagi «Maktab API» kartochkasida ko‘rinadi.

Xatolar

Barcha xatolar kod va tavsifli JSON ko‘rinishida keladi:

{
  "error": "validation_error",
  "message": "phone: некорректный номер телефона"
}

HTTP holatiga va error maydoniga (mashina kodi) tayaning; message matni jurnallar uchun mo‘ljallangan.

failed holatidagi qabul uchun error maydonida not_confirmed bo‘ladi: 15 daqiqa ichida qabul tasdiqlanmadi.

Maxfiylik

API faqat sizning maktabingiz ma’lumotlarini ko‘rsatadi.

• POST /students javobidagi created: true talaba sizning maktabingizda hali bo‘lmaganini bildiradi — uning akkaunti platformada boshqa maktabda mavjud bo‘lsa ham. Maktabingiz uchun bog‘lanish yaratiladi, begona ma’lumotlar ochilmaydi.
• created: false — talaba sizning maktabingizda allaqachon o‘qiydi. Mavjud talabaning ismi va pochtasi qayta yozilmaydi.
• Maktabingiz bilan bog‘lanmagan talaba uchun kirishni tekshirish mavjud bo‘lmagan talaba bilan bir xil javob beradi: active: false.
• GET /courses faqat kalit egasi maktabining kurslarini qaytaradi; begona kurs 404 course_not_found javobini beradi.