Сіздің үдерісіңіз.
Біздің API.
API жеке кабинеттегі сауалнамаларға, файлдарға, өтінімдерге және жарыстарға қолжетімділік береді. Әр сұрау дерек иесі және API кілтінің құқықтары бойынша шектеледі.
API кілтін құру ↗Postman, код генераторлары және басқа құралдар үшін OpenAPI 3.1 JSON спецификациясын жүктеңіз.
1. Кілтті құру және сақтау
Жеке кабинет → API қолжетімділігі → Кілт құру бөліміне өтіңіз. Интеграция атауын, мерзімін және ең аз қажетті құқықтарды көрсетіңіз. Токен бір рет қана көрсетіледі. Оны сервердегі орта айнымалысында сақтаңыз және ашық JavaScript ішіне салмаңыз.
Authorization: Bearer YOUR_TOKEN
Accept: application/jsonBearer сұрауларына CSRF қажет емес. Браузер сессиясы алдымен GET /api/v1/session шақырып, өзгеріс енгізетін сұрауларға X-CSRF-Token жіберуі керек. Бөгде сайттан браузерлік CORS әдепкіде жабық, сондықтан интеграция API-ды өз серверінен шақырады.
Тіркелу, құпиясөзді қалпына келтіру сұрауы және байланыс нысаны бір реттік CAPTCHA талап етеді. Сол сессияда GET /captcha?purpose=register|forgot|contact шақырып, data.image ішіндегі PNG суретін көрсетіңіз, содан кейін captcha_id және суреттегі бес таңбаны captcha_answer ретінде жіберіңіз. Код 10 минут және бір әрекет үшін жарамды; жаңа код алдыңғысын жарамсыз етеді.
2. Алғашқы сұрау
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://nw.fams.kz/api/v1/profiles{
"data": [{"id": 123, "kind": "athlete", "name": "Спортшының аты"}],
"meta": {},
"request_id": "сұрау нөмірі"
}3. Файл мен паспортты жүктеу
20 МБ-қа дейінгі JPG, PNG, WebP және PDF қабылданады. Файлдар жалпыға ашық бумадан тыс сақталады. Жауаптағы data.id мәнін сақтап, file_id немесе photo_id ретінде жіберіңіз.
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
-F "file=@passport.pdf" -F "purpose=identity" \
https://nw.fams.kz/api/v1/filescurl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"profile_id":123,"type":"passport","file_id":"FILE_UUID","number":"N1234567","country":"Kazakhstan","issued_at":"2025-01-15","expires_at":"2035-01-15"}' \
https://nw.fams.kz/api/v1/documentsidentity және passport жеке басты куәландыратын құжат талабына сай келеді. Басқа түрлер: driver, medical, consent, organization. Шетелдік паспорт нөмірінде әріптер болуы мүмкін, ЖСН міндетті емес.
Бас тарту себебі: review_note өрісі GET /profiles/{id} және GET /applications/{id} жауаптарында келеді. Мәртебе rejected немесе changes болса, оны пайдаланушыға көрсетіңіз. Әкімші құжатты қайтарғанда немесе қабылдамағанда 5–3000 таңбалық себепті міндетті түрде жазады.
Негізгі маршруттар
| /api/v1 кейінгі әдіс пен жол | Мақсаты | Құқық |
|---|---|---|
| GET /catalog?kind=service | Қызметтер мен тарифтер | Жалпыға ашық |
| GET /services/prices | Ағымдағы АЕК және барлық белсенді қызметтің теңгедегі нақты бағасы | applications:read |
| GET, POST /profiles | Сауалнамаларды алу немесе құру | profiles:read / profiles:write |
| GET /profiles/summary | Құжат, өтінім, сертификат және жарыс есептегіштері бар спортшылардың ықшам тізімі | profiles:read |
| GET /profiles/{id}/portfolio | Бір спортшының сауалнамасы, құжаттары, сертификаттары, өтінімдері және жарыстарға қатысуы | profiles:read, тек иесі |
| PATCH /profiles/{id} | Сауалнама деректерін немесе фотоны өзгерту | profiles:write |
| POST /profiles/{id}/submit | Сауалнаманы тексеруге жіберу | profiles:write |
| POST /documents | Сауалнамаға құжат тіркеу | profiles:write |
| GET, POST /files | Файлдарды алу немесе жүктеу | files:read / files:write |
| GET /applications | Өз өтінімдеріңізді алу | applications:read |
| POST /applications/quote | Серверде бағаны есептеу | applications:write |
| POST /applications | Өтінім жобасын құру | applications:write |
| POST /applications/{id}/submit | Өтінімді тексеріп жіберу | applications:write |
| POST /applications/{id}/pay | Қайта есептен шығарудан қорғалған баланстық төлем | wallet:write |
| GET /applications/{id}/certificate | Мақұлданған және төленген құжатты жүктеу | applications:read |
| PUT /applications/{id}/sharing | Халықаралық лицензия құжаттарын QR арқылы ашу немесе жабу | applications:write, тек иесі |
| GET /applications/{id}/qr | Мақұлданған және төленген халықаралық лицензия QR-ын жүктеу | applications:read |
| GET /event-registrations | Өз жарысқа қатысу өтінімдерін алу | applications:read |
| GET /events/{id}/registration-options | Жарысқа жарамды сертификаттар | applications:read |
| POST /events/{id}/register | Спортшының өтінімін беру; өтінім төлемсіз | applications:write |
| GET /events/{id}/registrations | Ұйымдастырушыға спортшы өтінімдерін алу | events:read |
| PATCH /events/{id}/registrations/{registration_id} | Мақұлдау, себеппен қайтару немесе бас тарту | events:write |
| GET /messenger | Тек рұқсат етілген диалогтар: әкімшілік және байланысты жарыстар | notifications:read |
| GET /messenger/{perspective}/registrations/{id} | Қатысу өтінімі бойынша диалог | notifications:read |
| POST /messenger/{perspective}/registrations/{id}/messages | Сервер анықтаған рұқсат етілген тарапқа хабарлама жіберу | notifications:write |
| GET, POST /events | Жарыстарды алу немесе жоба құру | events:read / events:write |
| GET /events/public/{id} | Жарияланған жарыс, құжаттама күйі және бекітілген нәтижелер кестесі | Жалпыға ашық |
| GET /events/public/{id}/documents/{regulations|results} | Бекітілген регламент немесе қорытынды хаттама; жүктеу үшін ?download=1 | Бекітілгеннен кейін жалпыға ашық |
| PATCH /events/{id} | Жарыс дерегін немесе кезең файлын өзгерту | events:write |
| GET, POST /events/{id}/participants | Қатысушыларды алу немесе сертификатпен қосу | events:read / events:write |
| PATCH, DELETE /events/{id}/participants/{application_id} | Нәтижені өзгерту немесе жіберуге дейін қатысушыны жою | events:write |
| GET /wallet | Баланс, шоттар және операциялар тарихы | wallet:read |
| GET /notifications | Хабарламалар | notifications:read |
| GET, POST, DELETE /telegram | Telegram-бот күйі, бір реттік сілтеме жасау немесе ажырату | Өзгерту үшін браузер сессиясы және CSRF |
| GET /verify/{token} | Жеке деректерсіз жалпы тексеру | Жалпыға ашық |
| GET /verify/{token}/documents | Иесі рұқсат берген жарамды халықаралық лицензия құжаттары | Рұқсат берілген QR арқылы жалпыға ашық |
Өтінімдер, сақтандыру және ақша
GET /services/prices — жүйеге кірген пайдаланушы немесе интеграция үшін ресми тарифтер тізімі. Жауапта ағымдағы АЕК mrp.amount_minor, әр қызмет коэффициенті services[].mrp, Қазақстан бағасы price_kz_minor және рұқсат етілген санаттар үшін ТМД-ның толық бағасы price_cis_minor беріледі. _minor өрістері бүтін тиынмен көрсетіледі. Интерфейсте осы мәндерді көрсетіңіз, бірақ өтінім құрылғанда сервер қайтарған соманы соңғы сома деп қабылдаңыз.
Telegram API-дегі сол тексеру ережелерін қолданады. Пайдаланушы оны Қауіпсіздік бетіндегі 10 минуттық бір реттік кодпен қосады; құпиясөз бен API кілті Telegram-ға жіберілмейді. Көлік webhook-ы тек Telegram үшін арналған және X-Telegram-Bot-Api-Secret-Token арқылы қорғалған. Серверді баптау docs/telegram-bot.md ішінде.
Ұлттық сертификатта сақтандыру үдерісі әрқашан бар. Жалғыз төлем — таңдалған санаттың сақтандыру жарнасы; бөлек сақтандыру қызметі немесе қосқыш жоқ. Бұрынғы формула сақталған: санат тарифі × АЕК, ал ТМД аумағы рұқсат етіліп таңдалса, санаттың ТМД үстемесі × АЕК қосылады. insurance_coverage_minor — сақтандыру төлемінің емес, қамту сомасының мәні. Жауап өрістерін сақтандыруды өшіру үшін қолданбаңыз.
Бағаны сервер есептеп, өтінімге сақтайды. Клиент есептеген бағаны жібермеңіз. _minor деп аяқталатын ақша өрістері бүтін тиынмен беріледі; шоттағы amount "15000.00" сияқты жол болуы керек. Таймауттан кейін шотты қайталағанда сол Idempotency-Key пен соманы қолданыңыз.
Ұйымдастырушының қадамдары
kind: "organizer"сауалнамасын құрып, деректерді толтырыңыз және мақұлдауды күтіңіз./eventsішінде жарыс жобасын құрыңыз./events/{id}/agreementжүктеп, қол қойыңыз; сканды жүктеп,agreementкезеңіне тіркеңіз.detailsкезеңін жіберіп,data.application_idарқылы берілген жарна өтінімін төлеңіз.- Мақұлданғаннан кейін
regulationsфайлын жіберіңіз. - Жарыстан кейін әр спортшыны
POST /events/{id}/participantsарқылы қосыңыз.certificateөрісіне сертификат нөмірін, тексеру кодын немесе толық QR сілтемесін беруге болады. Сервер спортшыны өзі анықтап, сертификаттың мақұлдануын, төлемін және жарыс күндеріндегі жарамдылығын тексереді.category,start_number,result_status,placeжәнеresultөрістерін толтырыңыз. - Қорытынды PDF тіркеп,
resultsкезеңін жіберіңіз. Тексеру кезінде қатысушылар тізімі жабылады.
Қателер, лимиттер және әкімші маршруттары
401 — кіру қатесі; 403 — құқық жеткіліксіз; 404 — жазба жоқ немесе басқа иеге тиесілі; 409 — мәртебе, баланс не идемпотенттік қайшылығы; 419 — CSRF; 422 — тексеру қатесі; 429 — сұрау лимиті; 503 — интеграция өшірілген. Қателерде error.code, error.message және кейде error.details болады. Қолдауға request_id беріңіз, API кілтін бермеңіз.
Тізім маршруттары 1–100 аралығындағы page және limit параметрлерін қабылдап, meta.total қайтарады. Күндер YYYY-MM-DD пішімінде, уақыт белдеуі — Қазақстан, UTC+5.
Әкімші маршруттарына әкімші рөлі және admin:read / admin:write қажет. GET /admin/athletes спортшылар сауалнамаларын береді және аты-жөні, ЖСН, телефон, қала, email немесе ID бойынша status, certificate (issued, not_issued, pending) және q сүзгілерін қолдайды. Жауапта сертификаттың берілу күйі, соңғы өтінім, нөмірі мен жарамдылық мерзімі, аккаунт иесі және құжаттар мен өтінімдер саны бар. CSV кестесі GET /admin/export?kind=athletes арқылы жүктеледі. Балансты қолмен түзету, кері жазба, құқық пен кілттерді өзгерту үшін браузер сессиясы мен құпиясөз растауы да керек. Банк callback-ы төлемді өздігінен растамайды; сервер шотты, соманы, валютаны және терминалды банкпен салыстырады.
PUT /admin/profiles/{id}/owner сауалнаманы басқа белсенді қатысушы аккаунтына ауыстырады. current_user_id, target_user_id, кемінде бес таңбалық себеп және әкімші құпиясөзін жіберіңіз. Байланысты құжаттар, өтінімдер, сертификаттар, ұйымдастырушы жарыстары, файлдар және жарыс чаттарының контексті бір транзакцияда көшеді. Берілген сертификат көшірмелері, төленген сомалар және бухгалтерлік өткізбелер өзгермейді. QR арқылы құжаттарға ашық қолжетімділік жаңа иесі келісім бергенге дейін жабылады. Екі иесіне де хабарлама жіберіліп, әрекет аудитке жазылады.
Ұлттық сертификаттар: үш тізім
GET /admin/national ұлттық сертификаттарды және ағымдағы әкімшінің бөлек review, insurance, print тізімдерін қайтарады. Сүзгілер: year, q, service_id, status, paid, insurance, print, page, limit.
POST /api/v1/admin/national/lists/insurance
{"operation":"add","ids":[123,124]}
POST /api/v1/admin/national/lists/insurance/export
{"ids":[123,124]}Басқа операциялар: remove, clear және жылмен бірге auto. Бір тізімде 200 жазбаға дейін болады. Сақтандыру мен баспаға мақұлдау және төлем керек. Экспорт HTTP 201 және data.file.download_url қайтарады. Сақтандыру XLSX, баспа document.xlsx, foto/, qr/ бар ZIP жасайды. Экспорт белгісі файлдың дайындалғанын ғана білдіреді; сайт деректерді үшінші тарапқа жібермейді және полис рәсімдемейді.
Сертификатты тексеру және QR құжаттарына келісім
GET /verify/{token} үшін HTTP 200 жазбаның табылғанын білдіреді; жарамдылықты тек data.valid растайды. Негізгі жауапта аты-жөні, скандар және ішкі ескертулер жоқ. Халықаралық лицензия иесі PUT /applications/{id}/sharing сұрауымен {"enabled":true,"confirmed":true} жіберіп қолжетімділікті ашады, {"enabled":false} арқылы жабады. Әкімші иесінің орнына келісім бере алмайды.
GET /verify/{token}/documents лицензия мақұлданған, төленген, қазір жарамды және рұқсат ашық болғанда ғана жұмыс істейді. Жауапта рұқсат етілген өрістер мен мақұлданған скан сілтемелері ғана болады; ЖСН, телефон, мекенжай, ішкі UUID және сақтау жолдары қайтарылмайды. Әр файл сілтемесі мәртебе мен келісімді қайта тексереді, сондықтан рұқсатты жабу бірден күшіне енеді.
Әкімші анкета немесе құжат деректерін PATCH /admin/records/{profile|document}/{id} сұрауымен, admin:write құқығымен және алдыңғы GET қайтарған дәл updated_at мәнімен түзетеді. Тексеру мәртебесі мен жүктелген скан сақталады, иесіне хабарлама жіберіледі, өзгерген өрістер аудитке жазылады. Ескірген нұсқа 409 қайтарады. Белсенді өтінімге тіркелген құжаттың түрін өзгертуге болмайды, ал басқа деректерін түзетуге болады. Бұрын берілген сертификаттың бекітілген көшірмесі өзгермейді.