QR-kod orqali elektron imzo bilan imzolash (RS-IMZO / E-IMZO)

1. QR-kod orqali imzolash nima

QR-kod orqali imzolash foydalanuvchiga saytingizdagi kontentni RS-ID mobil ilovasida saqlangan elektron imzosi (RS-IMZO yoki E-IMZO) bilan imzolash imkonini beradi.

Backendingiz imzolanadigan kontent bilan QR-token yaratadi. Saytingiz QR-kodni ko'rsatadi; foydalanuvchi uni RS-ID mobil ilovasida skanerlaydi, kontentni ko'radi, imzo kalitini tanlaydi va imzolaydi. RS-ID imzoni tekshiradi, imzolangan ma'lumotlarni (PKCS#7) sizning callback_url manzilingizga yuboradi va QR-tokenni yakunlangan deb belgilaydi.

Saytingizda E-IMZO plaginlarini o'rnatish yoki imzo kalitlari bilan ishlash shart emas — imzolash foydalanuvchining telefonida amalga oshadi.

Foydalanish holatlari

Holat	Misol
Hujjatlarni imzolash	Foydalanuvchi saytingizda ko'rsatilgan kredit, ijara yoki xizmat ko'rsatish shartnomasini imzolaydi.
Bir nechta imzolovchi tomonidan kelishish	Hujjatni muayyan shaxslar yoki kompaniyalar (JSHSHIR yoki STIR bo'yicha) imzolashi kerak; hammasi imzolagach, QR yakunlanadi.
Elektron imzo bilan kirish	Saytingiz `sign_content` ga bir martalik tasodifiy satr qo'yadi; foydalanuvchi uni imzolaydi va imzo tekshirilgach, siz uni tizimga kiritasiz.
Amalni tasdiqlash	To'lov topshirig'i yoki arizani qayta ishlashdan oldin imzolash.

2. Atamalar

Atama	Kim / nima
Mijoz (Client)	RS-ID'ni integratsiya qilayotgan kompaniya (siz). RS-ID'da Web SDK mijozi sifatida ro'yxatdan o'tgan va `client_id` / `client_secret` olgan. Mijoz backendi va mijoz frontendini o'z ichiga oladi.
Foydalanuvchi	Imzolovchi inson — unda elektron imzo qo'shilgan RS-ID mobil ilovasi bor.
RS-ID mobil ilovasi	Foydalanuvchi telefonidagi RS-ID ilovasi. Foydalanuvchining elektron imzolarini saqlaydi va kontentni imzolaydi.
Server	RS-ID serveri: QR-tokenlar yaratadi, imzolarni tekshiradi va callback yuboradi.
QR-token	Bitta imzolash so'rovi, `qr_id` bilan aniqlanadi. Amal qilish muddati (`expire_time`) va holatiga ega.
RS-IMZO / E-IMZO	Elektron imzo turlari (`sign_method`).
Imzolovchi	Imzolashga ruxsat berilgan shaxs yoki kompaniya; JSHSHIR (14 ta raqam, jismoniy shaxs) yoki STIR (9 ta raqam, kompaniya) bo'yicha aniqlanadi.
PKCS#7	RS-ID sizning `callback_url` manzilingizga yuboradigan imzolangan ma'lumotlarning standart formati (CMS).

3. Qanday ishlaydi

Backendingiz avtorizatsiyadan o'tadi (7.1) va imzolanadigan kontent bilan QR-token yaratadi (7.3).

Saytingiz QR-kodni foydalanuvchiga ko'rsatadi.

Foydalanuvchi uni RS-ID mobil ilovasida skanerlaydi, kontentni o'qiydi va RS-IMZO yoki E-IMZO kaliti bilan imzolaydi (7.4).

RS-ID imzoni va imzolovchiga ruxsat berilganini tekshiradi.

RS-ID imzolangan ma'lumotlarni (PKCS#7) sizning callback_url manzilingizga yuboradi (7.5).

Backendingiz QR holatini COMPLETED yoki EXPIRED bo'lguncha tekshiradi (7.6 / 7.7).

4. Integratsiya sxemasi

5. Muhitlar

Muhit	API bazaviy URL	Havola (QR-kod ichida)
Stage (test)	`https://sdk.stage.rsid.uz/web/api`	`https://auth.stage.rsid.uz/{qr_id}`
Production	`https://sdk.rsid.uz/web/api`	`https://auth.rsid.uz/{qr_id}`

Stage va production uchun turli client_id / client_secret ishlatiladi. Stage'da yaratilgan QR-kodni faqat RS-ID ilovasining stage versiyasi skanerlay oladi.

6. Umumiy qoidalar

Javob formati

Barcha API javoblari bir xil tuzilishga ega:

{ "data": { }, "code": 0, "message": "Success" }

Maydon	Turi	Tavsif
`code`	integer	`0` — muvaffaqiyat. Boshqa har qanday qiymat — xato (xatolar jadvaliga qarang). Faqat HTTP-statusni emas, har doim `code` ni tekshiring.
`message`	string	So'rov tilidagi matn (uz / ru / en). Uni dasturiy tahlil qilmang.
`data`	any	Javob ma'lumotlari. Xato bo'lganda yo'q.

Sarlavhalar (Headers)

Sarlavha	Qiymat	Qayerda ishlatiladi
`Content-Type`	`application/json`	Barcha POST so'rovlar
`Authorization`	`Bearer {access_token}`	`sign-in` va `refresh` dan tashqari barcha so'rovlar
`Accept-Language`	`uz` / `ru` / `en`	Ixtiyoriy — `message` tili

Xavfsizlik

client_secret va access_token faqat backendingizda saqlanadi. Frontendga faqat QR rasmi yoki havolasi kerak.

Callback kelganda PKCS#7 ni o'zingiz tekshiring: imzo haqiqiyligini, imzolangan kontent sizning sign_content bilan mos kelishini va sertifikat kutilgan shaxsga (JSHSHIR / STIR) tegishli ekanini.

callback_url uchun HTTPS dan foydalaning va callback'ni o'z yozuvingiz bilan external_id bo'yicha moslang.

7. API tavsifi

Mijoz hisob ma'lumotlarini kirish tokeniga almashtiradi.

Metod - POST
Endpoint - {base_url}/v1/auth/sign-in — Authorization sarlavhasisiz
Content-Type (sarlavha) - application/json

So'rov tanasi

Maydon	Turi	Majburiy	Uzunlik / format	Tavsif
`client_id`	string	Ha	Bo'sh emas; raqam bilan boshlanmaydi	RS-ID bergan Web SDK mijoz identifikatori.
`client_secret`	string	Ha	Bo'sh emas	RS-ID bergan mijoz siri.

{
  "client_id": "web-sdk-client",
  "client_secret": "s3cr3t-value"
}

Javob

Maydon	Turi	Tavsif
`data.access_token`	string (JWT)	`Authorization: Bearer` sarlavhasi uchun token.
`data.token_type`	string	Har doim `Bearer`.
`data.expires_in`	integer	Tokenning amal qilish muddati, soniyalarda.
`data.scope`	string	Berilgan huquqlar, bo'sh joy bilan ajratilgan.
`data.refresh_token`	string (JWT)	Hisob ma'lumotlarini qayta yubormasdan yangi `access_token` olish uchun token.
`code`	integer	Muvaffaqiyatda `0`.
`message`	string	Natija matni.

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "read write",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "code": 0,
  "message": "Success"
}

Har bir so'rov uchun qayta avtorizatsiya qilmang — access_token muddati tugaguncha undan qayta foydalaning.

7.2 Tokenni yangilash (Refresh token)

refresh_token orqali qayta avtorizatsiyasiz yangi access_token beradi. access_token muddati tugaganda (expires_in soniyadan keyin) chaqiring.

Metod - POST
Endpoint - {base_url}/v1/auth/refresh?token={refresh_token} — Authorization sarlavhasisiz.
Content-Type (sarlavha) - application/json

Query-parametrlar

Maydon	Turi	Majburiy	Uzunlik / format	Tavsif
`token`	string	Ha	JWT	Avtorizatsiyadan (7.1) yoki oldingi yangilash javobidan olingan `refresh_token`.

So'rov tanasi

Maydon	Turi	Majburiy	Uzunlik / format	Tavsif
`client_id`	string	Ha	Bo'sh emas; raqam bilan boshlanmaydi	RS-ID bergan Web SDK mijoz identifikatori.
`client_secret`	string	Ha	Bo'sh emas	RS-ID bergan mijoz siri.

{
  "client_id": "web-sdk-client",
  "client_secret": "s3cr3t-value"
}

Javob — 7.1 dagi kabi. Agar refresh-token muddati tugagan yoki yaroqsiz bo'lsa, qayta avtorizatsiyadan o'ting (7.1).

7.3 QR-token yaratish

Imzolash so'rovini yaratadi va QR-kodni qaytaradi.

Metod - POST
Endpoint - {base_url}/v1/qr
Authorization (sarlavha) - Bearer {access_token}
Content-Type (sarlavha) - application/json

So'rov tanasi

Maydon	Turi	Majburiy	Uzunlik / format	Tavsif
`sign_content`	string	Ha	Bo'sh emas	Foydalanuvchi imzolaydigan kontent. RS-ID ilovasida foydalanuvchiga ko'rsatiladi.
`expire_time`	integer	Ha	> 0, soniya	QR-tokenning amal qilish muddati soniyalarda, masalan `300` (5 daqiqa).
`sign_method`	string (enum)	Yo'q	`RS_IMZO`, `E_IMZO`	Ruxsat etilgan imzo turi. Yuborilmasa, foydalanuvchi istalgan imzosi bilan imzolashi mumkin.
`signers`	array	Yo'q	—	Kimga imzolashga ruxsat berilgan. Yuborilmasa, istalgan foydalanuvchi bir marta imzolay oladi. Yuborilsa, har bir imzolovchi bir marta imzolaydi va hammasi imzolagach, QR yakunlanadi.
`signers[].signer`	string	`signers` yuborilsa, ha	JSHSHIR (14 ta raqam) yoki STIR (9 ta raqam)	Imzolashga ruxsat berilgan shaxs yoki kompaniya.
`signers[].allow_id`	string	Yo'q	—	Imzolovchining qo'shimcha identifikatori, imzo bilan birga saqlanadi.
`external_id`	string	Yo'q	Mijoz doirasida yagona	O'z identifikatoringiz (hujjat yoki buyurtma). Holatni o'z id'ingiz bo'yicha tekshirish imkonini beradi (7.7). Yagona bo'lishi kerak — takrorlansa, `-1080` qaytariladi.
`callback_event`	object	Yo'q	—	Callback sozlamalari.
`callback_event.callback_url`	string	Tavsiya etiladi	HTTPS URL	Har bir imzodan so'ng RS-ID imzolangan ma'lumotlarni yuboradigan manzil (7.5).
`redirect_url`	string	Yo'q	URL	Imzolagandan so'ng RS-ID ilovasiga qaytariladigan havola.
`document_provider_type`	string (enum)	Yo'q	`HUJJAT_UZ`, `DIDOX`	Hujjat provayderi, agar hujjat undan bo'lsa.
`qr_response_type`	string (enum)	Yo'q	`BASE64`, `DATA`, `ALL`	Nima qaytarilishi. Standart qiymat `BASE64`. `BASE64` — PNG rasm; `DATA` — QR ichidagi havola; `ALL` — ikkalasi.
`width`	integer	Yo'q	px	QR rasmining kengligi. Standart qiymat `100`.
`height`	integer	Yo'q	px	QR rasmining balandligi. Standart qiymat `100`.

So'rov namunalari

Istalgan foydalanuvchi imzolaydi

{
  "sign_content": "09.11.2026 dagi A-7781-son shartnoma. Xizmat ko'rsatish shartnomasi shartlariga roziman.",
  "expire_time": 300,
  "sign_method": "RS_IMZO",
  "external_id": "CONTRACT-A-7781",
  "callback_event": {
    "callback_url": "https://shop.example.uz/webhooks/rsid/sign"
  },
  "qr_response_type": "ALL",
  "width": 256,
  "height": 256
}

Muayyan imzolovchilar

Elektron imzo bilan kirish

Javob

Maydon	Turi	Tavsif
`data.qr_id`	string	QR-token identifikatori. Uni 7.6 da ishlating.
`data.qr_base64`	string	QR-kod base64 dagi PNG rasm ko'rinishida. `BASE64` va `ALL` uchun qaytariladi.
`data.qr_data`	string	QR-kod ichidagi havola (`https://auth.rsid.uz/{qr_id}`). `DATA` va `ALL` uchun qaytariladi.
`data.expire_at`	string	Amal qilish muddati tugash vaqti, `yyyy-MM-dd HH:mm:ss`.
`data.qr_status`	string	Yangi token uchun `ACTIVE`.
`code`	integer	Muvaffaqiyatda `0`.
`message`	string	Natija matni.

{
  "data": {
    "qr_id": "9b2e6c1a-4f7d-4a3b-8e5c-1d2f3a4b5c6d",
    "qr_data": "https://auth.rsid.uz/9b2e6c1a-4f7d-4a3b-8e5c-1d2f3a4b5c6d",
    "qr_base64": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+...",
    "expire_at": "2026-11-09 17:35:00",
    "qr_status": "ACTIVE"
  },
  "code": 0,
  "message": "Success"
}

Rasmni <img src="data:image/png;base64,{qr_base64}"> orqali ko'rsating yoki qr_data bo'yicha o'z QR-kodingizni chizing.

Xatolar

Kod	Sabab
`-1002`	Hisob ma'lumotlari Web SDK mijoziga tegishli emas.
`-1080`	Bunday `external_id` bilan QR-token allaqachon mavjud.
`-5`	Token foydalanuvchisi topilmadi.
`400`	Validatsiya xatosi, masalan `sign content cannot be blank` yoki `expire_time` yuborilmagan / musbat emas.

7.4 RS-ID mobil ilovasida foydalanuvchi harakatlari

Foydalanuvchi RS-ID mobil ilovasini ochadi va QR-kodni skanerlaydi.

Ilova imzolanadigan kontentni (sign_content) ko'rsatadi.

Foydalanuvchi elektron imzoni tanlaydi (sign_method berilgan bo'lsa, faqat shu turdagi kalitlar ko'rsatiladi). signers berilgan bo'lsa, faqat ruxsat etilgan JSHSHIR / STIR'ga ega imzolardan foydalanish mumkin.

Foydalanuvchi imzolaydi. Ilova imzoni (PKCS#7) RS-ID'ga yuboradi.

RS-ID imzoni tekshiradi va callback yuboradi (7.5).

Quyidagi hollarda ilova xato ko'rsatadi va imzo qabul qilinmaydi:

Holat	Natija
QR-token muddati tugagan	`QR token expired` — yangi QR-token yarating.
QR-token allaqachon yakunlangan	`QR token completed`.
Imzoning JSHSHIR / STIR'i `signers` da yo'q	Foydalanuvchiga imzolashga ruxsat yo'q.
Bu imzolovchi allaqachon imzolagan	Hujjat bu imzo bilan allaqachon imzolangan.
Barcha imzolovchilar imzolagan	Hujjat to'liq imzolangan.

7.5 Imzolangan ma'lumotlar bilan callback

Har bir muvaffaqiyatli imzodan so'ng RS-ID callback_event.callback_url manziliga POST so'rov yuboradi.

Metod - POST
URL - sizning callback_url
Content-Type - application/json

So'rov tanasi (RS-ID yuboradi)

Maydon	Turi	Tavsif
`sign_request_data`	string	Asl yaratish so'rovingizning (7.3) JSON'i, satr ko'rinishida. O'z yozuvingizni uning `external_id` qiymati bo'yicha toping.
`pkcs7`	string	Imzolangan ma'lumotlar, base64 dagi PKCS#7 (CMS). Imzolangan kontent, imzo va imzolovchi sertifikatini o'z ichiga oladi.

{
  "sign_request_data": "{\"signers\":null,\"expire_time\":300,\"sign_method\":\"RS_IMZO\",\"sign_content\":\"09.11.2026 dagi A-7781-son shartnoma. Xizmat ko'rsatish shartnomasi shartlariga roziman.\",\"redirect_url\":null,\"external_id\":\"CONTRACT-A-7781\",\"document_provider_type\":null,\"callback_event\":{\"callback_url\":\"https://shop.example.uz/webhooks/rsid/sign\"},\"qr_response_type\":\"ALL\",\"width\":256,\"height\":256}",
  "pkcs7": "MIIKvgYJKoZIhvcNAQcCoIIKrzCCCqsCAQExDjAMBggqhlADAgIBAQUAMIIBDgYJKoZIhvcNAQcBoIIA..."
}

Sizning javobingiz — HTTP 200 qaytaring. Callback bir marta yuboriladi va takrorlanmaydi, shuning uchun holatni 7.6 / 7.7 orqali ham tekshiring.

Bir nechta signers bo'lsa, callback har bir imzodan so'ng yuboriladi.

7.6 `qr_id` bo'yicha QR-token holati

Metod - GET
Endpoint - {base_url}/v1/qr/{qr_id}
Authorization (sarlavha) - Bearer {access_token}

Yo'l parametrlari

Maydon	Turi	Majburiy	Uzunlik / format	Tavsif
`qr_id`	string	Ha	UUID	7.3 dan.

Javob

Maydon	Turi	Tavsif
`data.qr_id`	string	QR-token identifikatori.
`data.qr_status`	string	`ACTIVE` — imzo kutilmoqda; `COMPLETED` — imzolangan (`signers` berilgan bo'lsa, hammasi tomonidan); `EXPIRED` — muddati tugagan; `DELETED` — o'chirilgan.
`data.expire_at`	string	Amal qilish muddati tugash vaqti, `yyyy-MM-dd HH:mm:ss`.
`data.qr_data`	string	QR-kod ichidagi havola.
`data.qr_base64`	string	QR rasmi (PNG 100×100, base64) — uni qayta ko'rsatish uchun.

{
  "data": {
    "qr_id": "9b2e6c1a-4f7d-4a3b-8e5c-1d2f3a4b5c6d",
    "qr_data": "https://auth.rsid.uz/9b2e6c1a-4f7d-4a3b-8e5c-1d2f3a4b5c6d",
    "qr_base64": "iVBORw0KGgoAAAANSUhEUgAAAGQAAABkAQMAAABKLAcXAAAABlBMVEX///8AAABVwtN+...",
    "expire_at": "2026-11-09 17:35:00",
    "qr_status": "COMPLETED"
  },
  "code": 0,
  "message": "Success"
}

qr_status = ACTIVE ekan, har bir necha soniyada so'rov yuboring.

Xatolar

Kod	Sabab
`-1035`	QR-token topilmadi yoki boshqa mijozga tegishli.
`-1002`	Hisob ma'lumotlari Web SDK mijoziga tegishli emas.

7.7 `external_id` bo'yicha QR-token holati

7.6 bilan bir xil, lekin 7.3 dagi o'z external_id qiymatingiz bo'yicha.

Metod - GET
Endpoint - {base_url}/v1/qr/status/by-external/{external_id}
Authorization (sarlavha) - Bearer {access_token}

Yo'l parametrlari

Maydon	Turi	Majburiy	Uzunlik / format	Tavsif
`external_id`	string	Ha	—	7.3 dagi `external_id`.

Javob — 7.6 dagi kabi.

Xatolar — 7.6 dagi kabi.

8. Xato kodlari

Kod	Nomi	Ma'nosi
`0`	SUCCESS	Muvaffaqiyat.
`-5`	BAD_CREDENTIALS	Hisob ma'lumotlari noto'g'ri yoki token foydalanuvchisi topilmadi.
`-9`	SYSTEM_ERROR	Kutilmagan server xatosi.
`-1000`	BAD_REQUEST	Noto'g'ri so'rov.
`-1002`	CLIENT_NOT_PERMITTED	Web SDK mijozi emas.
`-1035`	INVALID_QR_TOKEN	QR-token topilmadi yoki boshqa mijozga tegishli.
`-1080`	QR_TOKEN_EXISTS_BY_EXTERNAL_ID	Bunday `external_id` bilan QR-token allaqachon mavjud.

QR-kod orqali imzolash

QR-kod orqali elektron imzo bilan imzolash (RS-IMZO / E-IMZO)#

1. QR-kod orqali imzolash nima#

Foydalanish holatlari#

2. Atamalar#

3. Qanday ishlaydi#

4. Integratsiya sxemasi#

5. Muhitlar#

6. Umumiy qoidalar#

Javob formati#

Sarlavhalar (Headers)#

Xavfsizlik#

7. API tavsifi#

7.1 Avtorizatsiya (Sign in)#

7.2 Tokenni yangilash (Refresh token)#

7.3 QR-token yaratish#

7.4 RS-ID mobil ilovasida foydalanuvchi harakatlari#

7.5 Imzolangan ma'lumotlar bilan callback#

7.6 qr_id bo'yicha QR-token holati#

7.7 external_id bo'yicha QR-token holati#

8. Xato kodlari#

QR-kod orqali elektron imzo bilan imzolash (RS-IMZO / E-IMZO)

1. QR-kod orqali imzolash nima

Foydalanish holatlari

2. Atamalar

3. Qanday ishlaydi

4. Integratsiya sxemasi

5. Muhitlar

6. Umumiy qoidalar

Javob formati

Sarlavhalar (Headers)

Xavfsizlik

7. API tavsifi

7.1 Avtorizatsiya (Sign in)

7.2 Tokenni yangilash (Refresh token)

7.3 QR-token yaratish

7.4 RS-ID mobil ilovasida foydalanuvchi harakatlari

7.5 Imzolangan ma'lumotlar bilan callback

7.6 `qr_id` bo'yicha QR-token holati

7.7 `external_id` bo'yicha QR-token holati

8. Xato kodlari