Chaindoc logoChaindoc

Орнату

Chaindoc SDK жобаңызға енгізіңіз. Екі пакет бар: backend жұмысы (құжаттар, қолтаңбалар, тексеру) үшін Server SDK және frontend-ге қолтаңба UI енгізу үшін Embed SDK.

Бастамас бұрын

Егер сізде әлі тіркелгі болмаса, quick start нұсқаулығынан бастаңыз.

Server SDK

Server SDK backend-де барлық нәрсені басқарады: құжаттар жасау, қолтаңба сұраныстарын жіберу, командаларды басқару және blockchain тексеруін іске қосу. Бұл REST API жұқа қабы, сондықтан API docs оқысаңыз, әдіс атаулары таныс болады.

Пакетті орнату

npm install @chaindoc_io/server-sdk

Қоршаған орта айнымалыларын баптау

Жоба түбірінде `.env` файл жасаңыз. Мұнда secret кілт керек.

.env
# Production keys
CHAINDOC_SECRET_KEY=sk_live_xxxxxxxxxxxxx

# Staging/Testing keys
# CHAINDOC_SECRET_KEY=sk_test_xxxxxxxxxxxxx

# Optional: Custom API endpoint
# CHAINDOC_API_URL=https://api.chaindoc.io

SDK инициализациясы

lib/chaindoc.ts
import { Chaindoc } from '@chaindoc_io/server-sdk';

// Basic initialization
export const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// Advanced configuration
export const chaindocAdvanced = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
  baseUrl: process.env.CHAINDOC_API_URL, // Optional
  timeout: 60000, // 60 seconds
  retry: {
    maxRetries: 5,
    baseDelayMs: 1000,
    maxDelayMs: 10000,
  },
  headers: {
    'X-Custom-Header': 'value',
  },
});

Негізгі конфигурация көптеген жобалар үшін жеткілікті. Retry параметрлері көптеген құжаттарды пакеттік өңдегенде реттеуге тұрарлық, себебі API rate limits бар.

Байланысты тексеру

terminal
// Test API connection
const health = await chaindoc.healthCheck();

if (health.status === 'ok' && health.apiKeyValid) {
  console.log('Connected to Chaindoc API');
  console.log('User ID:', health.userId);
} else {
  console.error('Connection failed');
}

Егер бұл сәтсіз болса, secret кілтіңіз `sk_live_` (production) немесе `sk_test_` (sandbox) екенін тексеріңіз. Ең жиі кездесетін мәселе - қате түрде public кілтті қолдану.

Embed SDK

Embed SDK Chaindoc қолтаңба интерфейсін веб-қосымшаңызда көрсетуге мүмкіндік береді. Пайдаланушылар сіздің сайтыңызды тастамай құжаттарға қол қояды. React, Vue, Angular немесе қарапайым JavaScript-пен жұмыс істейді.

Пакетті орнату

npm install @chaindoc_io/embed-sdk

CDN опциясы build қадамы жоқ сайттар үшін ыңғайлы. Production үшін npm пакетін қолданыңыз, осылайша tree-shaking және дұрыс нұсқа бақылауы аласыз.

Қоршаған орта айнымалыларын баптау

Embed SDK public кілтті (`pk_`) қолданады, ол клиенттік кодқа енгізуге қауіпсіз.

# .env.local
REACT_APP_CHAINDOC_PUBLIC_KEY=pk_live_xxxxx
# or for Next.js
NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY=pk_live_xxxxx

Қосымшаңызда инициализация

// hooks/useChaindoc.ts
import { useRef, useEffect } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export function useChaindoc() {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

  useEffect(() => {
    sdkRef.current = new ChaindocEmbed({
      publicKey: process.env.REACT_APP_CHAINDOC_PUBLIC_KEY!,
      environment: 'production',
    });

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  return sdkRef.current;
}

Framework-ға арналған баптау

Бұл мысалдар әр framework-та Embed SDK-ны провайдер немесе сервис ретінде қалай қосуды көрсетеді. Егер backend-де Server SDK қолдансаңыз, провайдер қажет емес; оны қажет жерде импорттаңыз.

Next.js (App Router)

app/providers.tsx
'use client';

import { createContext, useContext, useEffect, useRef } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

const ChaindocContext = createContext<ChaindocEmbed | null>(null);

export function ChaindocProvider({ children }: { children: React.ReactNode }) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

  useEffect(() => {
    if (!sdkRef.current) {
      sdkRef.current = new ChaindocEmbed({
        publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!,
      });
    }

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  return (
    <ChaindocContext.Provider value={sdkRef.current}>
      {children}
    </ChaindocContext.Provider>
  );
}

export const useChaindoc = () => useContext(ChaindocContext);

Next.js (Pages Router)

pages/_app.tsx
import type { AppProps } from 'next/app';
import { useEffect, useRef } from 'react';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export default function App({ Component, pageProps }: AppProps) {
  const sdkRef = useRef<ChaindocEmbed | null>(null);

  useEffect(() => {
    sdkRef.current = new ChaindocEmbed({
      publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!,
    });

    return () => {
      sdkRef.current?.destroy();
    };
  }, []);

  return <Component {...pageProps} />;
}

Nuxt 3

plugins/chaindoc.client.ts
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();
  
  const chaindoc = new ChaindocEmbed({
    publicKey: config.public.chaindocPublicKey,
  });

  return {
    provide: {
      chaindoc,
    },
  };
});

Angular

services/chaindoc.service.ts
import { Injectable, OnDestroy } from '@angular/core';
import { ChaindocEmbed } from '@chaindoc_io/embed-sdk';
import { environment } from '../environments/environment';

@Injectable({
  providedIn: 'root'
})
export class ChaindocService implements OnDestroy {
  private sdk: ChaindocEmbed;

  constructor() {
    this.sdk = new ChaindocEmbed({
      publicKey: environment.chaindocPublicKey,
    });
  }

  getSdk(): ChaindocEmbed {
    return this.sdk;
  }

  ngOnDestroy(): void {
    this.sdk.destroy();
  }
}

TypeScript конфигурациясы

Екі SDK толық TypeScript анықтамаларымен келеді. Қосымша `@types` пакеттері қажет емес.

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "types": ["node"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Егер ескі TypeScript (< 5.0) қолдансаңыз, `"moduleResolution": "bundler"` орнына `"node"` қолданыңыз.

Әзірлеу vs production

Әзірлеу кезінде test кілттерін қолданыңыз, сонда нақты құжаттар жасап немесе қолтаңба emailдерін нақты алушыларға жібермейсіз.

Әзірлеу баптауы

terminal
// Use test keys for development
const chaindoc = new Chaindoc({
  secretKey: 'sk_test_xxxxx',
  baseUrl: 'https://api.chaindoc.io',
});

const embed = new ChaindocEmbed({
  publicKey: 'pk_test_xxxxx',
  environment: 'staging',
  debug: true, // Enable detailed logs
});

`debug: true` жалаушысы консольға сұраныс/жауап мәліметтерін шығарады. Шуыл, бірақ неліктен жұмыс істемейтінін түсінгенде пайдалы.

Production баптауы

terminal
// Use live keys for production
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!, // sk_live_xxxxx
});

const embed = new ChaindocEmbed({
  publicKey: process.env.NEXT_PUBLIC_CHAINDOC_PUBLIC_KEY!, // pk_live_xxxxx
  environment: 'production',
});

Орнатуды тексеру

Барлығы дұрыс қосылғанын тексеру үшін бұл тексерулерді орындаңыз:

1SDK нұсқасын тексеруҚосымшаңызда `console.log(ChaindocEmbed.version)` жүргізіңіз. Егер нұсқа нөмірі шықса, пакет дұрыс орнатылған.

2API байланысын тексеруBackend-ден `chaindoc.healthCheck()` шақырыңыз. Сәтті жауап secret кілтіңіз жарамды және API қол жетімді дегенді білдіреді.

3Файл жүктеуді сынауКішкентай тест PDF файлын `chaindoc.media.upload()` көмегімен жүктеңіз. Бұл auth, желі және файл өңдеудің жұмыс істейтінін растайды.

4Қолтаңба UI ашуEmbed SDK инициализациялап, тест сессиясымен `openSignatureFlow()` шақырыңыз. Егер модалдық терезе пайда болса, бәрі дұрыс.

Мәселелерді шешу

«Module not found» қатесі

Бұл әдетте пакет дұрыс орнатылмаған немесе кэшталған нұсқа қайшылығы бар дегенді білдіреді. Барлығын тазалап, қайта орнатыңыз:

terminal
# npm
rm -rf node_modules package-lock.json
npm install

# yarn
rm -rf node_modules yarn.lock
yarn install

TypeScript тип қателері

Node.js типтері орнатылғанын және `tsconfig.json` дұрыс module resolution қолданатынын тексеріңіз. Көптеген мәселелер сәйкес келмейтін `moduleResolution` параметрлерінен келеді.

terminal
npm install --save-dev @types/node

API кілт қателері

Егер 401 немесе 403 жауаптарын аласыз, мыналарды тексеріңіз:

  • 401 Unauthorized - кілт жарамсыз немесе мерзімі біткен. Dashboard-та қайта жасаңыз.
  • 403 Forbidden - жоспарыңызда API кіруі жоқ. Business жоспары қажет.
  • Дұрыс кілт түрін қолданыңыз: `pk_` кілттері Embed SDK үшін (frontend), `sk_` кілттері Server SDK үшін (backend). Араластыру - ең жиі қателік.
  • Test кілттері (`_test_`) тек sandbox-та жұмыс істейді. Live кілттері (`_live_`) production-ға барады.

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

SDK орнатылды, енді келесі қадамды таңдаңыз:

  • Quick start — 10 минутта алғашқы қолтаңба сұранысын жіберу
  • API documentation — толық endpoint анықтамасы және мысалдар
  • SDKs — кеңейтілген SDK мүмкіндіктері және әр framework нұсқаулықтары
  • Webhooks — нақты уақытта оқиға хабарламаларын баптау
  • Security best practices — өндіріске шығармас бұрын не баптау керек