Dokumentensignatur

Die Signing API ermöglicht das Erstellen von Signatur-Umschlägen für Akten, das Überführen von Dokumenten in Umschläge und die Nachverfolgung des Signatur-Lebenszyklus. Externe Unterzeichner erhalten Magic-Link-E-Mails zum Signieren ohne Optimaite-Konto.

Endpunkte

Method	Path	Beschreibung
GET	/api/v1/cases/{case_id}/signed-documents	Signatur-Umschläge einer Akte auflisten
POST	/api/v1/cases/{case_id}/signing-envelopes	Signatur-Umschlag erstellen
POST	/api/v1/signing/promote-to-envelope	Dokumente in Entwurfs-Umschlag überführen

Das Signatur-Umschlag-Objekt

{
  "id": "env_01ABCDEFG",
  "case_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Employment Agreement -- Smith",
  "status": "in_progress",
  "documents": [
    {
      "id": "sigdoc_01",
      "document_id": "doc_01ABCDEF",
      "filename": "employment_agreement.pdf"
    }
  ],
  "signers": [
    {
      "id": "signer_01",
      "name": "John Smith",
      "email": "john.smith@example.com",
      "role": "signer",
      "status": "pending",
      "signed_at": null
    }
  ],
  "created_at": "2026-05-20T10:00:00Z",
  "completed_at": null
}

Signatur-Umschlag erstellen

POST /api/v1/cases/{case_id}/signing-envelopes

{
  "title": "Employment Agreement -- Smith",
  "document_ids": ["doc_01ABCDEF"],
  "signers": [
    {
      "name": "John Smith",
      "email": "john.smith@example.com",
      "role": "signer"
    },
    {
      "name": "HR Director",
      "email": "hr@company.de",
      "role": "signer"
    }
  ],
  "signing_order": "sequential",
  "send_emails": true
}

Bei send_emails: true erhält jeder Unterzeichner eine Magic-Link-E-Mail zum Zugriff und Signieren des Dokuments.

Antwort

Liefert 201 Created mit dem vollständigen Umschlag-Objekt.

Dokumente in Umschlag überführen

POST /api/v1/signing/promote-to-envelope

Bestehende Optimaite-Dokumente in einen Entwurfs-Signatur-Umschlag überführen:

{
  "case_id": "550e8400-e29b-41d4-a716-446655440000",
  "document_ids": ["doc_01ABCDEF", "doc_02GHIJKL"],
  "title": "NDA Package"
}

Dies erstellt einen Entwurfs-Umschlag. Unterzeichner hinzufügen und separat senden.

Signierte Dokumente auflisten

GET /api/v1/cases/{case_id}/signed-documents

Liefert alle mit einer Akte verknüpften Signatur-Umschläge inklusive aktuellem Status.

Antwort

{
  "data": [
    {
      "id": "env_01ABCDEFG",
      "title": "Employment Agreement -- Smith",
      "status": "completed",
      "signers": [
        { "name": "John Smith", "status": "signed", "signed_at": "2026-05-21T09:30:00Z" },
        { "name": "HR Director", "status": "signed", "signed_at": "2026-05-22T11:00:00Z" }
      ]
    }
  ]
}

Umschlag-Status-Lebenszyklus

draft -> sent -> in_progress -> completed
                                    \-> expired
                                    \-> declined

Status	Beschreibung
draft	Umschlag erstellt, noch nicht an Unterzeichner gesendet
sent	E-Mails an Unterzeichner versendet
in_progress	Mindestens ein Unterzeichner hat das Dokument geöffnet
completed	Alle Unterzeichner haben signiert
expired	Signaturfrist abgelaufen ohne Abschluss
declined	Ein Unterzeichner hat die Signatur abgelehnt

Fehlerantworten

Status	Code	Bedeutung
400	NO_DOCUMENTS	Keine Dokument-IDs angegeben
400	NO_SIGNERS	Keine Unterzeichner angegeben
403	AUTH_INSUFFICIENT_SCOPE	Fehlender Scope documents:write
404	CASE_NOT_FOUND	Akten-ID existiert nicht
404	DOCUMENT_NOT_FOUND	Eine oder mehrere Dokument-IDs existieren nicht

Nächste Schritte

• Dokumente -- Zu signierende Dokumente verwalten
• Akten -- Umschläge mit Akten verknüpfen
• Parteien -- Kontakte der Unterzeichner verwalten