Schnellstart-Anleitung

Mach mit Chaindoc in unter 10 Minuten startklar. Diese Anleitung zeigt dir sowohl die Web-Oberfläche als auch die API – du entscheidest, welcher Weg besser passt.

Signieren über die Web-Oberfläche

Für deine erste Signaturanfrage brauchst du keinen Code. Die Web-App erledigt alles: Upload, Empfänger, Signatur-Flow und blockchain-basierte Verifikation.

Schritt für Schritt: deine erste Signatur

Du willst die verschiedenen Signatur-Typen verstehen (einfach, fortgeschritten, qualifiziert)? Das ist wichtig für Compliance. Die meisten Geschäftsverträge funktionieren mit einfachen E-Signaturen, aber regulierte Branchen brauchen oft fortgeschrittene oder qualifizierte.

Integration über die API

Wenn du das Signieren in deine eigene App einbaust, nutzt du die REST API und TypeScript SDKs. Der Flow ist derselbe wie bei der Web-Oberfläche, nur automatisiert.

1. API-Keys holen

API-Zugriff erfordert einen Business-Plan. Gehe in deinem Dashboard zu Einstellungen > API-Zugriff und erstelle zwei Keys:

• Public Key (`pk_`) für Frontend-Nutzung mit dem Embed SDK
• Secret Key (`sk_`) für Backend-Nutzung mit dem Server SDK. Halte diesen außerhalb von Client-seitigem Code.

2. SDK installieren

Wähle das SDK, das zu deinem Anwendungsfall passt. Die meisten Apps brauchen beides: das Server SDK für Dokumenterstellung und das Embed SDK für die Signatur-UI.

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

Für detaillierte Framework-Setup (React, Vue, Angular, Next.js) schau in die Installationsanleitung.

3. Dokument hochladen und erstellen

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

Das Setzen von `status: 'published'` löst automatisch die Blockchain-Verifikation aus. Wenn du warten willst, nutze `'draft'` und veröffentliche später.

4. Signaturanfrage erstellen

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

Setze `embeddedFlow: true`, wenn du die Signatur-UI innerhalb deiner App anzeigen willst. Ohne das bekommen die Unterzeichner einen Link zur gehosteten Chaindoc-Signaturseite.

5. Signatur-Oberfläche anzeigen (Frontend)

Das ist optional. Wenn du `embeddedFlow: true` gesetzt hast, kannst du die Signatur-UI direkt in deiner App öffnen. Erstelle zuerst eine Session im Backend, dann übergib die Session-ID an das Frontend.

// 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. Status prüfen und auf Events lauschen

Du kannst den Status pollen, aber Webhooks sind die bessere Option für Production. Sie benachrichtigen deinen Server sofort, wenn etwas passiert.

// 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 einrichten (empfohlen)

Webhooks pushen Events in Echtzeit an deinen Server, sodass du nicht ständig prüfen musst. Hier ist ein einfacher Express-Handler:

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

In Production solltest du Webhook-Signaturen mit HMAC verifizieren, um sicherzustellen, dass das Payload tatsächlich von Chaindoc kommt. Der Webhooks-Guide behandelt das im Detail.

Komplettes Workflow-Beispiel

Das hier fasst alles zusammen: Upload, Erstellung, Signieren, Verifikation. Kopiere es, tausche deine API-Keys ein, und du hast einen funktionierenden Prototypen.

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

Wie es weitergeht

Jetzt, wo du die Grundlagen drauf hast, hier sind die nächsten Schritte je nachdem, was du baust:

• Installation — Framework-spezifisches Setup für React, Vue, Angular und Next.js
• API-Dokumentation — vollständige Endpoint-Referenz mit Request/Response-Beispielen
• SDKs — Server SDK und Embed SDK mit Framework-spezifischen Integrationsanleitungen
• Webhooks — Echtzeit-Event-Benachrichtigungen für Production-Apps
• Security Best Practices — was du vor dem Live-Gang absichern solltest

Häufige Fragen

Wie lange dauert die Blockchain-Verifikation?

Normalerweise 1-5 Minuten, je nach Netzwerk. Dein Dokument ist aber sofort verfügbar. Die Verifikation läuft im Hintergrund und du bekommst ein Webhook-Event, wenn sie fertig ist.

Kann ich die API ohne Bezahlung testen?

Der kostenlose Plan gibt dir Zugriff auf die Web-Oberfläche. API-Zugriff braucht einen Business-Plan, aber die Sandbox-Umgebung lässt dich alles testen, ohne echte Daten zu beeinflussen oder Quota zu verbrauchen.

Sind diese Signaturen rechtlich bindend?

Ja. Chaindoc-Signaturen entsprechen eIDAS in Europa, dem ESIGN Act und UETA in den USA sowie äquivalenten Vorschriften in den meisten anderen Ländern. Die Blockchain-Verifikation fügt eine zusätzliche Beweisebene hinzu, die bei Streitigkeiten relevant sein kann. Siehe die Signatures-Dokumentation für Details, welcher Signatur-Typ deinen Compliance-Anforderungen entspricht.

Welche Dateiformate kann ich hochladen?

PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, JPG, PNG, GIF, WEBP, SVG, MP4, AVI, MOV und WMV. Maximale Dateigröße ist 50MB.