Сіздің үдерісіңіз.
Біздің 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://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://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://fams.kz/api/v1/documentsidentity және passport жеке басты куәландыратын құжат талабына сай келеді. Басқа түрлер: driver, medical, consent, organization, insurance_policy, naf_permission, foreign_naf_license. Шетелдік паспорт нөмірінде әріптер болуы мүмкін, ЖСН міндетті емес.
Әр құжат бойынша бөлек шешім: review_note өрісі GET /profiles/{id} және GET /applications/{id} жауаптарында келеді. Мәртебе changes, cancelled немесе expired болса, себебін пайдаланушыға көрсетіңіз. Әкімші POST /admin/review сұрауына kind: "document", құжаттың id мәнін және approve, changes немесе cancel шешімін жібереді. Түзетуге қайтару мен күшін жою үшін 5–3000 таңбалық себеп міндетті. Шешім тек көрсетілген құжатты өзгертеді.
Мерзімнің аяқталуы: expires_at ағымдағы күннен бұрын болса, API құжатқа status: "expired" мәртебесін сақтайды. Оған байланыстырылған белсенді FAMS сертификатының немесе құжатының өтінімдері status: "changes" күйіне өтеді; себепте мерзімі өткен құжат пен байланысты өтінімдердің ID-лері көрсетіледі. Сертификат пен QR бірден жарамсыз болады, ал бұрынғы төлем өтінімде сақталады. Жаңа мақұлданған құжатты PATCH /applications/{id} арқылы тіркеп, өтінімді қайта жіберіңіз; талаптары орындалған төленген ұлттық сертификат екінші төлемсіз автоматты түрде мақұлданады.
Негізгі маршруттар
| /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 |
| DELETE /profiles/{id} | Сауалнама да, фотосурет те ешқашан мақұлданбаған кезде иесінің сауалнамасын жою | profiles:write |
| POST /profiles/{id}/submit | Сауалнаманы тексеруге жіберу | profiles:write |
| GET /profiles/{id}/vehicles | Ескі сауалнамалардағы көлік жазбаларын тек оқу; қосу және өзгерту өшірілген | profiles:read |
| 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}/registrations/batch | 100 пилотқа дейін бөлек өтінімдерді және әр өтінімнің көлік деректерін сақтау немесе жіберу | 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 | Бекітілгеннен кейін жалпыға ашық |
| GET /events/public/{id}/documents/additional/{document_id} | Жарыстың қосымша құжатын ашу немесе жүктеу | Жарияланған жарыс үшін жалпыға ашық |
| PATCH /events/{id} | Жарыс дерегін немесе кезең файлын өзгерту | events:write |
| GET, POST /events/{id}/additional-documents | Бюллетеньдерді, сызбаларды, кестелерді және басқа жарыс құжаттарын алу немесе қосу | events:read / events:write, жарыс иесі |
| DELETE /events/{id}/additional-documents/{document_id} | Жарыстың бір қосымша құжатын жою | events:write, жарыс иесі |
| GET, POST /events/{id}/participants | Қатысушыларды алу немесе сертификатпен қосу | events:read / events:write |
| PATCH, DELETE /events/{id}/participants/{application_id} | Нәтижені өзгерту немесе жіберуге дейін қатысушыны жою | events:write |
| GET /contract-templates | Белсенді келісім үлгілері және айнымалылар | events:read |
| GET, POST /contracts | Келісімдерді алу немесе 3-нұсқа PDF-ін бірден жасау | events:read / events:write |
| GET /contracts/{id}/{preview|original|pdf} | Қол қойылмаған алдын ала нұсқа, өзгермейтін түпнұсқа немесе үйлесімді PDF | events:read, иесі немесе әкімші |
| POST /contracts/{id}/request-confirmation | FAMS қолтаңбасы мен мөрі бар PDF жасауды қайталау немесе қалпына келтіру | events:write, жарыс иесі |
| POST /contracts/{id}/{replace|cancel} | Жаңа нұсқа жасау немесе себеппен күшін жою | events:write |
| POST /contracts/{id}/scan | Ұйымдастырушы қол қойған толық PDF-ті FAMS тексеруіне жүктеу | events:write |
| GET /contracts/verify/{token} | Келісім күйін, қол қоюшыны және SHA-256 хэшін ашық тексеру | Жалпыға ашық |
| GET /contracts/verify/{token}/pdf | FAMS растаған ұйымдастырушы сканын жүктеу | FAMS растағаннан кейін ашық |
| GET, PUT /admin/fams-signing | Жаңа келісімдерге арналған FAMS бірыңғай қолтаңбасы мен мөрін баптау | admin:read / admin:write |
| POST /admin/contracts/{id}/review | Ұйымдастырушы қол қойған сканды растау немесе қабылдамау | admin: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 өрістері бүтін тиынмен көрсетіледі. Интерфейсте осы мәндерді көрсетіңіз, бірақ өтінім құрылғанда сервер қайтарған соманы соңғы сома деп қабылдаңыз.
Ұлттық санаттар мына ретпен қайтарылады: D, D Жасөспірім, D Картинг, B Мото, B Жасөспірім Мото, E, L, K Мото (ШКГ). D Картинг санаты 18 жастан асқан және сауалнамасында жүргізуші куәлігі жоқ спортшыларға ғана қолжетімді. Сервер бұл талапты бағаны есептеу, өтінімді құру және жіберу кезінде тексереді; талап орындалмаса 422 service_eligibility қайтарады.
Telegram API-дегі сол тексеру ережелерін қолданады. Пайдаланушы оны Қауіпсіздік бетіндегі 10 минуттық бір реттік кодпен қосады; құпиясөз бен API кілті Telegram-ға жіберілмейді. Көлік webhook-ы тек Telegram үшін арналған және X-Telegram-Bot-Api-Secret-Token арқылы қорғалған. Серверді баптау docs/telegram-bot.md ішінде.
Ұлттық сертификатта сақтандыру үдерісі әрқашан бар. Жалғыз төлем — таңдалған санаттың сақтандыру жарнасы; бөлек сақтандыру қызметі немесе қосқыш жоқ. Бұрынғы формула сақталған: санат тарифі × АЕК, ал ТМД аумағы рұқсат етіліп таңдалса, санаттың ТМД үстемесі × АЕК қосылады. insurance_coverage_minor — сақтандыру төлемінің емес, қамту сомасының мәні. Жауап өрістерін сақтандыруды өшіру үшін қолданбаңыз.
Бір спортшы сауалнамасы, қызмет/санат, таңдалған спорт/дисциплина және жыл үшін тек бір белсенді өтінімге рұқсат етіледі. Қайталанған POST /applications сұрауы 409 duplicate_application және бар өтінімнің error.details.application_id мәнін қайтарады; сол жазбаны PATCH, submit және pay арқылы жалғастырыңыз. Спортшы сауалнамасы, фотосы, барлық міндетті тіркелген құжаттары және төлемі мақұлданып немесе расталған сәтте ұлттық сертификат автоматты түрде мақұлданады. Соңғы талапты аяқтаған әрекеттің жауабында бірден status: "approved", нөмірі және жарамдылық күндері болады. Ұлттық және халықаралық сертификаттар өтінім берілген жылдың 31 желтоқсанында аяқталады; сервер valid_until мәнін өзі белгілеп, клиент жіберген кейінгі күнді елемейді.
Бағаны сервер есептеп, өтінімге сақтайды. Клиент есептеген бағаны жібермеңіз. _minor деп аяқталатын ақша өрістері бүтін тиынмен беріледі; шоттағы amount "15000.00" сияқты жол болуы керек. Таймауттан кейін шотты қайталағанда сол Idempotency-Key пен соманы қолданыңыз.
Ұйымдастырушы келісімін рәсімдеу
Жаңа келісімдер workflow_version: 3 нұсқасын қолданады. Әкімші FAMS тарапын PUT /admin/fams-signing арқылы бір рет баптайды. Мөлдір PNG/WebP қолтаңба мен мөрді POST /files арқылы purpose: signature және purpose: stamp деп жүктеңіз. Баптауда FAMS қол қоюшысының Т.А.Ә., лауазымы, жабық файл ID-лері, сурет координаттары және масштабы сақталады.
GET /admin/fams-signing FAMS-тың бірыңғай баптауын қайтарады. Бастапқы суреттердің ашық URL-ы жоқ және оларды тек әкімшілер оқи алады. Әр жасалған PDF өзгермейтін көшірмені сақтайды, сондықтан кейінгі баптау өзгерісі тек жаңа PDF-терге әсер етеді.
- Мақұлданған ұйымдастырушы сауалнамасы мен жарысты жасап,
POST /contractsорындаңыз. Сервер бірден нөмір мен QR береді, FAMS қолтаңбасы мен мөрін қояды және өзгермейтін PDF-ті сақтайды. Ұйымдастырушы тарапы бос қалады. GET /contracts/{id}/originalарқылы жүктеп, басып шығарып, ұйымдастырушы тарапына қолмен қол қойыңыз.- Барлық қол қойылған бетті бір PDF түрінде
POST /contracts/{id}/scanарқылы жүктеңіз. Мәртебеpendingболады. - FAMS
POST /admin/contracts/{id}/reviewсұрауынconfirmнемесеrejectшешімімен орындайды. Бас тарту себебі міндетті.
Тек FAMS растаған confirmed сканы valid: true береді. Ашық GET /contracts/verify/{token}/pdf дәл сол расталған сканды қайтарады. Расталғанға дейін QR келісімнің әлі жарамсыз екенін көрсетеді және сканды ашпайды. Күші жойылған және ауыстырылған нұсқалар мұрағат файлын сақтайды, бірақ әрқашан жарамсыз болып тексеріледі.
Аудит FAMS бірыңғай баптауын өзгерту, әр PDF-ке FAMS қолтаңбасы мен мөрін қолдану, жасау, жүктеу, скан жүктеу, тексеру, ауыстыру және күшін жою әрекеттерін орындаушы, уақыт, IP және хэштермен сақтайды.
FAMS үлгі айнымалылары: {{FAMS_SIGNATURE}}, {{FAMS_STAMP}}, {{FAMS_SIGNER_NAME}}, {{FAMS_SIGNER_POSITION}}, {{FAMS_SIGNED_AT}}, {{DOCUMENT_NUMBER}}, {{DOCUMENT_QR}}. Ұйымдастырушының қолтаңбасы мен мөріне арналған орын қолмен толтыру үшін бос қалуы тиіс.
Қателер, лимиттер және әкімші маршруттары
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 және сақтау жолдары қайтарылмайды. Әр файл сілтемесі мәртебе мен келісімді қайта тексереді, сондықтан рұқсатты жабу бірден күшіне енеді.
GET /admin/records/application/{id} өтінімге тіркелген сауалнама құжаттарын entity.documents ішінде, ал өтінімнің барлық файлдарын entity.attachments ішінде қайтарады. Халықаралық жарысқа рұқсатты тексергенде екі жинақты да қараңыз; әкімші кабинеті оларды қарау және жүктеу батырмалары бар бір тізімде көрсетеді.
Әкімші анкета немесе құжат деректерін PATCH /admin/records/{profile|document}/{id} сұрауымен, admin:write құқығымен және алдыңғы GET қайтарған дәл updated_at мәнімен түзетеді. Тексеру мәртебесі мен жүктелген скан сақталады, иесіне хабарлама жіберіледі, өзгерген өрістер аудитке жазылады. Ескірген нұсқа 409 қайтарады. Белсенді өтінімге тіркелген құжаттың түрін өзгертуге болмайды, ал басқа деректерін түзетуге болады. Бұрын берілген сертификаттың бекітілген көшірмесі өзгермейді.