Chaindoc logoChaindoc

API-Integration

Mit der Chaindoc REST API automatisierst du Dokumenten-Workflows, sammelst Signaturen und synchronisierst Events in Echtzeit. Hier ist das Ding: Das ist genau dieselbe API, die auch unsere Web-App antreibt.

Was du mit der API machen kannst

Die API gibt dir programmatischen Zugriff auf alles, was Chaindoc kann: Dokumente hochladen, Signaturanfragen erstellen, Teams verwalten und via Webhooks auf Events lauschen. Ehrlich gesagt, das ist dieselbe API, die auch unsere Web-App antreibt.

Drei Wege zur Integration

Wähl den, der zu deinem Stack passt. Die meisten Production-Apps nutzen das Server SDK im Backend und das Embed SDK im Frontend.

  • REST API — direkte HTTP-Requests, funktioniert mit jeder Sprache. Maximale Flexibilität.
  • Server SDK — type-sicherer Node.js-Wrapper mit automatischen Retries und Error Handling (`@chaindoc_io/server-sdk`)
  • Embed SDK — integriert eine Signing-Oberfläche direkt in deine Web-App, ohne dass Nutzer deine Seite verlassen (`@chaindoc_io/embed-sdk`)

Falls du die SDKs noch nicht installiert hast, die Installationsanleitung zeigt dir das npm-Setup für React, Vue, Angular und Next.js.

Schnelles Beispiel

Hier ist derselbe "Dokument erstellen"-Aufruf in drei Varianten. Die SDK-Version ist am kürzesten, aber der raw REST-Call zeigt genau, was über die Leitung geht.

curl -X POST https://api.chaindoc.io/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vertrag",
    "description": "Dienstleistungsvereinbarung",
    "status": "published",
    "hashtags": ["#vertrag"],
    "meta": []
  }'

Authentifizierung

Jeder Request braucht einen API-Key im Authorization-Header:

terminal
Authorization: Bearer sk_live_xxxxxxxxxxxxx

Es gibt zwei Key-Typen — die zu verwechseln ist der häufigste Integration-Fehler:

  • Public Keys (`pk_`) — nur lesend, sicher für Frontend-Code
  • Secret Keys (`sk_`) — vollständiger Lese-/Schreibzugriff, nur fürs Backend. Niemals im Client-Code exposen.
  • Beide gibt's als Test- (`_test_`) und Live-Varianten (`_live_`). Test-Keys landen in der Sandbox.

Rate Limits

Die API liefert Rate-Limit-Infos in den Response-Headers. Wenn du am Limit bist, bekommst du einen 429er. Warte kurz und versuch's nochmal.

terminal
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000
  • Allgemeine Endpoints: 3 Requests pro 10 Sekunden
  • Media-Upload: 3 Requests pro 10 Sekunden
  • Leseoperationen: 10 Requests pro 60 Sekunden
  • Signatur-Erstellung: 20 Requests pro 3 Sekunden

Das Server SDK handhabt Retries automatisch mit exponentiellem Backoff. Wenn du raw HTTP nutzt, musst du die Retry-Logik selbst bauen.

Error Handling

Errors kommen als JSON mit Status-Code, Message und (bei Validation-Errors) einer Liste spezifischer Feld-Probleme:

terminal
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "name",
      "message": "name must be a string"
    }
  ]
}

Häufige Status-Codes: 400 (bad request), 401 (invalid key), 403 (Plan beinhaltet keine API), 404 (not found), 429 (rate limited), 500 (server error). Bei 5xx-Fehlern: Mit Backoff retryen.

Häufige Integrations-Patterns

Vollständiger Signing-Flow (embedded)

Das am häufigsten genutzte Pattern: Dokument hochladen, zur Unterschrift senden und die Signing-UI direkt in deiner App anzeigen.

1Datei hochladenPOST /media/upload — schick das PDF, Office-Dokument oder Bild.

2Dokument erstellenPOST /documents — setz status='published', um die Blockchain-Verifizierung zu triggern.

3Signaturanfrage erstellenPOST /signatures/requests — füg Empfänger hinzu, setz Signing-Order und Deadline.

4Embedded Session erstellenPOST /embedded/sessions — das gibt dir eine sessionId für jeden Signer.

5Signing-UI öffnenÜbergib die sessionId an die openSignatureFlow()-Methode vom Embed SDK.

6Auf Abschluss wartenRicht einen Webhook für das signature.request.completed Event ein, oder poll GET /signatures/requests/:id/status.

Der Quick-Start-Guide hat den kompletten Code für diesen Flow.

E-Mail-basiertes Signing (ohne Embed)

Wenn Signer deine App nicht nutzen, setz `embeddedFlow: false`. Chaindoc schickt ihnen dann eine E-Mail mit Signing-Link. Du bekommst trotzdem Webhook-Notifications, wenn sie signieren.

terminal
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Signer bekommen E-Mail-Links
  message: 'Bitte prüf und signier dieses Dokument',
});

Bulk-Dokumenten-Verarbeitung

Für Batch-Imports: Loop durch deine Dateien und lad jedes einzeln hoch. Achte aber auf die Rate Limits. Wenn du hunderte Dokumente verarbeitest, füg eine kurze Verzögerung zwischen den Requests ein oder nutz die eingebaute Retry-Logik vom SDK.

terminal
const documents = ['doc1.pdf', 'doc2.pdf', 'doc3.pdf'];

for (const file of documents) {
  const buffer = await readFile(file);
  const blob = new Blob([buffer], { type: 'application/pdf' });
  
  const { media } = await chaindoc.media.upload([blob]);
  
  await chaindoc.documents.create({
    name: file,
    description: 'Batch-verarbeitetes Dokument',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

KYC-Integration

Für High-Security-Workflows kannst du Identity Verification vor dem Signieren verlangen. Chaindoc integriert mit Sumsub für KYC. Setz `isKycRequired: true` auf der Signaturanfrage, dann müssen Signer erst durch die Identity-Verifizierung, bevor sie unterschreiben können.

terminal
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Optional: bereits verifiziert
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true,
});

Zugriffskontrolle via API

Du kannst Dokumenten-Berechtigungen programmatisch setzen. Beschränk den Zugriff auf bestimmte E-Mails oder Team-Rollen:

terminal
await chaindoc.documents.updateRights(documentId, {
  accessType: 'restricted',
  accessEmails: [
    { email: 'viewer@company.com', level: 'read' },
    { email: 'editor@company.com', level: 'write' },
  ],
  accessRoles: [
    { roleId: 1, level: 'read' },
  ],
});

Best Practices

  • API-Keys in Umgebungsvariablen halten. Niemals ins Version Control committen.
  • Test-Keys (`sk_test_`) für die Entwicklung nutzen. Live-Keys (`sk_live_`) landen im Production-System.
  • Exponentiellen Backoff für 429-Responses implementieren. Das SDK macht das automatisch.
  • Webhook-Signatures mit HMAC verifizieren, um Replay-Attacken zu verhindern.
  • Dateien vor dem Dokument-Erstellen hochladen. Die API braucht die Media-ID vom Upload-Schritt.
  • Pagination für Listen-Endpoints nutzen. Nicht alles auf einmal fetchen.
  • Vor dem Go-Live den Security-Guide checken.

Beispiel-Use-Cases

Ein paar reale Patterns, die Teams mit der API bauen:

  • E-Commerce — Kaufverträge für High-Value-Bestellungen automatisch generieren und beim Checkout zum Unterschicken senden
  • HR-Onboarding — Arbeitsverträge aus Templates erstellen und neuen Mitarbeitern am ersten Tag zuschicken
  • CRM-Integration — Signaturanfragen aus Salesforce- oder HubSpot-Deal-Records triggern
  • Dokumentenarchivierung — Blockchain-Verifizierung zu Dokumenten in deinem bestehenden Storage-System hinzufügen

Was als Nächstes?

  • API-Dokumentation — komplette Endpoint-Referenz mit Request/Response-Beispielen
  • SDKs — Server SDK und Embed SDK mit framework-spezifischen Guides
  • Webhooks — Echtzeit-Event-Notifications einrichten
  • Quick Start — deine erste Integration in 10 Minuten zum Laufen bringen
  • Installation — npm-Setup für alle unterstützten Frameworks