Przewodnik szybkiego startu

Rozpocznij pracę z Chaindoc w mniej niż 10 minut. Ten przewodnik przeprowadzi Cię przez interfejs webowy oraz API, więc możesz wybrać ścieżkę, która Ci odpowiada.

Podpisywanie przez interfejs webowy

Nie potrzebujesz żadnego kodu, aby wysłać pierwszą prośbę o podpis. Aplikacja webowa obsługuje wszystko: przesyłanie, odbiorców, proces podpisywania i weryfikację blockchain.

Krok po kroku: Twój pierwszy podpis

Chcesz zrozumieć różne typy podpisów (prosty, zaawansowany, kwalifikowany)? To ma znaczenie dla zgodności. Większość umów biznesowych działa dobrze z prostymi podpisami elektronicznymi, ale regulowane branże często wymagają zaawansowanych lub kwalifikowanych.

Integracja przez API

Jeśli budujesz podpisywanie we własnej aplikacji, użyjesz REST API i SDK TypeScript. Przepływ jest taki sam jak w interfejsie webowym, po prostu zautomatyzowany.

1. Uzyskaj klucze API

Dostęp do API wymaga planu Business. Przejdź do Ustawienia > Dostęp API w panelu i utwórz dwa klucze:

• Klucz publiczny (`pk_`) do użytku frontendowego z Embed SDK
• Klucz tajny (`sk_`) do użytku backendowego z Server SDK. Trzymaj ten klucz poza kodem po stronie klienta.

2. Zainstaluj SDK

Wybierz SDK pasujące do Twojego przypadku użycia. Większość aplikacji potrzebuje obu: Server SDK do tworzenia dokumentów i Embed SDK do interfejsu podpisywania.

# Node.js 18+ required
npm install @chaindoc_io/server-sdk

Szczegółowe instrukcje konfiguracji dla frameworków (React, Vue, Angular, Next.js) znajdziesz w przewodniku instalacji.

3. Prześlij i utwórz dokument

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

Ustawienie `status: 'published'` automatycznie uruchamia weryfikację blockchain. Jeśli chcesz poczekać, użyj `'draft'` i opublikuj później.

4. Utwórz prośbę o podpis

// 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);

Ustaw `embeddedFlow: true`, jeśli zamierzasz wyświetlić interfejs podpisywania w swojej aplikacji. Bez tego podpisujący otrzymają link do hostowanej strony podpisywania Chaindoc.

5. Pokaż interfejs podpisywania (frontend)

To jest opcjonalne. Jeśli ustawiłeś `embeddedFlow: true`, możesz otworzyć interfejs podpisywania bezpośrednio w swojej aplikacji. Najpierw utwórz sesję na backendzie, a następnie przekaż ID sesji do frontendu.

// 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. Sprawdź status i nasłuchuj zdarzeń

Możesz odpytywać o status, ale webhooki to lepsza opcja dla produkcji. Powiadomią Twój serwer natychmiast, gdy coś się wydarzy.

// 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. Skonfiguruj webhooki (zalecane)

Webhooki wysyłają zdarzenia do Twojego serwera w czasie rzeczywistym, więc nie musisz ciągle sprawdzać. Oto podstawowy handler 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');
});

W produkcji powinieneś weryfikować podpisy webhooków za pomocą HMAC, aby upewnić się, że payload faktycznie pochodzi z Chaindoc. Przewodnik po webhookach szczegółowo to omawia.

Pełny przykład workflow

To łączy wszystko razem: przesyłanie, tworzenie, podpisywanie, weryfikacja. Skopiuj to, podmień klucze API i masz działający prototyp.

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

Dokąd dalej

Teraz, gdy znasz podstawy, oto co warto zgłębić w zależności od tego, co budujesz:

• Instalacja — konfiguracja specyficzna dla frameworków: React, Vue, Angular i Next.js
• Dokumentacja API — pełna referencja endpointów z przykładami request/response
• SDK — Server SDK i Embed SDK z przewodnikami integracji dla poszczególnych frameworków
• Webhooki — powiadomienia o zdarzeniach w czasie rzeczywistym dla aplikacji produkcyjnych
• Najlepsze praktyki bezpieczeństwa — co zabezpieczyć przed uruchomieniem produkcyjnym

Częste pytania

Ile trwa weryfikacja blockchain?

Zazwyczaj 1-5 minut, w zależności od sieci. Twój dokument jest dostępny od razu. Weryfikacja działa w tle i otrzymasz zdarzenie webhooka, gdy się zakończy.

Czy mogę testować API bez płacenia?

Darmowy plan daje dostęp do interfejsu webowego. Dostęp do API wymaga planu Business, ale środowisko sandbox pozwala testować wszystko bez wpływu na rzeczywiste dane lub zużywania limitu.

Czy te podpisy są prawnie wiążące?

Tak. Podpisy Chaindoc są zgodne z eIDAS w Europie, ESIGN Act i UETA w USA oraz odpowiednimi regulacjami w większości innych jurysdykcji. Weryfikacja blockchain dodaje dodatkową warstwę dowodów, co może mieć znaczenie w sporach. Zobacz dokumentację podpisów, aby dowiedzieć się, który typ podpisu odpowiada Twoim potrzebom zgodności.

Jakie formaty plików mogę przesłać?

PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, JPG, PNG, GIF, WEBP, SVG, MP4, AVI, MOV i WMV. Maksymalny rozmiar pliku to 50MB.