API холболт

Багцуудын үнэ, бусад боломжийг Үнэ хуудаснаас харна уу.

Байгууллагын баталгаажсан эзэмшигч апп доторх API холболт хэсгээс түлхүүр үүсгэнэ. Нэр, эрх, шаардлагатай бол нэг хэлтэс, хүчинтэй хоногоо сонгоно. Анхны хугацаа 90 хоног, дээд хугацаа 365 хоног; нэг байгууллага 10 хүртэл идэвхтэй түлхүүртэй.

Нууц түлхүүрийг зөвхөн үүсгэх үед нэг удаа харуулна. Хуулж, холбох системийн серверийн нууц тохиргоонд хадгална. Браузерийн код, URL, нийтийн файл болон хүсэлтийн логт түлхүүрээ оруулахгүй.

Бүх хүсэлтэд дараах толгой хэрэгтэй. Доорх нь зөвхөн орлуулагч:

Authorization: Bearer <API_KEY>

Нэвтэрсэн браузерийн cookie нь API түлхүүрийг орлохгүй. Түлхүүр байгууллагыг тогтооно; URL эсвэл JSON-д өөр байгууллагын ID өгч хандахгүй.

view эрх бүх түлхүүрт орно. Pro багцад зөвхөн энэ эрх ажиллана. Нэмэлт эрхүүд:

Сертификат дахин олгоход сертификатын хоёр эрх хоёулаа шаардлагатай. Унших эрх нь оролцогчийн нэр, имэйл, утас зэрэг холбоо барих мэдээлэлд хандах эрхтэй. Зөвхөн шаардлагатай хүрээ, эрхийг сонгоно.

Түлхүүрт сонгосон хэлтсийн хүрээг хүсэлтээр өргөжүүлэхгүй. Түлхүүр үүсгэсэн гишүүний одоогийн эрх, хэлтэс, баталгаажуулалт, байгууллагын хүчинтэй багцыг хүсэлт бүрт дахин шалгана. Эрх, хэлтсийг солихдоо шинэ түлхүүр үүсгэж, хуучныг цуцална. Түлхүүр алдагдсан бол API холболт хэсгээс даруй цуцална.

Бүх зам үндсэн хаягийн араас залгана. {id} нь тухайн объектын UUID. Сургалтын хуваарийн dayId-г GET /sessions/{id}-ийн days жагсаалтаас авна.

Унших · view

Өөрчлөх · Organization, Enterprise

GET /api/v1/sessions?page=1&perPage=50
Authorization: Bearer <API_KEY>

Жагсаалтын хариу:

{
  "data": [],
  "pagination": { "page": 1, "perPage": 50, "total": 0, "pages": 1 }
}

Нэг объектын болон үйлдлийн хариу {"data": ...} хэлбэртэй. Огноо ISO 8601 UTC мөрөөр, хоосон утга null гэж ирнэ. Амжилттай үүсгэсэн объект 201, бусад амжилттай хүсэлт 200 төлөвтэй. Аль хэдийн байгаа бүртгэл эсвэл хүчинтэй сертификатыг буцаахад мөн 200 ирж болно.

Хуудас ба хугацааны шүүлтүүр

• page: 1-ээс эхлэх бүхэл тоо; анхны утга 1.
• perPage: 1–100; анхны утга 50.
• (page - 1) × perPage нь 100,000-аас ихгүй байна.
• from нь хамрах эхлэл, to нь хамруулахгүй төгсгөл. Хоёрыг хамт, цагийн бүстэй ISO 8601 утгаар өгнө, жишээ нь 2027-01-01T00:00:00Z. Эхлэл нь төгсгөлөөс өмнө, сонгосон цонх 366 хоногоос уртгүй байна.

Олон жилийн мэдээллийг хугацааны цонхуудаар хувааж татна. status шүүлтүүр:

Ирцийн жагсаалт зөвхөн хадгалсан мөрүүдийг өгнө; мөр байхгүйг шууд absent гэж тооцохгүй. Ирцэд status шүүлтүүр байхгүй. Давхардсан болон танихгүй query параметр, нэг объект унших болон өөрчлөх хүсэлтийн query параметрийг хүлээн авахгүй.

Бүх POST, PUT хүсэлт Content-Type: application/json толгой, JSON объект биетэй байна. Талбаргүй үйлдэлд ч хоосон биеийн оронд {} илгээнэ. Биеийн дээд хэмжээ 64 KiB. Танихгүй талбаруудыг хүлээн авахгүй.

POST /api/v1/sessions/<SESSION_UUID>/publish
Authorization: Bearer <API_KEY>
Content-Type: application/json

{}

Сургалт үүсгэх, засах

POST /sessions нь үргэлж ноорог үүсгэнэ. Дараа нь /publish үйлдлээр нийтэлнэ. PUT /sessions/{id} нь хэсэгчилсэн засвар биш: хадгалах бүх мэдээлэл, бүх өдрийн хуваарийг дахин илгээнэ. Шаардлагатай үндсэн талбарууд нь title, mode, capacity, days; сонголтот талбарыг орхивол анхны утга эсвэл null болж болно.

Үүсгэх болон засахад ашиглах бүрэн жишээ. Байгууллагынхаа өгөгдлөөр солино:

{
  "departmentId": null,
  "title": "Аюулгүй ажиллагааны сургалт",
  "description": "Ажилтнуудад зориулсан сургалт",
  "mode": "in_person",
  "location": "Төв байр, 201 тоот",
  "onlineUrl": null,
  "trainerName": "Багшийн нэр",
  "capacity": 30,
  "waitlistEnabled": true,
  "registrationDeadline": "2027-04-19T18:00:00+08:00",
  "visibility": "public",
  "days": [
    {
      "startsAt": "2027-04-20T09:00:00+08:00",
      "endsAt": "2027-04-20T17:00:00+08:00"
    }
  ],
  "certificateTemplateId": null,
  "feedbackFormId": null,
  "attendanceThresholdPercent": 80,
  "autoIssueCertificate": false,
  "requireFeedbackForCertificate": false,
  "durationHours": null,
  "isPaid": false,
  "priceAmount": null,
  "paymentDueAt": null,
  "lateWindowMin": 30
}

Хэлтэст хязгаарласан түлхүүрийн хувьд departmentId-г орхих эсвэл өөрийн хэлтсийг өгнө; null болон өөр хэлтсээр хүрээг өргөжүүлэхгүй. Одоо байгаа сургалтын хэлтсийг шилжүүлэхэд түлхүүр үүсгэсэн гишүүн эзэмшигч хэвээр байх шаардлагатай.

certificateTemplateId, attendanceThresholdPercent, autoIssueCertificate, requireFeedbackForCertificate дөрвийг өөрчлөхөд certificate.issue эрх хэрэгтэй. Энэ эрхгүй засвар нь хадгалсан дөрвөн тохиргоог хэвээр үлдээнэ; үүсгэхэд автомат олголтыг идэвхжүүлэхгүй. Эрхгүй түлхүүрээр эдгээр талбарыг орхино.

GET /sessions/{id} хариуг шууд PUT рүү илгээхгүй: id, status, startsAt, endsAt, counts, өдрийн id, dayIndex зэрэг зөвхөн унших талбарыг хасна. Нийтэлсэн сургалтын хуваарь/байршлыг өөрчлөхөд оролцогчдод ердийн мэдэгдэл очно.

Оролцогч бүртгэх

POST /sessions/{id}/registrations хүсэлтэд оролцогчийн мэдээллийг participant объект дотор илгээнэ. email, firstName, lastName заавал; бусад нь сонголтот:

{
  "participant": {
    "email": "participant@example.com",
    "firstName": "Нэр",
    "lastName": "Овог",
    "phone": "99112233",
    "employer": "Байгууллагын нэр",
    "position": "Албан тушаал"
  }
}

Бүртгэл нээлттэй, нийтлэгдсэн сургалтад бүртгэнэ. Суудал дүүрсэн үед хүлээлгийн жагсаалтын тохиргоо үйлчилнэ. Ижил имэйл байгууллага дотор нэг оролцогчийг заана; өөр нэрээр ашиглавал зөрчил болно. Байгаа бүртгэлийг буцаавал 200, шинээр бүртгэвэл 201 ирнэ. Баталгаажуулалт болон сануулгын ердийн мэдэгдлүүд үүснэ.

Бусад үйлдэл

reason нь 3–2000 тэмдэгт. Ирцийн status нь present, late, absent, excused утгатай; өдөр болон бүртгэл нэг сургалтынх байна. present, late ирсэнд тооцогдоно. Байгаа ирсэн цагийг хадгалж, анх гараар тэмдэглэхэд одоогийн цагийг хэрэглэнэ; absent, excused нь checkedInAt: null байна.

Зөвхөн хугацаа нь дууссан, нийтлэгдсэн эсвэл хаагдсан сургалтыг дуусгана. Сертификат олгоход баталгаажсан бүртгэл, ирц, үнэлгээ болон төлбөрийн одоогийн шаардлагууд үйлчилнэ; API эдгээрийг алгасах талбаргүй. Сертификат шинээр болон дахин олгоход 201, өмнө олгосон хүчинтэй сертификатыг буцаахад 200 ирнэ.

Сургалт үүсгэх, оролцогч бүртгэх, сертификат олгох, сертификат дахин олгох дөрвөн үйлдэлд Idempotency-Key заавал илгээнэ. 8–128 хэвлэгдэх ASCII тэмдэгттэй, эхлэл/төгсгөлдөө зайгүй утга хэрэглэнэ.

Idempotency-Key: hr-training-create-0001

Сүлжээ тасарсан эсвэл хариу тодорхойгүй бол ижил түлхүүр, арга, зам, JSON мэдээллээр дахин оролдоно. Ижил хүсэлт 24 цагийн дотор өмнөх амжилттай хариугаа буцааж, давхар бүртгэл/сертификат үүсгэхгүй. Түлхүүрийг өөр мэдээлэлд ашиглавал 409 ирнэ. 24 цаг өнгөрвөл шинэ үйлдэлд тооцогдож болох тул эхлээд үүссэн объектоо шалгана. Давтах үед одоогийн эрх, багц, хэлтсийг дахин шалгана.

Алдаа дараах тогтмол бүтэцтэй:

{
  "error": {
    "code": "forbidden",
    "message": "Танд энэ үйлдлийг хийх эрх байхгүй."
  }
}

Программын нөхцөлийг code болон HTTP төлөвөөр шалгана; message нь хүнд зориулсан тайлбар бөгөөд үг хэллэгээр нь шийдвэр гаргахгүй.

Нэг түлхүүрт минутанд 120 хүсэлт; өөрчлөх үйлдэлд нэмэлтээр нэг түлхүүрт 30, байгууллагад нийт 60 хүсэлтийн хязгаар үйлчилнэ. Нэвтрэхээс өмнөх IP шалгалт ч тусдаа хязгаартай. Тоолуур сервер дахин эхлэхэд шинэчлэгддэг тул үүнийг төлбөрийн хэрэглээний тоолуур гэж үзэхгүй. API хариуг Cache-Control: no-store гэж буцаана.

Төлбөр баталгаажуулах, багц/баг/хэлтэс удирдах, байгууллагын тохиргоо болон нийтлэг загвар өөрчлөхийг апп дотроос гүйцэтгэнэ. Нэргүй үнэлгээний хариулт, QR/PIN, ирцийн нууц код, төлбөрийн код, хувийн PDF файлыг API өгөхгүй. Оролцогчийн үндсэн мэдээлэл байгууллагын хэмжээнд хуваалцагддаг; сургалтын түүх, ирц, сертификат нь түлхүүрийн хүрээгээр хязгаарлагдана.

Асуулт байвал холбоо барих хуудсаар бидэнд хандана уу.