API & Webhooks

Erste Schritte

API und Webhooks sind in den Tarifen Pro und Business enthalten, ebenso in den 14 Testtagen. Den API-Schlüssel legt der Inhaber des Kontos unter Einstellungen → Integrationen an. Er wird genau einmal angezeigt; fordera speichert ihn nur als Hash.

Basis-Adresse: https://fordera.de/api/v1. Alle Antworten sind JSON, Zeitpunkte im Format ISO 8601 (UTC).

Typischer Ablauf mit einem CRM

1. Einmalig: GET /workflows abrufen und die passende id merken.
2. Neuer Kunde im CRM: POST /requests mit dieser workflowId. fordera verschickt die Anfrage.
3. Webhook document.uploaded: Datei über file.downloadUrl abholen und mit file.sha256 prüfen.
4. Webhook request.completed: Akte im CRM als vollständig markieren.

Anmeldung

Jeder Aufruf trägt den Schlüssel im Kopf Authorization:

curl https://fordera.de/api/v1/workflows \
  -H "Authorization: Bearer frd_IHR_SCHLUESSEL"

Je Schlüssel sind 600 Aufrufe pro Minute möglich. Jeder Schlüssel hat Zugriff auf alle Daten Ihrer Firma und nur auf diese. Widerrufen Sie einen Schlüssel jederzeit unter Einstellungen → Integrationen.

Fehler

Fehler kommen mit passendem HTTP-Status und einem Text für Menschen (error). Wo ein Programm unterschiedlich reagieren soll, steht zusätzlich ein fester code, der sich nicht ändert.

Workflows

GET /workflows

Alle Workflows Ihrer Firma mit ihren Positionen, sortiert nach Name.

{
  "data": [{
    "id": "cm…",
    "name": "Factoring: Neukunde / Bonitätsprüfung",
    "description": "…",
    "reminderDays": [3, 7, 14],
    "expiryDays": 30,
    "positions": [
      { "id": "cm…", "name": "BWA", "description": null, "type": "FILE", "required": true }
    ],
    "createdAt": "…", "updatedAt": "…"
  }]
}

type ist FILE (Datei), TEXT, NUMBER, DATE oder CONSENT (Einwilligung mit Zustimmungsfeld). Die id einer Position heißt in Anfragen und Webhooks requirementId.

Anfragen

POST /requests

Legt eine Anfrage an und verschickt sie standardmäßig per E-Mail.

HTTP 201
{
  "id": "cm…",
  "portalUrl": "https://fordera.de/portal/…",
  "status": "OPEN",
  "emailSent": true
}

emailSent meldet, ob der Mailversand tatsächlich angenommen wurde. Bei false trotz sendEmail: true erklärt emailError den Fehlschlag. Die Anfrage ist trotzdem angelegt, der portalUrl funktioniert.

GET /requests

Liste der Anfragen, neueste zuerst.

{
  "total": 312, "limit": 50, "offset": 0,
  "data": [{
    "id": "cm…", "recipientName": "…", "recipientEmail": "…",
    "workflow": "…", "status": "PARTIAL",
    "progress": { "done": 3, "total": 5, "requiredDone": 3, "requiredTotal": 4, "optionalOpen": 1 },
    "portalUrl": "…", "openedAt": "…", "dueDate": "…",
    "createdAt": "…", "updatedAt": "…"
  }]
}

COMPLETE heißt: Alle Pflichtpositionen liegen vor. Freiwillige Unterlagen können danach noch eintreffen (optionalOpen).

GET /requests/:id

Eine Anfrage mit allen Positionen und Dateien.

{
  "id": "cm…", "status": "PARTIAL", "workflow": "…", "portalUrl": "…",
  "recipientName": "…", "recipientEmail": "…",
  "openedAt": "…", "dueDate": "…", "createdAt": "…",
  "positions": [{
    "requirementId": "cm…", "name": "Jahresabschluss", "type": "FILE",
    "required": true, "status": "UPLOADED", "value": null, "rejectionReason": null,
    "file":  { …zuletzt hochgeladene Datei… },
    "files": [ { "id": "cm…", "fileName": "abschluss.pdf", "mimeType": "application/pdf",
                 "fileSize": 182044, "sha256": "…", "uploadedAt": "…",
                 "downloadUrl": "https://fordera.de/api/v1/files/cm…" } ]
  }],
  "extraFiles": [ { …wie oben…, "comment": "Noch ein Kontoauszug" } ]
}

Status einer Position: PENDING, UPLOADED, ACCEPTED, REJECTED, WAIVED, SKIPPED oder DECLINED. extraFiles sind Unterlagen, die der Empfänger freiwillig zusätzlich hochgeladen hat.

Dateien

GET /files/:id

Lädt eine Datei herunter, mit demselben Schlüssel. Jeder Abruf wird im Protokoll des Vorgangs vermerkt. Prüfen Sie die Datei gegen sha256, um sicherzugehen, dass sie seit dem Eingang unverändert ist.

curl -H "Authorization: Bearer frd_…" -o abschluss.pdf \
  https://fordera.de/api/v1/files/cm…

Kunden

Webhooks

fordera meldet Ereignisse per POST an eine https-Adresse Ihrer Wahl. Ziele legen Sie unter Einstellungen → Integrationen an und wählen dort, welche Ereignisse sie erhalten.

POST https://ihr-system.de/fordera
x-fordera-event:     document.uploaded
x-fordera-event-id:  evt_3f2c…
x-fordera-signature: 9a41…   (HMAC-SHA256, hex)

{
  "id": "evt_3f2c…",
  "event": "document.uploaded",
  "timestamp": "2026-10-06T09:12:44.120Z",
  "data": { … }
}

Ereignisse

file hat dieselben Felder wie in GET /requests/:id, einschließlich downloadUrl und sha256.

Echtheit prüfen

Bilden Sie den HMAC-SHA256 über den unveränderten Nachrichtentext mit dem Signatur-Geheimnis Ihres Ziels und vergleichen Sie ihn mit x-fordera-signature. Beispiel in Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

function istEcht(rohText, signatur, geheimnis) {
  const erwartet = createHmac("sha256", geheimnis).update(rohText).digest("hex");
  return erwartet.length === signatur.length &&
    timingSafeEqual(Buffer.from(erwartet), Buffer.from(signatur));
}

Zustellung und Wiederholung

Antworten Sie mit einem Status 2xx innerhalb von 5 Sekunden. Sonst gilt die Zustellung als gescheitert, und fordera versucht es erneut: nach etwa 1, 2, 4, 8 und 16 Stunden, insgesamt sechsmal. Eine Wiederholung trägt denselben Text, dieselbe Signatur und dieselbe id, damit Sie Doppelte überspringen können. timestamp ist der Zeitpunkt des Ereignisses, nicht der Zustellung.

Die Reihenfolge der Ereignisse ist nicht garantiert. Beim letzten Upload kann request.completed vor dem zugehörigen document.uploaded eintreffen. Verlassen Sie sich auf requestStatus und rufen Sie im Zweifel GET /requests/:id ab.

Zapier, Make und n8n

Ohne Programmierung: Legen Sie in Zapier, Make oder n8n einen Webhook-Auslöser an und tragen Sie dessen Adresse in fordera als Ziel ein. Jedes Ereignis startet dann Ihren Ablauf, etwa „Dokument eingegangen → Datei in SharePoint ablegen“. Für die andere Richtung („Neukunde im CRM → Anfrage auslösen“) nutzen Sie das HTTP-Modul des Werkzeugs mit POST /requests und dem Kopf Authorization.