Chaindoc logoChaindoc

Chaindoc REST API Reference

Vollständige Endpoint-Referenz für die Chaindoc REST API. Hier ist das Ding: Du bekommst alles von Authentifizierung bis Blockchain-Verifizierung. Ehrlich gesagt, damit baust du komplette Workflows.

Übersicht

Mit der API greifst du programmatisch auf alles in Chaindoc zu: Dokumente, Signaturen, Blockchain-Verifizierung und Team-Management. Sie ist für Server-zu-Server-Nutzung gebaut und unterstützt sowohl Public als auch Secret API Keys.

  • Dokumente — Erstelle, aktualisiere und verifiziere Dokumente auf der Blockchain
  • Signaturen — Sende Signaturanfragen und verfolge den Abschluss
  • Media — Lade PDFs, Bilder und Videos hoch (max. 10 pro Request)
  • Embedded Sessions — Erstelle Signing Sessions für dein Frontend (nutzt das Embed SDK)
  • KYC — Teile und verifiziere Identitätsdaten über die Sumsub-Integration

Authentifizierung

Jeder Request braucht einen API Key im Authorization Header. Es gibt zwei Typen:

Key-Typen

  • Public Key (`pk_`) — Read-only, sicher für Frontend-Code
  • Secret Key (`sk_`) — Full read/write, nur fürs Backend. Niemals im Client-Code exposen.

Keys bekommen

1Business Plan abonnierenNur Business Plan Nutzer können API Keys erstellen

2Zu API Access navigierenGehe zu Einstellungen → API Access in deinem Dashboard

3API Key erstellenKlicke den Create API Key Button

4Sicher speichernSpeichere den Secret Key sicher (wird nur einmal angezeigt)

API Keys verwenden

Füge deinen API Key im Authorization Header mit Bearer-Authentifizierung hinzu:

terminal
curl -X GET https://api.chaindoc.io/api/v1/me \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Rate Limiting

API Endpoints sind rate-limited, um Missbrauch zu verhindern. Die Limits variieren je nach Endpoint-Typ.

  • General endpoints: 3 Requests pro 10 Sekunden
  • Media Upload: 3 Requests pro 10 Sekunden
  • OTP Verifizierung: 5 Requests pro 60 Sekunden
  • Read-Operationen: 10 Requests pro 60 Sekunden
  • Signatur-Erstellung: 20 Requests pro 3 Sekunden

Wenn das Limit überschritten wird, bekommst du eine 429 Too Many Requests Response. Rate Limit Headers sind in allen Responses enthalten:

terminal
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1640000000

Fehlerbehandlung

HTTP Status Codes

  • 200 - Success
  • 201 - Resource erfolgreich erstellt
  • 400 - Bad request (Validierungsfehler)
  • 401 - Unauthorized (ungültiger oder fehlender API Key)
  • 403 - Forbidden (unzureichende Berechtigungen)
  • 404 - Resource nicht gefunden
  • 429 - Too many requests (Rate Limit überschritten)
  • 500 - Internal server error

Error Response Format

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

General API

API Key Info abrufen

Informationen zum aktuellen API Key abrufen.

GET /me

Authorization: Bearer sk_live_xxxxx

Health Check

API-Konnektivität und Key-Gültigkeit prüfen.

GET /health

Authorization: Bearer sk_live_xxxxx

Documents API

Dokument erstellen

Erstelle ein neues Dokument mit Blockchain-Verifizierung. Wenn der Status auf 'published' gesetzt wird, wird das Dokument automatisch auf der Blockchain verifiziert.

POST /documents

Headers:
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Dokument aktualisieren

Aktualisiere ein Dokument durch Erstellen einer neuen Version. Vorherige Versionen werden für den Audit Trail aufbewahrt.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Dokument-Zugriffsrechte aktualisieren

Dokument-Zugriffskontrolleinstellungen aktualisieren.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Dokument verifizieren

Verifiziere die Dokumenten-Authentizität über Blockchain. Gibt den Verifizierungsstatus mit Transaction Hash und Chain ID zurück.

POST /documents/verify

{
  "versionHash": "0x123abc...",
  "certificateHash": "0x456def..."
}

Verifizierungsstatus abrufen

Blockchain-Verifizierungsstatus für eine Dokumentenversion abrufen.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

Signatures API

Signaturanfrage erstellen

Erstelle eine Signaturanfrage für einen oder mehrere Empfänger. Aktiviere Embedded Flow für Frontend-Integration.

curl -X POST https://api.chaindoc.io/api/v1/signatures/requests \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "f0b7721f-0399-4035-9b69-7b95d3a367f0",
    "recipients": [{"email": "signer@example.com"}],
    "deadline": "2024-12-31T23:59:59Z",
    "embeddedFlow": true
  }'

Signaturanfrage-Status abrufen

Prüfe den Status einer Signaturanfrage und sieh nach, welche Unterzeichner fertig sind.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Dokument signieren

Ein Dokument signieren (wenn API Key Besitzer ein Unterzeichner ist).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Nutzer-Signaturen abrufen

Alle Signaturen für den authentifizierten Nutzer abrufen.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Signaturanfragen abrufen

Alle Signaturanfragen für den authentifizierten Nutzer mit Pagination-Unterstützung.

GET /signatures/requests?pageNumber=1&pageSize=10

Authorization: Bearer sk_live_xxxxx

Media Upload API

Lade Dateien für die Nutzung bei der Dokumentenerstellung hoch. Unterstützt PDF, Bilder und Videos. Maximal 10 Dateien pro Request.

curl -X POST https://api.chaindoc.io/api/v1/media/upload \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -F "media=@contract.pdf"

KYC API

KYC-Daten teilen

Teile KYC (Know Your Customer) Daten mit Empfängern zur Identitätsverifizierung.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Embedded Sessions API

Erstelle Embedded Sessions für Dokumentensignatur in deiner Frontend-Anwendung. Sessions sind 10 Minuten gültig.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Das Wichtigste als Nächstes

  • API-Integration — bewährte Patterns, Best Practices und vollständige Workflow-Beispiele
  • SDKs — Server SDK und Embed SDK mit framework-spezifischen Guides
  • Webhooks — Echtzeit-Event-Benachrichtigungen einrichten
  • Installation — npm Setup für alle unterstützten Frameworks
  • Sicherheit — API-Key-Management und Compliance