Asosiy qismga oʻtish
API hujjati API kalitini olish

Integratsiya · 4-bob

Autentifikatsiya

Backendingiz maxfiy API kalit bilan autentifikatsiya qiladi; foydalanuvchining brauzeri yoki ilovasi esa faqat qisqa muddatli sessiya tokenini oladi.

3 daqiqa oʻqish

API kalitlar

Muhit Prefiks Misol
Sinov sk_test_ sk_test_i2fhPNWPG4cTmi1qCDVthAD7uTG6z6hf5lrHwddg
Ishchi sk_live_ sk_live_sFeAQm0nrtHEOkc483XcnWDSvOpNK7CZ0ptBI0ij

Kalit — prefiks va undan keyingi 40 ta tasodifiy harf va raqam. Muhitni kalit belgilaydi: sinov kaliti faqat sinov maʼlumotlarini, ishchi kalit faqat ishchi maʼlumotlarni koʻradi.

  • Kalitlarni panelda API kalitlari → Kalit yaratish orqali yarating. Muhitni tanlang va kalitga nom bering (masalan, uni ishlatadigan xizmat nomi). Kalitlarni faqat hisob egasi va adminlar boshqara oladi.
  • Toʻliq kalit faqat bir marta, yaratilgan zahoti koʻrsatiladi. Biz faqat uning xeshini saqlaymiz; keyinchalik panel kalitlarni farqlash uchun faqat birinchi belgilarini koʻrsatadi. Kalitni yoʻqotsangiz, yangisini yarating.
  • Ishchi kalitlarni faqat biznesingiz tasdiqlangandan keyin yaratish mumkin — Sinov va ishchi rejim bobiga qarang.
  • Bir vaqtda bir nechta faol kalitingiz boʻlishi mumkin, masalan har bir xizmat uchun bittadan.
Muhim

Maxfiy kalitni hech qachon brauzerga, mobil ilovaga, WordPress mavzusiga yoki ochiq repozitoriyga qoʻymang. Kalitga ega boʻlgan har kim hisobingizda arizachi yarata oladi va hujjat maʼlumotlarini oʻqiy oladi.

Kalitni yuborish

Kalitni https://kyc.goxost.net/api/v1 ga har bir soʻrovning Authorization sarlavhasida yuboring:

curl https://kyc.goxost.net/api/v1/usage \
  -H "Authorization: Bearer $KYC_SECRET_KEY"
$kyc = new GuzzleHttp\Client([
    'base_uri' => 'https://kyc.goxost.net/api/v1/',
    'headers'  => ['Authorization' => 'Bearer ' . getenv('KYC_SECRET_KEY')],
]);
$usage = json_decode($kyc->get('usage')->getBody(), true);
const usage = await fetch('https://kyc.goxost.net/api/v1/usage', {
  headers: { Authorization: `Bearer ${process.env.KYC_SECRET_KEY}` },
}).then((r) => r.json());
usage = requests.get(
    "https://kyc.goxost.net/api/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['KYC_SECRET_KEY']}"},
).json()
Muammo Javob
Kalit yoʻq, notanish yoki bekor qilingan 401 unauthenticated
Hisob bloklangan yoki faol emas 403 forbidden
Ishchi kalit, biznes hali tasdiqlanmagan 403 tenant_not_verified
ID boshqa hisob yoki muhitga tegishli 404 not_found

Kalit talab qilmaydigan yagona endpoint — ochiq hujjatlar katalogi, GET /documents/catalog.

Kalitlarni almashtirish va bekor qilish

Kalitni toʻxtalishlarsiz almashtirish uchun:

  1. Panelda yangi kalit yarating.
  2. Uni serverlaringizga joylang.
  3. Eski kalit endi ishlatilmayotganini tekshiring, soʻng uning yonidagi Bekor qilish tugmasini bosing.

Bekor qilingan kalit API da darhol ishlamay qoladi. Direct API kalit tekshiruvini qisqa vaqt keshlaydi, shuning uchun u yerda bekor qilingan kalit yana 60 soniyagacha qabul qilinishi mumkin. Kalit sizib chiqqan boʻlishi mumkin boʻlsa, uni darhol bekor qiling va yangisini yarating.

Brauzer va ilova uchun sessiya tokenlari

Brauzer yoki mobil ilovaga maxfiy kalitingiz hech qachon kerak emas. Backendingiz sessiya yaratganda (POST /applicants/{id}/sessions) ikkita qiymat oladi:

Qiymat Nima uchun
url Hosted senariy: foydalanuvchini yoʻnaltiring, havolani yuboring yoki QR kod qilib koʻrsating
token SDK lar: uni kyc.js yoki Flutter SDK ga bering

Ikkalasi ham bitta arizachining bitta sessiyasiga tegishli va u bilan birga muddati tugaydi (60–1800 soniya, sukut boʻyicha 30 daqiqa). Ular /api/v1 ni chaqira olmaydi va boshqa arizachilarni koʻrmaydi. SDK lar tokenni tekshiruv xizmatiga Authorization: Session <token> koʻrinishida oʻzlari yuboradi — bu endpointlarni oʻzingiz chaqirishingiz shart emas.

Eslatma

SDK brauzer yoki ilovada xabar qiladigan natija faqat foydalanuvchi tajribasi uchun. Yakuniy qarorni backendingizda webhook yoki GET /verifications/{id} dan oling.

Idempotentlik kalitlari

Tarmoq xatolari boʻlib turadi. Yozuvchi soʻrovni xavfsiz takrorlash uchun POST, PATCH va DELETE soʻrovlari bilan Idempotency-Key sarlavhasini yuboring:

curl https://kyc.goxost.net/api/v1/applicants \
  -H "Authorization: Bearer $KYC_SECRET_KEY" \
  -H "Idempotency-Key: 3f1c9a7e-2b4d-4e8a-9c61-5d0f7b2a8e14" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user-8812"}'
  • Kalit A–Z a–z 0–9 _ - belgilaridan iborat 8–64 belgi. UUID yaxshi mos keladi. Notoʻgʻri format 400 bad_request qaytaradi.
  • 24 soat davomida bir xil kalit va bir xil soʻrov saqlangan javobni Idempotent-Replayed: true sarlavhasi bilan qaytaradi. Hech narsa ikki marta yaratilmaydi.
  • Bir xil kalit boshqa tana bilan kelsa, 409 idempotency_conflict qaytadi.
  • Shu kalitli birinchi soʻrov hali bajarilayotgan boʻlsa, 409 conflict olasiz — kuting va takrorlang.
  • 5xx javoblar saqlanmaydi, shuning uchun server xatosidan keyingi takror soʻrovni qaytadan bajaradi.
  • Kalitlar API kalitingiz doirasida amal qiladi. Har bir yangi amal uchun yangi kalit ishlating.

Soʻrov limitlari

Har bir API kalit daqiqasiga 600 ta soʻrov yubora oladi. Har bir javobda X-RateLimit-Limit va X-RateLimit-Remaining bor. Limitdan oshsa, Retry-After sarlavhasi (soniyada) bilan 429 rate_limited olasiz. Baʼzi endpointlarning qoʻshimcha limitlari bor — Xatolar bobiga qarang.