Жылдам қолдану нұсқаулығы

Chaindoc-ті 10 минуттан аз уақытта іске қосыңыз. Бұл нұсқаулық сізге веб-интерфейс пен API екі жолын да көрсетеді, сондықтан өзіңізге сәйкесін таңдаңыз.

Веб-интерфейс арқылы қолтаңба қою

Алғашқы қолтаңба сұрауын жіберу үшін код қажет емес. Веб-қосымша бәрін өзі жасайды: жүктеу, алушылар, қолтаңба процесі және блокчейн тексеру.

Қадам бойынша: сіздің алғашқы қолтаңбаңыз

Қолтаңба түрлерін (қарапайым, кеңейтілген, біліктілік) түсінгіңіз келе ме? Бұл үйлестіру үшін маңызды. Көпшілік бизнес келісім-шарттары қарапайым электрондық қолтаңбалармен жақсы жұмыс істейді, бірақ реттелетін салаларға көбінесе кеңейтілген немесе біліктілік қолтаңбасы қажет.

API арқылы интеграциялау

Егер сіз қолтаңбаны өз қосымшаңызға енгізгіңіз келсе, REST API және TypeScript SDK-ны пайдаланасыз. Үрдіс веб-интерфейстегімен бірдей, тек автоматтандырылған.

1. API кілттерін алыңыз

API кіруі үшін Business жоспары қажет. Басқару панеліңіздегі Параметрлер > API кіруі бөліміне өтіп, екі кілт жасаңыз:

• Public кілт (`pk_`) Embed SDK-ны алдыңғы жағында пайдалану үшін
• Secret кілт (`sk_`) Server SDK-ны артқы жағында пайдалану үшін. Бұны клиенттік кодтан сырт ұстаңыз.

2. SDK орнатыңыз

Қолданбаңызға сәйкес келетін SDK-ны таңдаңыз. Көпшілік қолданбаларға екеуі де қажет: құжаттар жасау үшін Server SDK және қолтаңба интерфейсі үшін Embed SDK.

# Node.js 18+ қажет
npm install @chaindoc_io/server-sdk

Толық framework орнату үшін (React, Vue, Angular, Next.js), орнату нұсқаулығына қараңыз.

3. Құжатты жүктеп, жасаңыз

import { Chaindoc } from '@chaindoc_io/server-sdk';
import { readFile } from 'fs/promises';

// Initialize SDK
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// 1. Upload document
const buffer = await readFile('./contract.pdf');
const file = new Blob([buffer], { type: 'application/pdf' });
const { media } = await chaindoc.media.upload([file]);

// 2. Create document record
const doc = await chaindoc.documents.create({
  name: 'Service Agreement',
  description: 'Q4 2024 Contract',
  media: media[0],
  status: 'published', // Triggers blockchain verification
  hashtags: ['#contract', '#2024'],
  meta: [{ key: 'client', value: 'Acme Corp' }],
});

console.log('Document created:', doc.documentId);

`status: 'published'` орнату блокчейн растауын автоматты түрде іске қосады. Егер кейінге қалдырғыңыз келсе, `'draft` пайдаланыңыз және кейін жариялаңыз.

4. Қолтаңба сұрауын жасаңыз

// Create signature request for multiple signers
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: doc.document.versions[0].uuid,
  recipients: [
    { email: 'signer1@example.com' },
    { email: 'signer2@example.com' },
  ],
  deadline: new Date('2024-12-31'),
  message: 'Please review and sign this agreement',
  embeddedFlow: true, // Enable for frontend integration
});

console.log('Signature request created:', sigRequest.signatureRequest.uuid);

Егер қолтаңба интерфейсін қосымшаңыздың ішінде көрсеткіңіз келсе, `embeddedFlow: true` орнатыңыз. Олсыз, қол қоюшылар Chaindoc-тың хостингтік қолтаңба бетіне сілтеме алады.

5. Қолтаңба интерфейсін көрсетіңіз (алдыңғы жағы)

Бұл міндетті емес. Егер `embeddedFlow: true` орнатсаңыз, қолтаңба интерфейсін тікелей қосымшаңыздың ішінде аша аласыз. Алдымен артқы жақта сессия жасаңыз, содан кейін session ID алдыңғы жаққа жіберіңіз.

// Create embedded session for signer
const session = await chaindoc.embedded.createSession({
  email: 'signer1@example.com',
  metadata: {
    documentId: doc.documentId,
    signatureRequestId: sigRequest.signatureRequest.uuid,
  },
});

// Return sessionId to frontend
res.json({ sessionId: session.sessionId });

6. Күйді тексеріңіз және оқиғаларды тыңдаңыз

Күйді сұрауға болады, бірақ өндірісте webhooks жақсырақ нұсқа. Олар бір нәрсе болған сәтте серверіңізге хабарлайды.

// Poll approach (fine for testing)
const status = await chaindoc.signatures.getRequestStatus(
  sigRequest.signatureRequest.uuid
);

if (status.signatureRequest.status === 'completed') {
  console.log('All signatures collected!');
}

7. Webhooks орнатыңыз (ұсынылады)

Webhooks оқиғаларды нақты уақытта серверіңізге жібереді, сондықтан үнемі тексерудің қажеті жоқ. Мұнда негізгі Express өңдеуші:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', (req, res) => {
  const event = req.headers['x-webhook-event'];
  const payload = req.body;
  
  switch (event) {
    case 'document.verified':
      console.log('Document verified on blockchain:', payload.txHash);
      break;
    case 'signature.request.completed':
      console.log('All signatures collected!');
      // Send notifications, update status, etc.
      break;
  }
  
  res.status(200).send('OK');
});

Өндірісте HMAC арқылы webhook қолтаңбаларын тексеру керек, өйткені жүктеме шынымен Chaindoc-тан келгеніне көз жеткізу керек. Webhooks нұсқаулығы оны толық түсіндіреді.

Толық үрдіс мысалы

Бұл бәрін біріктіреді: жүктеу, жасау, қол қою, растау. Көшіріп, өз API кілттеріңізді қойып, жұмыс істейтін прототип алыңыз.

import { Chaindoc } from '@chaindoc_io/server-sdk';
import { readFile } from 'fs/promises';

async function createSigningWorkflow() {
  const chaindoc = new Chaindoc({
    secretKey: process.env.CHAINDOC_SECRET_KEY!,
  });
  
  // Step 1: Upload document
  const buffer = await readFile('./contract.pdf');
  const file = new Blob([buffer], { type: 'application/pdf' });
  const { media } = await chaindoc.media.upload([file]);
  
  // Step 2: Create document
  const doc = await chaindoc.documents.create({
    name: 'Service Agreement',
    description: 'Contract for consulting services',
    media: media[0],
    status: 'published',
    hashtags: ['#contract'],
    meta: [],
  });
  
  // Step 3: Create signature request
  const sigRequest = await chaindoc.signatures.createRequest({
    versionId: doc.document.versions[0].uuid,
    recipients: [{ email: 'signer@example.com' }],
    deadline: new Date('2024-12-31'),
    embeddedFlow: true,
  });
  
  // Step 4: Create session for frontend
  const session = await chaindoc.embedded.createSession({
    email: 'signer@example.com',
    metadata: {
      documentId: doc.documentId,
      signatureRequestId: sigRequest.signatureRequest.uuid,
    },
  });
  
  return {
    documentId: doc.documentId,
    sessionId: session.sessionId,
  };
}

// Usage
const { documentId, sessionId } = await createSigningWorkflow();
console.log('Ready for signing:', { documentId, sessionId });

Келесі қадамдар

Енді негіздерді меңгергеннен кейін, нені жасап жатқаныңызға байланысты мыналарды зерттеңіз:

• Орнату — React, Vue, Angular және Next.js үшін framework-терге арналған орнату
• API құжаттамасы — сұрау/жауап мысалдарымен толық нүктелік анықтама
• SDKs — Server SDK және Embed SDK, framework-терге арналған интеграция нұсқаулықтарымен
• Webhooks — өндірістік қосымшалар үшін нақты уақыттағы оқиға хабарламалары
• Қауіпсіздік үздік тәжірибелері — тікелей эфирге шығармас бұрын не қорғау керек

Жиі қойылатын сұрақтар

Блокчейн растауы қанша уақытты алады?

Әдетте 1-5 минут, желіден тәуелді. Сіздің құжатыңыз дереу қолжетімді. Растау фонда жүреді және аяқталғанда сіз webhook оқиғасын аласыз.

Төлемсіз API-ны сынауға бола ма?

Тегін жоспар веб-интерфейске кіруді береді. API кіруі үшін Business жоспары қажет, бірақ sandbox ортасына барлығын нақты деректерге әсер етпей немесе квотаны қолданбай сынауға болады.

Бұл қолтаңбалар заңды түрде міндетті ме?

Иә. Chaindoc қолтаңбалары Еуропада eIDAS, АҚШ-та ESIGN Act және UETA, және басқа да көптеген юрисдикциялардағы баламалы ережелерге сәйкес келеді. Блокчейн растауы бұған қосымша дәлел деңгейін қосады, бұл дауларда маңызды болуы мүмкін. Үйлестіру қажеттіліктеріңізге сәйкес келетін қолтаңба түрі туралы толық ақпарат алу үшін қолтаңбалар құжаттамасына қараңыз.

Қандай файл пішімдерін жүктей аламын?

PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, JPG, PNG, GIF, WEBP, SVG, MP4, AVI, MOV және WMV. Ең көп файл көлемі 50 МБ.