Chaindoc logoChaindoc

API интеграциясы

Chaindoc REST API арқылы құжаттар үрдісін толық автоматтандыруға болады. Қолтаңбалар жинаңыз. Оқиғаларды нақты уақытта синхрондаңыз. Міне мәселе — бастау оңай. Бұл бетте негізгі ұғымдар мен практикада жиі кездесетін интеграция үлгілері қарастырылады.

API арқылы не істеуге болады

API арқылы Chaindoc мүмкіндіктеріне толық қол жеткізесіз: құжаттарды жүктеу, қолтаңба сұрауларын жасау, командаларды басқару және webhooks арқылы оқиғаларды тыңдау. Адал айтсақ, веб-қосымшаны қуаттайтын дәл осы API.

Интеграцияның үш жолы

Стекіңізге сәйкес келетінін таңдаңыз. Көптеген өндірістік қолданбалар backend-де Server SDK, ал frontend-де Embed SDK пайдаланады.

  • REST API — тікелей HTTP сұраулар, кез келген тілде жұмыс істейді. Ең жоғары икемділік.
  • Server SDK — автоматты қайталау және қателерді өңдеуі бар type-safe Node.js құрылымы (`@chaindoc_io/server-sdk`)
  • Embed SDK — қолтаңба интерфейсін веб-қосымшаңызға енгізеді, пайдаланушылар сайттан кетпейді (`@chaindoc_io/embed-sdk`)

SDK әлі орнатылмаған болса, орнату нұсқаулығы React, Vue, Angular және Next.js үшін npm баптауын қамтиды.

Жылдам мысал

Мұнда "құжат жасау" шақыруы үш түрде көрсетілген. SDK нұсқасы ең қысқа, бірақ таза REST шақыруы нақты не болып жатқанын көрсетеді.

curl -X POST https://api.chaindoc.io/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract",
    "description": "Service agreement",
    "status": "published",
    "hashtags": ["#contract"],
    "meta": []
  }'

Аутентификация

Әр сұрауда Authorization тақырыбында API кілті болуы керек:

terminal
Authorization: Bearer sk_live_xxxxxxxxxxxxx

Екі кілт түрі бар, оларды шатастыру — ең жиі кездесетін интеграция қатесі:

  • Public keys (`pk_`) — тек оқу, frontend коды үшін қауіпсіз
  • Secret keys (`sk_`) — толық оқу/жазу, тек backend. Client-side кодта ешқашан ашпаңыз.
  • Екеуі де test (`_test_`) және live (`_live_`) нұсқаларында бар. Test кілттері sandbox-қа жүгінеді.

Rate limits

API жауап тақырыптарына rate limit ақпаратын қайтарады. Шекке жетсеңіз, 429 жауабын аласыз. Кідіріп, қайталаңыз.

terminal
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000
  • Жалпы endpoint-тер: 10 секундта 3 сұрау
  • Media жүктеу: 10 секундта 3 сұрау
  • Оқу операциялары: 60 секундта 10 сұрау
  • Қолтаңба жасау: 3 секундта 20 сұрау

Server SDK экспоненциалды кідірумен қайталауды автоматты өңдейді. Таза HTTP пайдалансаңыз, қайталау логикасын өзіңіз жасаңыз.

Қателерді өңдеу

Қателер JSON түрінде, status code, хабар және (тексеру қателері үшін) нақты өріс мәселелерінің тізімімен қайтып келеді:

terminal
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "name",
      "message": "name must be a string"
    }
  ]
}

Жиі кездесетін status code-тар: 400 (нашар сұрау), 401 (жарамсыз кілт), 403 (жоспарда API жоқ), 404 (табылмады), 429 (rate limit), 500 (сервер қатесі). 5xx қателері үшін кідірумен қайталаңыз.

Жиі кездесетін интеграция үлгілері

Толық қолтаңба үрдісі (embedded)

Ең жиі кездесетін үлгі: құжатты жүктеу, қолтаңбаға жіберу және қолтаңба UI қолданбаңыздың ішінде көрсету.

1Файлды жүктеуPOST /media/upload — PDF, Office құжатын немесе суретті жіберіңіз.

2Құжат жасауPOST /documents — blockchain тексеруін іске қосу үшін status='published' орнатыңыз.

3Қолтаңба сұрауын жасауPOST /signatures/requests — алушыларды қосу, қолтаңба тәртібі мен мерзімін орнату.

4Embedded сессия жасауPOST /embedded/sessions — әр қол қоюшы үшін sessionId береді.

5Қолтаңба UI ашуsessionId Embed SDK openSignatureFlow() әдісіне өткізіңіз.

6Аяқталуын тыңдауwebhook орнатыңыз signature.request.completed оқиғасы үшін немесе GET /signatures/requests/:id/status сұраңыз.

Жылдам бастау нұсқаулығында бұл үрдіс толық коды бар.

Email негізіндегі қолтаңба (embed жоқ)

Қол қоюшылар қолданбаңызды пайдаланбаса, `embeddedFlow: false` орнатыңыз. Chaindoc оларға қолтаңба сілтемесімен email жібереді. Қол қойған кезде webhook хабарландыруларын аласыз.

terminal
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Қол қоюшылар email сілтемелерін алады
  message: 'Please review and sign this document',
});

Құжаттарды массивті өңдеу

Топтық импорт үшін файлдарыңызды айналып өтіп, әрқайсысын жүктеңіз. Бірақ rate limits-ке назар аударыңыз. Жүздеген құжатты өңдесеңіз, сұраулар арасында кішкене кідіріс қосыңыз немесе SDK встроенный қайталау логикасын пайдаланыңыз.

terminal
const documents = ['doc1.pdf', 'doc2.pdf', 'doc3.pdf'];

for (const file of documents) {
  const buffer = await readFile(file);
  const blob = new Blob([buffer], { type: 'application/pdf' });
  
  const { media } = await chaindoc.media.upload([blob]);
  
  await chaindoc.documents.create({
    name: file,
    description: 'Batch processed document',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

KYC интеграциясы

Жоғары қауіпсіздікпен жұмыс істеу үшін қол қою алдында жеке тұлғаны растауды талап ету керек. Chaindoc Sumsub KYC интеграциялайды. Қолтаңба сұрауында `isKycRequired: true` орнатыңыз, қол қоюшылар қол қою алдында жеке тұлғаны растайды.

terminal
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Қосымша: алдын-ала тексерілген
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true,
});

API арқылы қолжетімділік бақылауы

Құжат рұқсаттарын бағдарламалық орнатуға болады. Конкретті email немесе команда рөлдеріне шектеу қойыңыз:

terminal
await chaindoc.documents.updateRights(documentId, {
  accessType: 'restricted',
  accessEmails: [
    { email: 'viewer@company.com', level: 'read' },
    { email: 'editor@company.com', level: 'write' },
  ],
  accessRoles: [
    { roleId: 1, level: 'read' },
  ],
});

Үздік тәжірибелер

  • API кілттерін орта айнымалыларда сақтаңыз. Ешқашан нұсқаны басқару жүйесіне жібермеңіз.
  • Әзірлеу үшін test кілттерін (`sk_test_`) пайдаланыңыз. Live кілттері (`sk_live_`) өндіріске жүгінеді.
  • 429 жауаптары үшін экспоненциалды кідіруді іске асырыңыз. SDK бұл автоматты жасайды.
  • webhook қолтаңбаларын HMAC арқылы тексеріңіз, қайталама шабуылдардан қорғану үшін.
  • Құжаттарды жасамас бұрын файлдарды жүктеңіз. API жүктеу қадамындағы media ID қажет.
  • Тізімдерді қайтаратын endpoint-терге pagination пайдаланыңыз. Барлығын бірден алмаңыз.
  • Өндіріске шығар алдында қауіпсіздік нұсқаулығын тексеріңіз.

Қолданыс мысалдары

Командалар API арқылы жасайтын нақты үлгілер:

  • E-commerce — құнды тапсырыстар үшін сатып алу келісімшарттарын автоматты жасау және төлем кезінде қолтаңбаға жіберу
  • HR onboarding — қызметкерлерді қабылдау кезінде еңбек келісімшарттарын үлгілерден жасап, жаңа қызметкерлерге жіберу
  • CRM интеграциясы — Salesforce немесе HubSpot мәмілелерінен қолтаңба сұрауларын іске қосу
  • Құжаттарды архивтеу — бар сақтау жүйеңіздегі құжаттарға blockchain тексеруін қосу

Келесі не істеу керек

  • API құжаттамасы — сұрау/жауап мысалдарымен толық endpoint анықтамасы
  • SDK — Server SDK және Embed SDK, фреймворк нұсқаулықтарымен
  • Webhooks — нақты уақыттағы оқиға хабарландыруларын орнату
  • Жылдам бастау — 10 минутта алғашқы интеграцияңызды іске қосу
  • Орнату — барлық қолдау көрсетілген фреймворктар үшін npm баптауы