API арқылы алғашқы қолтаңба

Бес қадам: кілт алу, құжатты жүктеу, қол қою сессиясын құру, сілтемені қол қоюшыға беру және нәтижені алу. Барлық сұраулар Authorization тақырыбындағы кілтпен.

1. 1Кілт алыңыз

   Тіркеліп, кабинеттің «Әзірлеушілерге» бөлімінде sandbox кілтін жасаңыз — бірден, өтінімсіз. Кілт бір рет көрсетіледі. Нақты ЭЦҚ кілттерімен қол қою (live) үшін жұмыс режиміне өтінім беріңіз.

   Тіркеліп, sandbox кілтін алу
   shellКөшіру

   export ESIGN_KEY=sk_test_...   # ключ из кабинета → «Разработчикам»

2. 2Құжатты жүктеңіз

   20 МБ дейінгі PDF, Word, Excel, суреттер, TXT, CSV және XML жарайды.

   POST /v1/documentsКөшіру

   curl https://e-sign.amir-amirov.kz/v1/documents \
     -H "Authorization: Bearer $ESIGN_KEY" \
     -F file=@contract.pdf
   
   # → { "id": "doc_01JBX4K9T6R2ZC8N5Q3W7Y1M0A", "status": "uploaded", ... }

3. 3Қол қою сессиясын құрыңыз

   Әр қол қоюшыда кімнің кілті болуы керек екенін көрсетіңіз: ЖСН, БСН және өкілеттіктер.

   POST /v1/sign-sessionsКөшіру

   curl https://e-sign.amir-amirov.kz/v1/sign-sessions \
     -H "Authorization: Bearer $ESIGN_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: contract-114" \
     -d '{
       "document_id": "doc_01JBX4K9T6R2ZC8N5Q3W7Y1M0A",
       "signing_order": "sequential",
       "expires_in_hours": 72,
       "signers": [
         { "label": "Арендатор", "expected": { "iin": "900101300235" } },
         { "label": "Арендодатель",
           "expected": { "bin": "123456789013", "authority": "sign_right" } }
       ]
     }'

   Sandbox-та тек ҰКО тесттік кілттері, live-та тек нақты кілттер қабылданады. Тесттік кілттерді pki.gov.kz сайтынан жүктеуге болады.

4. 4Сілтемені қол қоюшыға беріңіз

   Жауапта әр қол қоюшының signing_url бар. Оны кез келген тәсілмен жіберіңіз: қол қоюшы e-sign бетін ашып, NCALayer арқылы қол қояды.

   201 CreatedКөшіру

   {
     "id": "ses_01JBX5...",
     "status": "pending",
     "signers": [
       { "label": "Арендатор", "status": "pending",
         "signing_url": "https://e-sign.amir-amirov.kz/s/m0Z8oPpd..." },
       { "label": "Арендодатель", "status": "waiting", "signing_url": "..." }
     ]
   }

   Қазір қол қоюшы компьютерде NCALayer арқылы қол қояды. Телефоннан eGov Mobile арқылы қол қою уақытша қолжетімсіз: телефонда қол қою беті сілтемені компьютерде ашуды ұсынады.

5. 5Нәтижені алыңыз

   Барлығы қол қойғанда session.completed webhook келеді. Сұрау қолтаңбасын тексеріп, дәлелдер пакетін жүктеңіз.

   webhookКөшіру

   POST https://your-app.kz/webhooks/esign
   X-Signature: t=1761822145,v1=5f2c...
   
   { "id": "evt_01JBX6...", "type": "session.completed",
     "data": { "session": { "id": "ses_01JBX5...", "status": "completed",
                            "document_id": "doc_01JBX4K9T6R2ZC8N5Q3W7Y1M0A" } } }
   
   # пакет доказательств: документ, .cms, метки времени, OCSP, лист подписей
   curl -o evidence.zip https://e-sign.amir-amirov.kz/v1/documents/doc_01JBX4K9T6R2ZC8N5Q3W7Y1M0A/evidence \
     -H "Authorization: Bearer $ESIGN_KEY"

   Webhook қолтаңбасын тексеру

   Node.jsКөшіру

   import crypto from "node:crypto";
   
   // rawBody — тело запроса как строка, до JSON.parse
   export function verifyEsignWebhook(rawBody, header, secret) {
     const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
     if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // старше 5 минут
     const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
     return expected.length === v1.length &&
       crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
   }