Мектеп API

Шолу

School API сіздің жүйеңізге (CRM, төлем сервисі, өз сайтыңыз) студенттерді Courstore-дағы мектеп курстарына қабылдауға және олардың қолжетімділігін тексеруге мүмкіндік береді. Төлемді өзіңіз қабылдайсыз — API тек курсқа қолжетімділікті ашады.

• Негізгі URL: https://api.courstore.com/v1/school-api
• Формат: JSON. Сұраныс денесі — Content-Type: application/json, көлемі 4 КБ-қа дейін.
• Авторизация: X-School-Key тақырыбындағы мектеп кілті.
• Қолжетімділік: Pro (жылдық), Lifetime және Enterprise тарифтері. Қалған тарифтерде API 403 tariff_not_allowed қайтарады — тариф әр сұраныста тексеріледі.
• Қателер әрқашан JSON түрінде келеді: {"error": "код", "message": "мәтін"}.

Толық машина оқитын спецификация: Swagger.

Жылдам бастау

1. Тарифті тексеріңіз. API Pro (жылдық), Lifetime және Enterprise тарифтерінде қолжетімді.
2. Кілт алыңыз. Мектеп кабинетінде «Интеграциялар» → «Мектеп API» → «Кілт жасау» бөлімін ашыңыз. cs_live_… түріндегі кілт бір рет қана көрсетіледі — бірден сенімді жерге сақтап қойыңыз. 3 белсенді кілтке дейін ұстауға болады, кез келгенін қайтарып алуға болады.
3. Алғашқы сұранысты жіберіңіз. Мектеп курстарының тізімін алыңыз — жауапта қабылдауға қажетті курстардың id мәндері болады.

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
    }
  }
]

Содан кейін студентті курсқа қабылдаңыз — толығырақ «Курсқа қабылдау» әдісінде:

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 мәртебесі бар 202 жауабы қабылдау кезекке қабылданғанын білдіреді. Нәтижені «Қабылдау мәртебесі» әдісінен алыңыз (әдетте бірнеше секундтан кейін дайын болады).

Аутентификация

Әр сұраныста мектеп кілті бар X-School-Key тақырыбы болуы тиіс:

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

• Кілт кабинетте жасалады: «Интеграциялар» → «Мектеп API». Пішімі — cs_live_…, бір рет көрсетіледі.
• Мектепке 3 белсенді кілтке дейін беріледі. Кез келген кілтті сол карточкада қайтарып алуға болады; оны қолданатын интеграциялар жұмысын тоқтатады.
• Кілтті серверіңізде сақтаңыз. Оны мобильді қосымшаларға, браузер кодына және ашық репозиторийлерге орналастырмаңыз.
• Мерзім міндетті емес: кілтті шығарғанда «дейін жарамды» күнін көрсетуге болады (осы күнді қоса). Одан кейін кілт 401 key_expired қайтарады — жаңасын шығарыңыз.
• Мектептің тарифі аяқталғанда оның барлық кілттері автоматты түрде және біржола қайтарып алынады; тарифті ұзартқаннан кейін жаңа кілт шығарыңыз. Қайтарып алынған кілт 401 bad_key алады.
• Кілт берілмесе, қате болса немесе қайтарып алынса — 401 жауабы келеді:

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

Кілт дұрыс, бірақ мектеп тарифі API-ге қолжетімділік бермесе — 403 tariff_not_allowed. «Мектеп API» карточкасында бүгінгі кілт қолданысы мен соңғы қателер көрінеді.

Әдістер

Төмендегі мысалдарда «Жылдам бастау» бөліміндегі $BASE және $KEY айнымалылары қолданылады. Жолдар негізгі URL — 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
    }
  }
]

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
}

Оқушыға арналған кіру сілтемесі

Сіздің сервис оқушыға бір реттік сілтеме бере алады: ол құпиясөзсіз Courstore-дағы мектебіңіздің кабинетін ашады. Сілтемедегі токен — 32 кездейсоқ байт, бізде тек хеш сақталады, бірінші қолданудан кейін сілтеме жарамсыз болады.

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);
});

Вебхуктар

Вебхуктар жазылулар мен қолжетімділік өзгерістері туралы жүйеңізге API-ді сұрамай-ақ бірден хабарлайды: Courstore сіздің мекенжайыңызға өзі POST жібереді.

{
  "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

Идемпотенттілік

POST /enrollments әдісі Idempotency-Key тақырыбын талап етеді — операцияның бірегей кілті, мысалы CRM-дегі тапсырыс нөмірі (128 таңбаға дейін: әріптер, цифрлар, . _ : -). Ол сұранысты қайталауды қауіпсіз етеді: тайм-аутқа байланысты жауап жоғалса, сұранысты сол кілтпен қайталаңыз — студент екі рет қабылданбайды.

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

Мұны қайта сатып алумен шатастырмаңыз: студент курсқа қабылданып қойған болса және сіз жаңа операция жіберсеңіз (басқа Idempotency-Key), қолжетімділік ұзартылады — «Қолжетімділік мерзімі» бөлімін қараңыз.

Қолжетімділік мерзімі

Қолжетімділік мерзімі былай анықталады:

• Сұраныста access нысаны берілсе, мерзім содан алынады: mode = days (amount 1-ден 3650-ге дейін) немесе months (amount 1-ден 120-ға дейін).
• access берілмесе, мерзім курс баптауларынан алынады. Оларды GET /courses жауабындағы access өрісінен көруге болады: mode = days / months және amount, не болмаса unlimited (мерзімсіз қолжетімділік, amount = null).

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

Жауаптар мен қабылдау мәртебесінде: lastDay — қолжетімділіктің соңғы күні, expireDate — қолжетімділікті жабу шекарасы; null — мерзімсіз қолжетімділік немесе күні әлі белгісіз.

Қайта сатып алу. Студент осы курсқа бұрын қабылданған болса, қолжетімділік бірден ұзартылады: есеп екі күннің үлкенінен басталады — бүгіннен немесе қолжетімділіктің ағымдағы аяқталуынан. Жауап — 200, status: done (кезексіз).

Студентке хабарландыру

API арқылы қабылдау кабинеттен қолмен қабылдаумен бірдей кезек арқылы өтеді. Студент сол хабарламаларды алады: WhatsApp / WABA / Telegram / пошта.

• notify параметрі (әдепкі бойынша true); false мәні осы қабылдау үшін хабарландыруларды өшіреді.
• Қайта сатып алғанда (ұзарту) студент Telegram-да хабарландыру алады — кабинеттегі «Қолжетімділікті ұзарту» сияқты.
• Қабылдау мәртебесінде notified: true хабарландыру жіберуге қойылғанын білдіреді. WhatsApp/Telegram-ға жеткізуді сервис растамайды.

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

Лимиттер

Шектеулер платформаны және студенттеріңізді интеграциядағы кездейсоқ циклдерден қорғайды.

Сұраныс лимиті асып кетсе, жауапта Retry-After тақырыбы болады — қайталауға дейінгі секунд саны. Бүгінгі қолданыс кабинеттегі «Мектеп API» карточкасында көрінеді.

Қателер

Барлық қателер код пен сипаттамасы бар JSON түрінде келеді:

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

HTTP-мәртебеге және error өрісіне (машиналық код) сүйеніңіз; message мәтіні журналдарға арналған.

failed мәртебесіндегі қабылдау үшін error өрісінде not_confirmed болады: 15 минут ішінде қабылдау расталмады.

Құпиялылық

API тек сіздің мектебіңіздің деректерін көрсетеді.

• POST /students жауабындағы created: true студент сіздің мектебіңізде әлі болмағанын білдіреді — оның аккаунты платформада басқа мектепте бар болса да. Сіздің мектебіңіз үшін байланыс жасалады, бөтен деректер ашылмайды.
• created: false — студент сіздің мектебіңізде бұрыннан оқиды. Бар студенттің аты мен поштасы қайта жазылмайды.
• Мектебіңізбен байланысы жоқ студент үшін қолжетімділікті тексеру жоқ студентпен бірдей жауап береді: active: false.
• GET /courses тек кілт иесі мектебінің курстарын қайтарады; бөтен курс 404 course_not_found жауабын береді.