Chaindoc logoChaindoc

Kurulum

Chaindoc SDK'lerini projenize ekleyin. İki paket bulunmaktadır: backend işlemleri için Server SDK (dokümanlar, imzalar, doğrulama) ve ön yüzünüze imza arayüzü entegre etmek için Embed SDK.

Başlamadan önce

Henüz bir hesabınız yoksa, hesap oluşturmak için hızlı başlangıç rehberi ile başlayın.

Server SDK

Server SDK, backend'deki tüm işlemleri yönetir: doküman oluşturma, imza istekleri gönderme, takım yönetimi ve blockchain doğrulama tetikleme. REST API etrafında ince bir wrapper'dır, bu yüzden API dokümanlarını okuduysanız, metod isimleri tanıdık gelecektir.

Paketi yükleyin

npm install @chaindoc_io/server-sdk

Ortam değişkenlerini ayarlayın

Proje kök dizininde bir `.env` dosyası oluşturun. Burada secret key'e ihtiyacınız olacak.

.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'yı başlatın

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',
  },
});

Temel yapılandırma çoğu proje için yeterlidir. Toplu doküman işleme yapıyorsanız, API rate limitleri olduğundan retry ayarlarını ayarlamaya değer.

Bağlantınızı doğrulayın

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');
}

Bu başarısız olursa, secret key'inizin `sk_live_` (production) veya `sk_test_` (sandbox) ile başladığından emin olun. En yaygın sorun, yanlışlıkla public key kullanmaktır.

Embed SDK

Embed SDK, Chaindoc imza arayüzünü web uygulamanızın içinde göstermenizi sağlar. Kullanıcılarınız sitenizden ayrılmadan doküman imzalayabilir. React, Vue, Angular veya düz JavaScript ile çalışır.

Paketi yükleyin

npm install @chaindoc_io/embed-sdk

CDN seçeneği, hızlı prototipler veya build adımı olmayan siteler için kullanışlıdır. Production için npm paketini kullanın, böylece tree-shaking ve uygun versiyon kontrolü elde edersiniz.

Ortam değişkenlerini ayarlayın

Embed SDK, client-side kodda güvenle dahil edilebilen public key (`pk_`) kullanır.

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

Uygulamanızda başlatın

// 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-spesifik kurulum

Bu örnekler, Embed SDK'nin her framework'te provider veya servis olarak nasıl bağlanacağını gösterir. Backend'de Server SDK kullanıyorsanız, provider'a ihtiyacınız yoktur; sadece ihtiyacınız olan yerde import edin.

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 yapılandırması

Her iki SDK de tam TypeScript tanımlamaları ile birlikte gelir. Ekstra `@types` paketlerine ihtiyacınız yoktur.

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

Eski bir TypeScript kurulumu (< 5.0) kullanıyorsanız, `"bundler"` yerine `"moduleResolution": "node"` kullanın.

Geliştirme vs. production

Gerçek dokümanlar oluşturmaktan veya gerçek alıcılara imza e-postaları göndermekten kaçınmak için geliştirme sırasında test anahtarları kullanın.

Geliştirme kurulumu

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` flag'i, istek/yanıt detaylarını konsola yazdırır. Gürültülüdür, ama bir şeyin neden çalışmadığını anlamaya çalışırken kullanışlıdır.

Production kurulumu

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',
});

Kurulumunuzu doğrulayın

Her şeyin doğru bağlandığından emin olmak için bu kontrolleri yapın:

1SDK versiyonunu kontrol edinUygulamanızda `console.log(ChaindocEmbed.version)` çalıştırın. Bir versiyon numarası yazdırırsa, paket doğru yüklenmiştir.

2API bağlantısını test edinBackend'den `chaindoc.healthCheck()` çağırın. Başarılı bir yanıt, secret key'inizin geçerli olduğu ve API'ye erişilebildiği anlamına gelir.

3Dosya yüklemeyi deneyin`chaindoc.media.upload()` ile küçük bir test PDF'i yükleyin. Bu, auth, ağ ve dosya işlemenin çalıştığını doğrular.

4İmza arayüzünü açınEmbed SDK'yı başlatın ve test oturumu ile `openSignatureFlow()` çağırın. Modal görünürse, hazırsınız demektir.

Sorun giderme

"Module not found" hatası

Bu genellikle paketin düzgün yüklenmemesi veya önbellekte bir versiyon çakışması olduğu anlamına gelir. Her şeyi temizleyip yeniden yükleyin:

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

# yarn
rm -rf node_modules yarn.lock
yarn install

TypeScript tip hataları

Node.js tiplerinin yüklü olduğundan ve `tsconfig.json`'unuzun doğru module resolution kullandığından emin olun. Çoğu sorun, eşleşmeyen `moduleResolution` ayarlarından kaynaklanır.

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

API key hataları

401 veya 403 yanıtları alıyorsanız, şunları kontrol edin:

  • 401 Unauthorized, anahtarın geçersiz veya süresi dolmuş olduğu anlamına gelir. Dashboard'dan yeniden oluşturun.
  • 403 Forbidden, planınızın API erişimi içermediği anlamına gelir. Business planına ihtiyacınız var.
  • Doğru key tipini kullandığınızdan emin olun: `pk_` anahtarları Embed SDK (frontend) için, `sk_` anahtarları Server SDK (backend) içindir. Bunları karıştırmak en yaygın hatadır.
  • Test anahtarları (`_test_`) sadece sandbox'ta çalışır. Live anahtarları (`_live_`) production'a bağlanır.

Sıradaki adımlar

SDK'ler yüklendiğine göre, bir sonraki adımınızı seçin: