Chaindoc logoChaindoc

Chaindoc REST API-Referenz

Vollständige Referenz für die Integration der REST-API von Chaindoc in deine Anwendungen. Verwalte Dokumente, Signaturen, Blockchain-Verifizierung und eingebettete Signatur-Workflows.

Überblick

Die Chaindoc REST API ermöglicht den programmatischen Zugriff auf Dokumentenmanagement, Blockchain-Verifizierung und digitale Signaturfunktionen. Die API ist für die Server-zu-Server-Integration ausgelegt und unterstützt sowohl öffentliche als auch geheime API-Schlüssel.

Wichtigste Funktionen

  • Dokumentenverwaltung – Erstelle, aktualisiere und verwalte Dokumente mit Blockchain-Verifizierung.
  • Digitale Signaturen – Fordere digitale Signaturen von mehreren Leuten an und sammle sie ein.
  • Blockchain-Verifizierung – Überprüfe die Echtheit von Dokumenten in Blockchain-Netzwerken.
  • Eingebettete Sitzungen – Erstelle sichere Sitzungen für Frontend-Signatur-Workflows.
  • Medien hochladen – Dateien (PDF, Bilder, Videos) für die Dokumentenerstellung hochladen
  • KYC-Integration – Identitätsdaten mit Sumsub teilen und überprüfen

Authentifizierung

Die Chaindoc-API nutzt API-Schlüssel zur Authentifizierung. Es gibt zwei Arten von Schlüsseln mit unterschiedlichen Zugriffsebenen.

API-Schlüsseltypen

  • Öffentlicher Schlüssel (pk_) – Nur-Lesezugriff für Frontend-Apps und Verifizierung
  • Geheimer Schlüssel (sk_) – Vollständiger Lese- und Schreibzugriff für Backend-Server

API-Schlüssel bekommen

1Business Plan abonnierenNur Nutzer des Business-Tarifs können API-Schlüssel erstellen.

2Geh zu „API-Zugriff“.Geh in deinem Dashboard zu „Einstellungen“ → „API-Zugriff“.

3API-Schlüssel erstellenKlick auf die Schaltfläche „API-Schlüssel erstellen“.

4Sicher speichernBewahr den geheimen Schlüssel sicher auf (wird nur einmal angezeigt).

API-Schlüssel verwenden

Füge deinen API-Schlüssel mit Bearer-Authentifizierung in den Authorization-Header ein:

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

Ratenbegrenzung

API-Endpunkte sind mit einer Ratenbegrenzung versehen, um Missbrauch zu verhindern. Die Ratenbegrenzungen variieren je nach Endpunkttyp.

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

Wenn das Ratenlimit überschritten wird, bekommst du eine 429 Too Many Requests-Antwort. Ratenlimit-Header sind in den Antworten enthalten:

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

Fehlerbehandlung

HTTP-Statuscodes

  • 200 – Erfolgreich
  • 201 – Ressource erfolgreich erstellt
  • 400 – Fehlerhafte Anfrage (Validierungsfehler)
  • 401 – Nicht autorisiert (API-Schlüssel ungültig oder fehlt)
  • 403 – Verboten (nicht genug Berechtigungen)
  • 404 – Ressource nicht gefunden
  • 429 – Zu viele Anfragen (Ratenlimit überschritten)
  • 500 – Interner Serverfehler

Format für Fehlermeldungen

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

Allgemeine API

API-Schlüssel-Infos abrufen

Hol dir Infos über den aktuellen API-Schlüssel.

GET /me

Authorization: Bearer sk_live_xxxxx

Gesundheitscheck

Überprüfe die API-Verbindung und die Gültigkeit der Schlüssel.

GET /health

Authorization: Bearer sk_live_xxxxx

Dokumente-API

Dokument erstellen

Erstell ein neues Dokument mit Blockchain-Verifizierung. Wenn der Status auf „veröffentlicht” gesetzt ist, wird das Dokument automatisch in der Blockchain verifiziert.

POST /documents

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

Dokument aktualisieren

Aktualisiere ein Dokument, indem du eine neue Version erstellst. Frühere Versionen werden für die Nachverfolgbarkeit aufbewahrt.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Aktualisiere die Zugriffsrechte für Dokumente.

Aktualisiere die Einstellungen für die Zugriffskontrolle des Dokuments.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Dokument überprüfen

Überprüfe die Echtheit des Dokuments mithilfe der Blockchain. Gibt den Verifizierungsstatus mit Transaktions-Hash und Chain-ID zurück.

POST /documents/verify

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

Überprüfungsstatus abrufen

Hol dir den Blockchain-Verifizierungsstatus für eine Dokumentversion.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

Signaturen-API

Signaturanforderung erstellen

Erstelle eine Signaturanforderung für einen oder mehrere Empfänger. Aktiviere den eingebetteten Flow für die 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
  }'

Status der Signaturanforderung abrufen

Schau nach, wie es um eine Unterschriftsanforderung steht und welche Unterzeichner schon unterschrieben haben.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Dokument unterschreiben

Unterschreib das Dokument (wenn der API-Schlüsselinhaber ein Unterzeichner ist).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Benutzersignaturen abrufen

Hol alle Signaturen für den authentifizierten Benutzer.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Unterschriftsanfragen erhalten

Hol dir alle Signaturanfragen für den authentifizierten Benutzer mit Unterstützung für Paginierung.

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

Authorization: Bearer sk_live_xxxxx

API zum Hochladen von Medien

Lade Dateien hoch, die du für die Dokumenterstellung brauchst. Unterstützt werden PDF-Dateien, Bilder und Videos. Maximal 10 Dateien pro Anfrage.

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

Gib KYC-Daten (Know Your Customer) an die Empfänger weiter, um die Identität zu überprüfen.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

API für eingebettete Sitzungen

Erstelle eingebettete Sitzungen für die Dokumentenunterzeichnung in deiner Frontend-Anwendung. Die Sitzungen sind 10 Minuten lang gültig.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json