Asosiy qismga oʻtish
API hujjati API kalitini olish

Integratsiya · 8-bob

Direct API

Rasmlarni oʻz serveringizdan yuboring va tekshiruv natijasini shu javobning oʻzida oling. Bu oʻz suratga olish interfeysi bor va faqat tekshiruvlarning oʻzi kerak boʻlgan bizneslar uchun.

5 daqiqa oʻqish

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
Muhim

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:

  1. Ilovangiz hujjatni (old tomoni, ID karta uchun orqa tomoni ham) va selfini suratga oladi hamda ularni oʻz serveringizga yuklaydi.
  2. Serveringiz front va back bilan POST /checks/document ni chaqiradi. document.data (ism, raqam, sanalar) va checks holatlarini oʻqing.
  3. Serveringiz hujjatdagi rasmni image_a, selfini image_b qilib POST /checks/face-match ni chaqiradi.
  4. Xohlasangiz, soddalashtirilgan shaxs ishtirokini tekshirish uchun selfi bilan POST /checks/liveness ni chaqiring.
  5. Xohlasangiz, ismni POST /aml/screen bilan tekshiring.
  6. 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/liveness bitta rasm bilan ishlaydi: ishonchsiz natija warn + LIVENESS_UNCERTAIN beradi, oʻz-oʻzidan hech qachon qatʼiy fail bermaydi. Toʻliq tekshiruv kerak boʻlsa, tekshiruv jarayonidan foydalaning.
  • Hujjat sozlamalari. country/type berilsa, faqat shular qabul qilinadi (boshqalari → DOC_NOT_SUPPORTED). ID karta uchun type=id_card ni back bilan yuboring; ikkala tomon yuborilsa, ularning mosligi tekshiriladi (maʼlumotlar mos kelmasa DOC_DATA_MISMATCH, tomonlarni bitta hujjat deb tasdiqlab boʻlmasa DOC_FACE_UNBOUND).
  • Faqat yosh. age_only=true boʻlsa document.data = null qaytadi va details.age_over bilan age tekshiruvi qoʻshiladi. min_age standart 18, ruxsat etilgani 18–30.
  • Hujjat haqiqiyligini tekshirish. document tekshiruvi oʻtsa, har bir tomon haqiqiylikka ham tekshiriladi. Shubha boʻlsa warn va tegishli belgi qaytadi (DOC_SCREEN_RECAPTURE, DOC_PRINTED_COPY, DOC_PHOTO_TAMPERED, DOC_TEMPLATE_MISMATCH).
  • Rasm oʻlchami. Hujjat rasmlari 52 MP gacha, /checks/liveness uchun 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 bitta direct_checks birligi sifatida hisoblanadi. Ishchi rejimda oylik limit tugagach → 429 plan_limit_reached. Xatolar hisoblanmaydi.
  • Sinov rejimi (sk_test_…): haqiqiy tekshiruv yoʻq; har bir chaqiruv soxta pass (ball 0.99) va sintetik namunaviy hujjat «ERIKSSON ANNA MARIA» ni qaytaradi. Cheklanmagan, lekin GET /usage da hisoblanadi.
  • Idempotency-Key ishlatilmaydi — 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.