API-Integration

Integrier Chaindoc mit unserer leistungsstarken REST-API und SDKs in deine Anwendungen. Automatisier Dokumenten-Workflows, sammle Unterschriften und synchronisier Ereignisse in Echtzeit.

Überblick

Chaindoc bietet eine umfassende REST-API, mit der du benutzerdefinierte Workflows für die Dokumentenunterzeichnung erstellen, Prozesse automatisieren und in deine bestehenden Systeme integrieren kannst. Die API ist für Entwickler konzipiert und bietet vollständige TypeScript-Unterstützung sowie automatische Wiederholungsversuche.

Erste Schritte

1. API-Zugriff erhalten

2. Wähl die Integrationsmethode aus.

Chaindoc bietet drei Integrationsansätze:

• REST-API – Direkte HTTP-Anfragen für maximale Flexibilität
• Server SDK – Typsicheres Node.js SDK mit automatischen Wiederholungsversuchen (@chaindoc_io/server-sdk)
• Embed SDK – Frontend-Signatur-Schnittstelle für Web-Apps (@chaindoc_io/embed-sdk)

3. Kurzes Beispiel

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

Kernkonzepte der API

Authentifizierung

Alle API-Anfragen brauchen eine Authentifizierung mit API-Schlüsseln im Authorization-Header:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

• Öffentliche Schlüssel (pk_) – Nur-Lese-Zugriff für Frontend-Anwendungen
• Geheime Schlüssel (sk_) – Vollständiger Lese-/Schreibzugriff für Backend-Server
• Testschlüssel (pk_test_, sk_test_) – Für Staging/Entwicklung
• Live-Schlüssel (pk_live_, sk_live_) – Für die Produktion

Ratenbeschränkungen

API-Endpunkte haben Nutzungsbeschränkungen, um eine faire Nutzung sicherzustellen:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000

• Allgemeine Endpunkte: 3 Anfragen pro 10 Sekunden
• Medien-Upload: 3 Anfragen pro 10 Sekunden
• Lesevorgänge: 10 Anfragen pro 60 Sekunden
• Erstellung von Signaturen: 20 Anfragen pro 3 Sekunden

Fehlerbehandlung

Die API gibt Standard-HTTP-Statuscodes mit detaillierten Fehlermeldungen zurück:

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

Gängige Integrationsmuster

Ablauf für das Hochladen und Unterzeichnen von Dokumenten

Nur-Backend-Workflow

Für Fälle, in denen die Unterzeichner deine Benutzeroberfläche nicht nutzen:

// Create signature request with email notifications
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Signers use Chaindoc email links
  message: 'Please review and sign this document',
});

// Chaindoc sends emails to recipients
// Track status via webhooks or API polling

Massenverarbeitung von Dokumenten

// Process multiple documents in batch
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 processed document',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

Erweiterte Funktionen

Webhooks

Erhalte Echtzeit-Benachrichtigungen zu Dokumentereignissen:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', async (req, res) => {
  const event = req.headers['x-webhook-event'];
  
  switch (event) {
    case 'document.verified':
      await handleBlockchainVerification(req.body);
      break;
    case 'signature.request.completed':
      await notifyAllParties(req.body);
      break;
  }
  
  res.status(200).send('OK');
});

KYC-Integration

Integriere Identitätsprüfungen für Workflows mit hohen Sicherheitsanforderungen:

// Create signature request with KYC required
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Optional: pre-verified KYC
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true, // Enforce identity verification
});

Zugriffskontrolle

Verwalte die Berechtigungen für Dokumente mit detaillierter Zugriffskontrolle:

// Update document access rights
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' }, // Team role
  ],
});

Bewährte Vorgehensweisen

• Speichere API-Schlüssel in Umgebungsvariablen, niemals im Code.
• Benutze Testschlüssel für die Entwicklung und Live-Schlüssel für die Produktion.
• Mach ein exponentielles Backoff für die Handhabung von Ratenbeschränkungen.
• Überprüfe Webhook-Signaturen, um Replay-Angriffe zu verhindern.
• Speichere API-Antworten im Cache, wenn es sinnvoll ist.
• Lade Dateien hoch, bevor du Dokumente erstellst, um eine bessere Leistung zu erzielen.
• Verwende Seitenumbrüche für große Datensätze.
• Achte auf Rate-Limit-Header und passe die Anfragehäufigkeit an.

Beispiele für Integrationen

E-Commerce-Plattform

Erstell und unterschreib automatisch Kaufverträge für hochwertige Bestellungen.

HR-System

Integriere das System in dein HRIS, damit Arbeitsverträge beim Onboarding automatisch unterschrieben werden können.

CRM-Integration

Erstell Unterschriftsanfragen direkt aus Kundendatensätzen in Salesforce, HubSpot oder einem benutzerdefinierten CRM.

Dokumentenmanagementsystem

Füge eine Blockchain-Verifizierung zum bestehenden DMS hinzu, um manipulationssichere Prüfpfade zu bekommen.

Ressourcen

• API-Dokumentation – Vollständige REST-API-Referenz mit allen Endpunkten
• SDKs – Dokumentation zu Server-SDK und Embed-SDK mit Framework-Beispielen
• Webhooks – Anleitung zum Einrichten von Echtzeit-Ereignisbenachrichtigungen
• Schnellstart – Lass deine erste Integration in 10 Minuten laufen.
• GitHub-Beispiele – Beispielintegrationen und Codeausschnitte