Qachon ishlatiladi
Koʻp integratsiyalar uchun tekshiruv jarayoni toʻgʻri keladi: hosted sahifa, kyc.js yoki Flutter SDK suratga oladi, shaxs ishtirokini toʻliq tekshiradi, natijani saqlaydi, webhook yuboradi va dalolatnoma beradi. Direct API dan faqat rasmlarni oʻzingiz olayotgan va alohida tekshiruvlar kerak boʻlgandagina foydalaning.
| Tekshiruv jarayoni | Direct API | |
|---|---|---|
| Kim suratga oladi | GOXOST KYC sahifasi yoki SDK | Sizning ilovangiz yoki saytingiz |
| Shaxs ishtirokini tekshirish | Toʻliq, selfi bosqichida | Soddalashtirilgan, bitta rasm boʻyicha |
| Arizachi, tekshiruv, tarix | Bor | Yoʻq — hech narsa yaratilmaydi |
| Saqlanadigan maʼlumot | Saqlash sozlamalaringizga koʻra | Hech narsa; maʼlumot faqat javobda |
| Webhooklar, koʻrib chiqish navbati, dalolatnoma | Bor | Yoʻq |
| Sanksiyalar boʻyicha tekshirish | Senariy sozlamasi | Alohida chaqiruv: POST /aml/screen |
Direct API chaqiruvlari maxfiy kalitingizdan foydalanadi. Ularni faqat serveringizdan chaqiring — hech qachon brauzerdan yoki mobil ilovadan emas. Ilovangiz rasmlarni serveringizga yuboradi, serveringiz esa Direct API ni chaqiradi.
Asosiy URL va autentifikatsiya
Direct API soʻrovlari /api/v1 ga emas, toʻgʻridan-toʻgʻri tekshiruv xizmatiga boradi. Uning manzilini GET /usage dagi core_url dan oling va sozlamalaringizda saqlang:
curl https://kyc.goxost.net/api/v1/usage -H "Authorization: Bearer sk_test_…"
{ "period": "2026-11", "plan": "free", "limit": 100,
"live": { "verifications": 124, "aml_checks": 124, "direct_checks": 40 },
"sandbox": { "verifications": 51, "aml_checks": 12, "direct_checks": 7 },
"core_url": "https://kyc-core.9k.uz/v1" }
Autentifikatsiya sarlavhasi oʻsha: Authorization: Bearer sk_test_… yoki sk_live_…. Soʻrovlar multipart/form-data koʻrinishida yuboriladi.
Endpointlar
| Endpoint | Maydonlar | Qaytaradi |
|---|---|---|
POST {core_url}/checks/document |
front (fayl), back (fayl, ixtiyoriy), country (ISO alpha-3, ixtiyoriy), type (id_card, passport, residence_permit, ru_internal_passport, visa; ixtiyoriy), age_only (bool, ixtiyoriy), min_age (butun son, ixtiyoriy) |
document (type, country, data) yoki null, hamda checks |
POST {core_url}/checks/face-match |
image_a, image_b (fayllar) |
score, status, labels |
POST {core_url}/checks/liveness |
image (fayl) |
score, status, labels |
Fayllar: JPEG, PNG yoki WebP (mazmuniga qarab aniqlanadi; HEIC qabul qilinmaydi), har biri 15 MB gacha, butun soʻrov 32 MB gacha.
Chaqiruvlar ketma-ketligi
Oʻz interfeysingiz bilan odamni tekshirishning odatiy tartibi:
- Ilovangiz hujjatni (old tomoni, ID karta uchun orqa tomoni ham) va selfini suratga oladi hamda ularni oʻz serveringizga yuklaydi.
- Serveringiz
frontvabackbilanPOST /checks/documentni chaqiradi.document.data(ism, raqam, sanalar) vachecksholatlarini oʻqing. - Serveringiz hujjatdagi rasmni
image_a, selfiniimage_bqilibPOST /checks/face-matchni chaqiradi. - Xohlasangiz, soddalashtirilgan shaxs ishtirokini tekshirish uchun selfi bilan
POST /checks/livenessni chaqiring. - Xohlasangiz, ismni
POST /aml/screenbilan tekshiring. - Serveringiz holatlarni birlashtirib, oʻz qarorini chiqaradi va kerakli narsani saqlaydi — GOXOST KYC hech narsa saqlamaydi.
curl https://kyc-core.9k.uz/v1/checks/document \
-H "Authorization: Bearer sk_test_…" \
-F front=@passport.jpg \
-F type=passport
curl https://kyc-core.9k.uz/v1/checks/face-match \
-H "Authorization: Bearer sk_test_…" \
-F image_a=@passport.jpg \
-F image_b=@selfie.jpg
$coreUrl = getenv('KYC_CORE_URL'); // core_url from GET /usage
$client = new GuzzleHttp\Client();
$auth = ['Authorization' => 'Bearer ' . getenv('KYC_SECRET_KEY')];
$document = json_decode((string) $client->post("$coreUrl/checks/document", [
'headers' => $auth,
'multipart' => [
['name' => 'front', 'contents' => fopen('passport.jpg', 'r')],
['name' => 'type', 'contents' => 'passport'],
],
])->getBody(), true);
$face = json_decode((string) $client->post("$coreUrl/checks/face-match", [
'headers' => $auth,
'multipart' => [
['name' => 'image_a', 'contents' => fopen('passport.jpg', 'r')],
['name' => 'image_b', 'contents' => fopen('selfie.jpg', 'r')],
],
])->getBody(), true);
// Node.js 20+
import { openAsBlob } from 'node:fs';
const coreUrl = process.env.KYC_CORE_URL; // core_url from GET /usage
const auth = { Authorization: `Bearer ${process.env.KYC_SECRET_KEY}` };
const docForm = new FormData();
docForm.append('front', await openAsBlob('passport.jpg'), 'passport.jpg');
docForm.append('type', 'passport');
const document = await (await fetch(`${coreUrl}/checks/document`, { method: 'POST', headers: auth, body: docForm })).json();
const faceForm = new FormData();
faceForm.append('image_a', await openAsBlob('passport.jpg'), 'passport.jpg');
faceForm.append('image_b', await openAsBlob('selfie.jpg'), 'selfie.jpg');
const face = await (await fetch(`${coreUrl}/checks/face-match`, { method: 'POST', headers: auth, body: faceForm })).json();
import os, requests
core_url = os.environ["KYC_CORE_URL"] # core_url from GET /usage
auth = {"Authorization": f"Bearer {os.environ['KYC_SECRET_KEY']}"}
with open("passport.jpg", "rb") as front:
document = requests.post(f"{core_url}/checks/document", headers=auth,
files={"front": front}, data={"type": "passport"}).json()
with open("passport.jpg", "rb") as a, open("selfie.jpg", "rb") as b:
face = requests.post(f"{core_url}/checks/face-match", headers=auth,
files={"image_a": a, "image_b": b}).json()
/checks/document javobi:
{
"document": {
"type": "passport",
"country": "UTO",
"data": {
"first_name": "ANNA MARIA",
"last_name": "ERIKSSON",
"full_name": "ERIKSSON ANNA MARIA",
"birth_date": "1992-08-12",
"number": "L898902C3",
"expiry_date": "2032-04-15",
"age": 34,
"is_expired": false,
"fields": { "…": "…" },
"mrz": { "…": "…" }
}
},
"checks": [
{ "name": "document", "status": "pass", "score": 1.0, "labels": [], "ms": 410 }
]
}
/checks/face-match va /checks/liveness javobi:
{ "score": 0.93, "status": "pass", "labels": [] }
document.data ning toʻliq sxemasi GET /verifications/{id} dagi bilan bir xil. status — pass, warn yoki fail; labels — xatolar va belgilar bobidagi sabab kodlari, masalan FACE_MATCH_UNCERTAIN, FACE_MISMATCH, FACE_NOT_FOUND, LIVENESS_UNCERTAIN, DOC_EXPIRED.
Qoidalar va limitlar
- Faqat soddalashtirilgan shaxs ishtirokini tekshirish. Toʻliq tekshiruv uchun hosted senariy yoki SDK dagi selfi bosqichi kerak.
/checks/livenessbitta rasm bilan ishlaydi: ishonchsiz natijawarn+LIVENESS_UNCERTAINberadi, oʻz-oʻzidan hech qachon qatʼiyfailbermaydi. Toʻliq tekshiruv kerak boʻlsa, tekshiruv jarayonidan foydalaning. - Hujjat sozlamalari.
country/typeberilsa, faqat shular qabul qilinadi (boshqalari →DOC_NOT_SUPPORTED). ID karta uchuntype=id_cardnibackbilan yuboring; ikkala tomon yuborilsa, ularning mosligi tekshiriladi (maʼlumotlar mos kelmasaDOC_DATA_MISMATCH, tomonlarni bitta hujjat deb tasdiqlab boʻlmasaDOC_FACE_UNBOUND). - Faqat yosh.
age_only=trueboʻlsadocument.data = nullqaytadi vadetails.age_overbilanagetekshiruvi qoʻshiladi.min_agestandart 18, ruxsat etilgani 18–30. - Hujjat haqiqiyligini tekshirish.
documenttekshiruvi oʻtsa, har bir tomon haqiqiylikka ham tekshiriladi. Shubha boʻlsawarnva tegishli belgi qaytadi (DOC_SCREEN_RECAPTURE,DOC_PRINTED_COPY,DOC_PHOTO_TAMPERED,DOC_TEMPLATE_MISMATCH). - Rasm oʻlchami. Hujjat rasmlari 52 MP gacha,
/checks/livenessuchun selfi rasmi 13 MP gacha, har bir tomoni 12 000 px gacha, uzun tomoni qisqasidan koʻpi bilan 10 barobar (422 image_too_large). - Soʻrov limitlari. Bitta IP dan daqiqasiga 120 ta va bitta kalit muhitidan daqiqasiga 60 ta soʻrov (
429 rate_limited). - Hisob. Har bir muvaffaqiyatli (
200) chaqiruv tekshiruvlardan alohida bittadirect_checksbirligi sifatida hisoblanadi. Ishchi rejimda oylik limit tugagach →429 plan_limit_reached. Xatolar hisoblanmaydi. - Sinov rejimi (
sk_test_…): haqiqiy tekshiruv yoʻq; har bir chaqiruv soxtapass(ball 0.99) va sintetik namunaviy hujjat «ERIKSSON ANNA MARIA» ni qaytaradi. Cheklanmagan, lekinGET /usageda hisoblanadi. Idempotency-Keyishlatilmaydi — chaqiruvlar holat saqlamaydi.
Xatolar
Xatolar { "error": { "code": "…", "message": "…" } } qobigʻida keladi.
| HTTP | code |
Nima qilish kerak |
|---|---|---|
| 400 | validation_failed |
Maydon yoʻq yoki notoʻgʻri (masalan, min_age oraliqdan tashqarida) |
| 400 | invalid_file |
JPEG, PNG yoki WebP rasm emas |
| 401 | unauthenticated |
Kalit yoʻq yoki yaroqsiz |
| 403 | forbidden |
Hisob bloklangan |
| 413 | file_too_large |
Soʻrov 32 MB dan katta |
| 422 | image_too_large |
Rasm oʻlchami yoki tomonlar nisbati limitdan oshgan — yuborishdan oldin kichraytiring |
| 429 | rate_limited |
Soʻrovlar juda koʻp — sekinlashing va keyinroq qayta urinib koʻring |
| 429 | plan_limit_reached |
Ishchi rejimning oylik limiti tugadi |
| 503 | auth_unavailable |
Kalitni hozir tekshirib boʻlmadi — oraliqni oshirib qayta urinib koʻring |
| 503 | core_unavailable |
Tekshiruv xizmati vaqtincha ishlamayapti — oraliqni oshirib qayta urinib koʻring |
Bekor qilingan kalit yoki bloklangan hisob taxminan bir daqiqa ichida (ishchi kalitlar uchun 10 soniyada) ishlashdan toʻxtaydi.