API-Aufrufe

Übersicht

Diese Seite beschreibt die verfügbaren API-Endpunkte für das Signatursystem. Zu jedem Endpunkt gibt es eine kurze Erklärung, die erforderlichen Eingaben, das erwartete Ergebnis sowie Beispiel-Requests und -Responses im JSON-Format.

Hinweis zu Datentypen:

• Datumsangaben als ISO-8601, z. B. 2025-12-31T23:59:59Z.
• IDs und Tokens sind Strings.

Anfragestruktur

Die anolink API ist eine REST‑Schnittstelle. Anfragen erfolgen immer über HTTPS und werden mit einem Bearer‑Token autorisiert. Nutzdaten werden als JSON übertragen.

HTTP‑Basis

• Methode: GET, POST, PUT, PATCH, DELETE
• URL: <BASE_URL>/…
• Header:
  • Authorization: Bearer <TOKEN>
  • Content-Type: application/json
  • Accept: application/json

Beispiel (Schema)

POST /resource HTTP/1.1
Host: <BASE_URL>
Authorization: Bearer <TOKEN>
Content-Type: application/json
Accept: application/json

{ /* JSON‑Body entsprechend der Endpunktbeschreibung */ }

Antworten

• Erfolg: Status 2xx mit JSON‑Body laut Endpunktbeschreibung
• Fehler: Status 4xx/5xx mit einheitlicher Struktur

{
  "error": {
    "code": "invalid_request",
    "message": "Feld 'patient_id' fehlt",
    "details": { "field": "patient_id" }
  }
}

Hinweise:

• HTTPS ist verpflichtend.
• Zeitangaben im ISO‑8601‑Format.
• GET ist idempotent; schreibende Aufrufe ändern Ressourcen gemäß Payload.

Signaturauftrag erstellen

POST /signature-requests – Erstellt einen neuen Signaturauftrag.

{
  "patient_id": "pat_123",
  "document_id": "doc_456",
  "institution_id": "inst_789",
  "expiration_date": "2025-12-31T23:59:59Z",
  "order_by": "operator@example.com"
}

{
  "signing_link": "https://example.com/signatures/start?token=abc123",
  "signature_id": "sig_00112233",
  "expiration_date": "2025-12-31T23:59:59Z"
}

Offene Signaturlinks abrufen

GET /signature-requests?patient_id=... – Liefert offene Signaturlinks eines Patienten.

GET /signature-requests?patient_id=pat_123

[
  {
    "document_id": "doc_456",
    "document_title": "Einwilligungserklärung",
    "signing_link": "https://example.com/signatures/start?token=def456",
    "status": "pending",
    "expiration_date": "2025-12-15T23:59:59Z"
  }
]

Abgeschlossene Vorgänge abrufen

GET /signature-requests/completed?patient_id=... – Liefert abgeschlossene Signaturvorgänge.

GET /signature-requests/completed?patient_id=pat_123

[
  {
    "signature_id": "sig_00112233",
    "signed_pdf_url": "https://example.com/files/signed/sig_00112233.pdf",
    "metadata_json_url": "https://example.com/files/metadata/sig_00112233.json",
    "timestamp": "2025-10-01T10:30:00Z"
  }
]

Zugriff auf Signaturportal prüfen

POST /signature-requests/verify-session – Prüft, ob ein Besucher über das Patientenportal zum Signaturportal weitergeleitet werden darf. Es werden ausschließlich HTTPS‑Anfragen akzeptiert. Details zum Zugriff: /docs/api/signaturportal/aufruf

{
  "patient_id": "pat_123",
  "signature_id": "sig_00112233",
  "session_token": "sess_7f9c2e"
}

{
  "valid": true,
  "redirect_url": "https://example.com/signature-portal/sig_00112233",
  "session_token": "sess_7f9c2e"
}

Design für das Signaturportal festlegen

POST /design (erstellen), PUT /design (ändern) – Speichert Branding/Design-Einstellungen.

{
  "institution_id": "inst_789",
  "logo_url": "https://example.com/assets/logo.png",
  "design_parameters": {
    "primaryColor": "#0ea5e9",
    "accentColor": "#111827",
    "font": "League Spartan"
  }
}

{
  "message": "saved succesfully!"
}

Dokument mit Signaturfeld anlegen

POST /documents – Legt ein Dokument an (inkl. Signaturfelddefinition).

{
  "document_name": "Einwilligungserklärung",
  "document_description": "Standardformular zur Einwilligung",
  "account_name": "praxis-dr-schmidt",
  "signingfield_koordinates": { "page": 1, "x": 100, "y": 200, "width": 180, "height": 50 },
  "document_bloburl": "https://storage.example.com/docs/template-123.pdf"
}

{
  "document_name": "Einwilligungserklärung",
  "document_id": "doc_456",
  "document_bloburl": "https://storage.example.com/docs/template-123.pdf"
}

Assignment aktualisieren (Entwurf/Aktiv)

PUT /assignments/{id} – Aktualisiert eine Zuteilung. Mit dem Status draft wird die Zuteilung beim Abfragen offener Links nicht gezeigt; mit active wieder sichtbar.

{
  "id": "asg_123",
  "status": "draft",
  "expiration_timestamp": "2026-01-31T23:59:59Z"
}

{
  "id": "asg_123",
  "status": "draft",
  "expiration_timestamp": "2026-01-31T23:59:59Z"
}

Dokument aktualisieren (Felddefinitionen)

PUT /documents/{id} – Ändert Felder/Metadaten eines Dokuments. Änderungen gelten für alle Zuteilungen, die noch nicht gestartet wurden; laufende/abgeschlossene Vorgänge bleiben unverändert.

{
  "document_id": "doc_456",
  "title": "Einwilligungserklärung v2",
  "fields": {
    "signature": { "page": 1, "x": 120, "y": 220, "width": 180, "height": 48 }
  }
}

{
  "id": "doc_456",
  "modified": true
}

Dokument löschen

DELETE /documents/{id} – Löscht ein Dokument. Nur möglich, wenn keine Zuteilungen zugeordnet sind.

{
  "deleted": false,
  "reason": "document has assignments"
}

Verfügbarkeit eines Dokuments setzen

PATCH /documents/{id}/availability – Steuert, ob ein Dokument für neue Zuteilungen nutzbar ist: draft, active oder inactive.

{
  "availability": "inactive"
}

{
  "id": "doc_456",
  "availability": "inactive"
}