sign.fritss.at - Integrationsleitfaden für Kunden

Dieser Leitfaden richtet sich an Entwickler, die ihre eigene Anwendung an die Signatur-API
anbinden. Für die vollständige, interaktive Referenz siehe API-Dokumentation
am Ende.

1. Voraussetzungen

Bevor du Requests schicken kannst, brauchst du von uns:

• einen API-Key (Header X-Api-Key) - wird dir einmalig im Klartext mitgeteilt, danach nicht
  mehr abrufbar. Bei Verlust: neuen Key anfordern, alten sperren lassen.
• deine returnUrl(s) müssen vorab bei uns freigegeben sein (Allowlist, nur HTTPS). Ohne
  Freigabe schlägt die Batch-Erstellung mit einem Validierungsfehler fehl.
• falls du Webhooks nutzen willst: ebenso deine webhookUrl(s) freigeben lassen, plus ein von
  dir gewähltes Webhook-Secret (für die Signaturprüfung, siehe unten).

Deine vereinbarten Limits (max. Dateigröße, max. Dateien pro Batch, Rate-Limit pro Minute)
erfährst du von uns bei der Einrichtung.

2. Ablauf im Überblick

1. POST /v1/batches        -> du bekommst eine signUrl zurück
2. Endnutzer öffnet signUrl -> signiert interaktiv (ID Austria / Handy-Signatur)
3. Du erfährst das Ergebnis -> per Webhook (empfohlen) ODER per Polling auf GET /v1/batches/{id}
4. GET /v1/documents/{id}/content -> signiertes PDF herunterladen (nur EINMAL möglich!)

3. Batch erstellen

POST /v1/batches
Header: X-Api-Key: <dein Key>
Body: multipart/form-data

Feld	Pflicht	Beschreibung
files	ja	1-N PDF-Dateien (Limit laut deiner Kundenkonfiguration)
returnUrl	nein	wohin der Endnutzer nach Abschluss im Browser weitergeleitet wird (muss in deiner Allowlist stehen)
webhookUrl	nein	wohin wir das Ergebnis per Webhook schicken (muss in deiner Allowlist stehen; erfordert ein hinterlegtes Webhook-Secret)
reference	nein	deine eigene Referenz (max. 100 Zeichen), erscheint unverändert in Status-Antworten und Webhooks
profile / signaturePosition	nein	überschreiben die für deinen Account hinterlegten Standardwerte

Antwort (201):

{
  "batchId": "b2e1...",
  "status": "AwaitingUser",
  "signUrl": "https://serv01.sign.fritss.at/pdf-as-web/...",
  "signingExpiresAt": "2026-10-31T16:00:00Z",
  "documents": [
    { "id": "d1a2...", "originalFileName": "vertrag.pdf", "status": "SigningStarted" }
  ]
}

signUrl muss der Endnutzer im eigenen Browser öffnen (nicht server-seitig abrufen) - dort
läuft die eigentliche Signatur mit ID Austria / Handy-Signatur ab.

4. Status-Werte

Batch-Status (status im Batch):

Status	Bedeutung
Created	angelegt, Signatur noch nicht gestartet (sehr kurzlebig)
AwaitingUser	wartet auf den Endnutzer
Completed	alle Dokumente erfolgreich signiert
PartiallyFailed	manche Dokumente signiert, andere nicht
Failed	kein Dokument signiert
Cancelled	abgebrochen (z.B. Zeitüberschreitung beim Signieren)
Expired	Frist abgelaufen, bevor der Endnutzer fertig war

Alle außer Created/AwaitingUser sind Endzustände - danach ändert sich nichts mehr.

Dokument-Status: Uploaded → SigningStarted → Signed → Retrieved (nach Download),
oder Failed/Cancelled/Expired.

5. Status abfragen (Polling-Alternative zum Webhook)

GET /v1/batches/{batchId}
Header: X-Api-Key: <dein Key>

{
  "batchId": "b2e1...",
  "status": "Completed",
  "reference": "deine-referenz",
  "documents": [
    { "id": "d1a2...", "originalFileName": "vertrag.pdf", "status": "Signed", "retrievableUntil": "2027-10-31T12:00:00Z" }
  ]
}

6. Signiertes Dokument herunterladen

GET /v1/documents/{documentId}/content
Header: X-Api-Key: <dein Key>

Antwort: das PDF direkt als application/pdf.

Wichtig: Download funktioniert nur einmal pro Dokument. Danach wird die Datei bei uns
gelöscht und ein erneuter Abruf liefert 410 Gone. Lade also erst herunter, wenn du bereit bist,
die Datei auch wirklich zu speichern (z.B. erst nachdem dein Webhook-Handler erfolgreich
geantwortet hat).

Nicht abgeholte, aber signierte Dokumente verfallen automatisch nach Ablauf deiner
Aufbewahrungsfrist (retrievableUntil).

7. Webhooks

Sobald ein Batch einen Endzustand erreicht, senden wir (falls webhookUrl gesetzt war) einen
POST mit folgendem Body an deine URL:

{
  "batchId": "b2e1...",
  "reference": "deine-referenz",
  "status": "Completed",
  "documents": [
    { "id": "d1a2...", "originalFileName": "vertrag.pdf", "status": "Signed" }
  ]
}

Signaturprüfung: Der Request trägt einen Header X-Signature mit dem HMAC-SHA256 des
rohen Request-Bodys, gebildet mit eurem Webhook-Secret als Schlüssel, als lowercase Hex-String.
Prüfe diese Signatur, bevor du dem Payload vertraust:

import hmac, hashlib
expected = hmac.new(webhook_secret.encode(), raw_body_bytes, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, request.headers["X-Signature"])

Wir retryen bei Fehlern (4xx/5xx/Timeout) mehrfach mit Backoff; antworte daher idempotent und mit
2xx, sobald du den Webhook verarbeitet hast. Der Webhook-Body enthält nie das PDF selbst -
nur Status und IDs. Das eigentliche Dokument holst du separat über Schritt 6.

8. Fehler & Limits

HTTP-Status	Bedeutung
400	Validierungsfehler (z.B. returnUrl nicht in der Allowlist, Datei zu groß, keine PDF)
401	fehlender/ungültiger X-Api-Key
429	Rate-Limit überschritten (dein vereinbartes Limit pro Minute)
502	Signaturbackend (PDF-AS) war beim Start nicht erreichbar/hat abgelehnt

API-Dokumentation

• Interaktiv, mit "Try it out": https://sign.fritss.at/docs (API-Key oben rechts eintragen)
• Rohes OpenAPI-Schema (Postman-Import, Codegeneratoren): https://sign.fritss.at/openapi/v1.json

Danksagung & Lizenzhinweis

Die eigentliche Signatur (ID Austria / Handy-Signatur) läuft über PDF-AS-Web 5, einen externen
Dienst des EGIZ (E-Government Innovation Center), veröffentlicht vom
österreichischen Bundeskanzleramt unter der
European Union Public Licence (EUPL) v1.2.
Dokumentation: apps.egiz.gv.at/handbooks.