Freigado
Developer

Freigado API

Binden Sie die Dokumentenfreigabe in wenigen Zeilen in Ihre Anwendung ein – etwa in ein DMS, ERP oder eine Fachanwendung. Sie reichen ein PDF samt Empfänger ein, Freigado übernimmt den sicheren Freigabe-Prozess, und Sie holen das Ergebnis strukturiert zurück. Schlanke REST-API, ausschließlich in der EU gehostet, DSGVO-konform.

Anleitung zur APISchritt für Schritt: Signatur, alle Endpunkte, Fehlercodes und lauffähige Beispiele für curl, PowerShell, C#, Node.js und Python.

So einfach ist die Integration

  1. Dokument einreichen – ein POST mit PDF und Empfänger- E-Mail. Optional: eine eigene Vorgangs-ID und bis zu drei eigene Entscheidungs-Buttons mit Vermerk.
  2. Freigado übernimmt – der Empfänger erhält einen sicheren Einmal-Link, verifiziert sich per Code und entscheidet im Browser. Kein Konto nötig.
  3. Ergebnis abrufen – ein GET liefert Status und Entscheidung (Ergebnis, Vermerk, Kommentar, Zeitpunkt). Das Dokument wird nach der Entscheidung sofort gelöscht.

Endpunkte

Zwei Endpunkte genügen für die Grundanbindung:

POST /api/v1/documents        # Dokument zur Freigabe einreichen
GET  /api/v1/documents/{id}    # Status & Entscheidung abrufen (Polling)

Optional – Vorlagen mit mehreren Unterzeichnern, Erinnerungen und Ergebnisabruf:

GET  /api/v1/templates                          # Vorlagen der Organisation
POST /api/v1/documents  (JSON: templateId …)    # Vorgang aus Vorlage anlegen
GET  /api/v1/documents/{id}/files/document      # finales PDF abholen
POST /api/v1/documents/{id}/files/ack           # Abruf bestätigen → sofort löschen

Authentifizierung

Jede Anfrage wird mit einem API-Schlüssel und einer HMAC-Signatur über Zeitstempel und Anfrageinhalt abgesichert – standardkonform und ohne Zusatzbibliotheken umsetzbar. Schlüssel und Signatur-Geheimnis legen Sie als Inhaber Ihrer Organisation im Portal unter „API-Zugang“ selbst an; sie verbleiben serverseitig in Ihrer Anwendung.

Authorization: Bearer <API_KEY>
X-Timestamp:   <unix-sekunden oder -millisekunden>
X-Signature:   <signatur>

Die vollständige Signatur-Spezifikation mit Testvektor finden Sie in der Anleitung zur API.

Beispiel

Dokument einreichen (schematisch – lauffähige Beispiele mit Signatur in der Anleitung):

curl -X POST https://<ihre-freigado-domain>/api/v1/documents \
  -H "Authorization: Bearer <API_KEY>" \
  -H "X-Timestamp: <unix-millis>" \
  -H "X-Signature: <signatur>" \
  -F "file=@vertrag.pdf" \
  -F "recipientEmail=pruefer@kunde.de" \
  -F "externalId=VORGANG-4711"

Antwort:

{
  "documentId": "…",
  "externalId": "VORGANG-4711",
  "reviewUrl": "https://…/d/…",
  "status": "PENDING",
  "expiresAt": "…"
}

Ergebnis später abrufen:

{
  "status": "APPROVED",
  "decision": {
    "outcome": "APPROVED",
    "selectedLabel": "Mit Auflagen freigegeben",
    "annotation": "…",
    "comment": "…",
    "decidedAt": "…"
  }
}

Gut zu wissen

  • Idempotent: Mit Ihrer eigenen Vorgangs-ID (externalId) führt ein wiederholter Aufruf nicht zu doppelten Dokumenten.
  • Polling statt Webhook: Sie fragen den Status aktiv ab – das funktioniert auch hinter Firewalls und On-Premise (nur ausgehende HTTPS-Verbindungen).
  • Konfigurierbare Entscheidung: bis zu drei eigene Buttons mit statischem Vermerk – passend zu Ihrem Workflow.
  • EU & DSGVO: Verarbeitung ausschließlich in der EU, keine US-Subprozessoren, sofortige Löschung nach Entscheidung. Bei API-Vorgängen bleibt nur das Ergebnis-PDF bis zu Ihrem Abruf liegen – höchstens 7 Tage.

Zugang

Der API-Zugang ist im Business-Tarif enthalten (auch in der kostenlosen Testphase). Schlüssel und Signatur-Geheimnis legen Sie im Portal unter „API-Zugang“ selbst an und widerrufen sie dort bei Bedarf.

API-Zugang anfragen