API-Dokumentation

Überblick

Basis-URL

https://snapfritz.com/api/v1

Format

JSON (UTF-8); Upload als multipart/form-data oder application/pdf

Tarif

Platin – ohne Platin antworten Aufrufe mit 403 plan_required

Version

v1 – Erweiterungen kommen abwärtskompatibel dazu

Der Ablauf besteht immer aus denselben Schritten:

1. Hochladen – die Felder werden sofort ausgelesen
2. Felder prüfen und bestätigen (oder an einen Menschen übergeben)
3. Signieren
4. Fertiges PDF herunterladen

Authentifizierung

Jede Anfrage trägt einen API-Schlüssel im Header Authorization. Schlüssel legen Sie unter Entwickler an; sie werden nur einmal angezeigt und bei uns nur als Hash gespeichert. Ein Schlüssel gehört zu genau einem Konto und darf nur, was seine Scopes erlauben.

Authorization: Bearer sf_live_…

Behandeln Sie den Schlüssel wie ein Passwort: nie in Code-Repositories oder Client-Apps ablegen. Bei Verdacht unter Entwickler widerrufen und neu anlegen.

Schnellstart

Ein vollständiger Durchlauf. Ersetzen Sie $DOC und $FIELD durch die IDs aus der Antwort.

export SNAPFRITZ_API_KEY=sf_live_…

# 1. upload
curl -s -X POST https://snapfritz.com/api/v1/documents \
  -H "Authorization: Bearer $SNAPFRITZ_API_KEY" \
  -F file=@formular.pdf

# 2. confirm a field (omit "value" to accept the suggestion)
curl -s -X POST https://snapfritz.com/api/v1/documents/$DOC/fields/$FIELD/confirm \
  -H "Authorization: Bearer $SNAPFRITZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "Erika Muster"}'

# 3. sign (needs the documents:sign scope)
curl -s -X POST https://snapfritz.com/api/v1/documents/$DOC/sign \
  -H "Authorization: Bearer $SNAPFRITZ_API_KEY"

# 4. download the filled PDF
curl -s https://snapfritz.com/api/v1/documents/$DOC/download \
  -H "Authorization: Bearer $SNAPFRITZ_API_KEY" -o ausgefuellt.pdf

Dasselbe als Python-Skript

Bestätigt sicher erkannte Felder automatisch und übergibt alles Unsichere an einen Menschen.

import os
import requests

BASE = "https://snapfritz.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['SNAPFRITZ_API_KEY']}"}

with open("formular.pdf", "rb") as f:
    doc = requests.post(f"{BASE}/documents", headers=H, files={"file": f}, timeout=120)
doc.raise_for_status()
doc = doc.json()
if doc["status"] == "failed":
    raise SystemExit("PDF not readable")

for field in doc["fields"]:
    if field["confirmed"] or field["state"] in ("not_applicable", "out_of_scope"):
        continue
    if field["state"] != "ok":
        # unsure / missing / hand: decide yourself or hand over to a human
        raise SystemExit(f"Needs a decision: {field['label']} -> {doc['reviewUrl']}")
    requests.post(f"{BASE}/documents/{doc['id']}/fields/{field['id']}/confirm",
                  headers=H, json={}).raise_for_status()

requests.post(f"{BASE}/documents/{doc['id']}/sign", headers=H).raise_for_status()
pdf = requests.get(f"{BASE}/documents/{doc['id']}/download", headers=H)
open("ausgefuellt.pdf", "wb").write(pdf.content)

Beispielantwort des Uploads

Gekürzt auf ein Feld; Werte sind Beispiele.

{
  "id": "3f0c2d5e-8a4b-4f0e-9c1a-2b7d6e5f4a31",
  "filename": "formular.pdf",
  "title": "Anmeldung",
  "documentType": "registration",
  "status": "ready_for_review",
  "pageCount": 2,
  "requiresStrongerSignature": false,
  "requiresStrongerSignatureReason": null,
  "createdAt": "2026-09-25T13:04:11.000Z",
  "signedAt": null,
  "sentAt": null,
  "downloadable": false,
  "reviewUrl": "https://snapfritz.com/documents/3f0c2d5e-8a4b-4f0e-9c1a-2b7d6e5f4a31",
  "fields": [
    {
      "id": "b1f7c8a0-52de-4c1e-8f3a-9d0e7a6b5c42",
      "page": 1,
      "type": "text",
      "label": "Nachname",
      "semanticKey": "last_name",
      "state": "ok",
      "value": "Muster",
      "source": "profile",
      "confirmed": false,
      "checkboxGroup": null
    }
  ]
}

Endpunkte

Alle Pfade beziehen sich auf die Basis-URL. IDs sind UUIDs; fremde oder ungültige IDs antworten mit 404.

Maschinenlesbare Beschreibung für Client-Generatoren und Agenten-Frameworks: OpenAPI 3.1 (JSON)

Objekte

Das öffentliche Format eines Dokuments und seiner Felder. Interne Angaben wie Speicherorte sind bewusst nicht enthalten.

Feld-Status (state)

Dokument-Status (status)

Fehler

Fehler haben immer diese Form; der code ist stabil und für Programme gedacht, die message für Menschen:

{ "error": { "code": "not_found", "message": "Document not found." } }

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": {
    "code": "quota_exceeded",
    "message": "The plan's upload allowance for this period is used up.",
    "quota": { "kind": "uploads", "plan": "platin", "used": 200, "limit": 200, "resetsAt": "2026-10-25T00:00:00.000Z" }
  }
}

Limits & Kontingent

• 60 Anfragen pro Minute und Schlüssel, davon höchstens 10 Uploads. Darüber: 429 mit Retry-After (Sekunden); jede Antwort trägt X-RateLimit-Header.
• PDFs bis 20 MB und 20 Seiten. Der Tarif zählt fertige Formulare (jedes erfolgreiche Signieren) und, doppelt so viele, hochgeladene lesbare PDFs.
• Ist eins davon aufgebraucht, antworten Upload bzw. Signieren mit 402 quota_exceeded. Es wird nichts nachberechnet. GET /usage zeigt vorab, wie viel bleibt und wann es sich erneuert.
• Die Extraktion läuft synchron im Upload-Request und dauert je nach Umfang bis zu etwa einer Minute – Timeout im Client entsprechend hoch setzen (≥ 120 s).
• Alle Aktionen mit einem Schlüssel erscheinen im Protokoll des Kontos als „API-Schlüssel <Präfix>“.

Für Agenten

• Prüfen Sie state und confirmed jedes Felds. Nur ok automatisch bestätigen; bei unsure, missing und hand entscheiden Sie selbst oder übergeben an einen Menschen über reviewUrl.
• Rufen Sie vor dem Upload GET /usage ab, um 402 zu vermeiden.
• Bei 429 den Header Retry-After abwarten, bei 5xx mit Backoff wiederholen. POST …/sign ist idempotent; Uploads sind es nicht – nach einem Timeout zuerst GET /documents prüfen, statt blind neu hochzuladen.
• Vergeben Sie documents:sign nur an Schlüssel, die wirklich unterschreiben sollen, und trennen Sie Lese- von Schreibschlüsseln.
• Dokumente mit requiresStrongerSignature = true lassen sich nicht per API signieren – sie gehören in die Prüfansicht.