API-Dokumentation

REST-API & Outbound-Webhooks

Vollständige technische Referenz der ERGOKONZEPT-Schnittstelle. Alle Endpunkte, Payloads, Webhook-Events und Code-Beispiele für eine produktionsreife Integration.

Einführung

Die ERGOKONZEPT-API ist eine REST-Schnittstelle (HTTPS / JSON) zur automatisierten Übergabe von Forderungen, Abruf von Status und Abrechnung sowie zur Annahme von Status-Events per Webhook. Alle Endpunkte sind unter der folgenden Basis-URL erreichbar:

https://ergokonzept-inkasso.com/api/public/v1

JSON über HTTPS

Request- und Response-Bodies sind UTF-8-JSON. Standard-Header: Content-Type: application/json.

API-Key

Authentifizierung via Header x-api-key oder Authorization: Bearer.

Outbound-Webhooks

Statusänderungen werden HMAC-signiert per HTTPS-POST an Ihre Endpunkte gepusht.

Wann ist die API sinnvoll?

Für die automatisierte Übergabe aus einem Bestandssystem (ERP, Shop, Buchhaltung). Für die manuelle Einzel-Erfassung steht unverändert das Mandantenportal zur Verfügung.

Komplette Doku für KI / LLM

Eine einzige Markdown-Datei mit allen Endpoints, Webhook-Payloads, Fehlercodes und Beispielen. Direkt in ChatGPT, Claude, Copilot & Co. einspielen, damit die KI die Integration ohne Rückfragen umsetzt.

ergokonzept-api.md

Authentifizierung

Jeder Request wird mit einem API-Key authentifiziert. Der Key wird im Mandantenportal unter API-Keys erzeugt und einmalig angezeigt. Beide Header-Varianten werden akzeptiert:

x-api-key: lk_IHR_API_KEY_HIER
# oder
Authorization: Bearer lk_IHR_API_KEY_HIER

Verbindungstest

Prüft die Gültigkeit des Keys ohne Datenänderung.

curl https://ergokonzept-inkasso.com/api/public/v1/claims \
  -H "x-api-key: lk_IHR_API_KEY_HIER"

200 OK

{ "data": [...] } – Key ist gültig.

401

{ "error": "invalid_api_key" } – Key fehlt, falsch oder widerrufen.

Login-Endpoint (Kompatibilität)

Für Clients, die einen Login-Schritt erwarten: POST /v1/login mit password = API-Key. Antwort enthält token, tenantId, Scopes.

curl -X POST https://ergokonzept-inkasso.com/api/public/v1/login \
  -H "Content-Type: application/json" \
  -d '{ "username": "shop-prod", "password": "lk_IHR_API_KEY_HIER" }'

Forderungen

POST/v1/claims

Forderung anlegen

Empfohlener Standard-Endpoint. Akzeptiert flache snake_case-Felder, optional inkl. Dokumenten als Base64.

Feld	Typ	Hinweis
`original_amount`	number	Hauptforderung (netto, ohne Gebühren)
`currency`	string(3)	ISO 4217, Default EUR
`invoice_number, invoice_date, due_date`	string	Rechnungsdaten
`service_mode`	enum	monitoring \| inkasso (Default: inkasso)
`external_reference`	string ≤120	Ihre interne Forderungs-ID
`debtor.type`	enum	private \| business
`debtor.address.country`	string(2)	ISO-3166 alpha-2
`documents[]`	array	Optional: invoice, contract, dunning_letter, …
`pre_collection_items[]`	array	Vorgelagerte Mahnkosten/Auslagen (type, amount, date, description)

Request

curl -X POST https://ergokonzept-inkasso.com/api/public/v1/claims \
  -H "x-api-key: lk_IHR_API_KEY_HIER" \
  -H "Content-Type: application/json" \
  -d '{
    "original_amount": 1499.00,
    "currency": "EUR",
    "invoice_number": "RG-2026-00123",
    "invoice_date": "2026-03-15",
    "due_date": "2026-04-15",
    "service_description": "Webentwicklung März 2026",
    "service_mode": "inkasso",
    "external_reference": "RG-2026-00123",
    "debtor": {
      "type": "private",
      "salutation": "Herr",
      "first_name": "Max",
      "last_name": "Mustermann",
      "email": "max@example.com",
      "phone": "+49 30 1234567",
      "address": {
        "street": "Musterstraße",
        "house_number": "12a",
        "postal_code": "10115",
        "city": "Berlin",
        "country": "DE"
      }
    },
    "documents": [
      {
        "file_type": "invoice",
        "filename": "rechnung-2026-00123.pdf",
        "mime_type": "application/pdf",
        "content_base64": "JVBERi0xLjQK..."
      }
    ]
  }'

Antwort (Beispiel)

{
  "data": {
    "id": "f3e2a1b4-…",
    "reference": "FOR-2026-000123",
    "status": "new",
    "service_mode": "inkasso",
    "original_amount": "1499.00",
    "open_amount": "1499.00",
    "created_at": "2026-05-29T10:12:34Z"
  }
}

POST/v1/claims/batch

Mehrere Forderungen in einem Request anlegen

Bis zu 100 Forderungen pro Request. Antwort enthält pro Element Erfolg/Fehler.

Request

curl -X POST https://ergokonzept-inkasso.com/api/public/v1/claims/batch \
  -H "x-api-key: lk_IHR_API_KEY_HIER" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "original_amount": 199.00, "invoice_number": "RG-001", "debtor": { ... } },
      { "original_amount": 499.00, "invoice_number": "RG-002", "debtor": { ... } }
    ]
  }'

Antwort (Beispiel)

{
  "results": [
    { "index": 0, "status": "created", "id": "…", "reference": "FOR-…" },
    { "index": 1, "status": "error", "code": "validation_failed", "message": "debtor.email invalid" }
  ],
  "summary": { "created": 1, "errors": 1 }
}

POST/v1/claims/createOwn

Kompatibilitätsmodus (camelCase)

Akzeptiert verschachtelte camelCase-Payloads mit kombinierten Adressen (addressLine1) und ISO3-Ländercodes. Dokumente optional — nachträglich via /files hochladbar.

Request

curl -X POST https://ergokonzept-inkasso.com/api/public/v1/claims/createOwn \
  -H "Authorization: Bearer lk_IHR_API_KEY_HIER" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "RG-2026-00123",
    "invoiceNumber": "RG-2026-00123",
    "originalAmountDue": 1499.00,
    "currency": "EUR",
    "dueDate": "2026-04-15",
    "debtor": {
      "businessType": "Consumer",
      "firstName": "Max",
      "lastName": "Mustermann",
      "email": "max@example.com",
      "address": {
        "addressLine1": "Musterstr. 12a",
        "postalCode": "10115",
        "city": "Berlin",
        "country": "DEU"
      }
    }
  }'

GET/v1/claims

Forderungen auflisten

Cursor-Paginierung. Filter: status, service_mode, reference, since, limit.

Request

curl "https://ergokonzept-inkasso.com/api/public/v1/claims?status=in_collection&limit=50" \
  -H "x-api-key: lk_IHR_API_KEY_HIER"

Antwort (Beispiel)

{
  "data": [ { "id": "…", "reference": "FOR-…", "status": "in_collection", "open_amount": "1499.00" } ],
  "next_cursor": "eyJ0Ijoi…"
}

GET/v1/claims/{id}

Einzelne Forderung abrufen

Liefert Stammdaten, Schuldner, Beträge, aktuellen Status und Verlinkungen auf Sub-Ressourcen.

Request

curl https://ergokonzept-inkasso.com/api/public/v1/claims/CLAIM-ID \
  -H "x-api-key: lk_IHR_API_KEY_HIER"

PATCH/v1/claims/{id}

Forderung aktualisieren (inkl. Fälligkeit nachträglich ändern)

Partial Update: status, Notizen, Fälligkeit (due_date), Rechnungsnummer/-datum, externe Referenz, Schuldnerstammdaten. Bei nachträglicher Fälligkeitsänderung werden Verzugszinsen ab dem neuen Datum berechnet und künftige Mahnschritte verschoben; bereits versendete Mahnungen bleiben unverändert. Jede Änderung landet im Aktivitätsprotokoll mit auslösendem API-Key. Ohne Statuswechsel wird der Webhook claim.updated gefeuert (mit changed_fields und due_date_retroactive).

Request

curl -X PATCH https://ergokonzept-inkasso.com/api/public/v1/claims/CLAIM-ID \
  -H "x-api-key: lk_IHR_API_KEY_HIER" \
  -H "Content-Type: application/json" \
  -d '{ "due_date": "2026-07-15" }'

Antwort (Beispiel)

{
  "data": {
    "id": "…",
    "reference": "FOR-2026-000123",
    "due_date": "2026-07-15",
    "status": "in_collection"
  }
}

POST/v1/claims/{id}/escalate

Forderung in Inkasso eskalieren

Nur für Forderungen mit service_mode=monitoring. Materialisiert RVG-Inkassokosten, archiviert Inkassoschreiben, versendet Schuldner-Portal-Token und löst Webhook claim.escalated aus. Bereits eskalierte Forderungen: 409 already_inkasso.

Request

curl -X POST https://ergokonzept-inkasso.com/api/public/v1/claims/CLAIM-ID/escalate \
  -H "x-api-key: lk_IHR_API_KEY_HIER" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Mandanten-Mahnstufe 3 ohne Reaktion" }'

POST/v1/claims/{id}/withdraw

Forderung zurückziehen

Sauberer Storno einer Forderung mit Begründung und – falls bekannt – Direktzahlung an den Mandanten. Setzt status=cancelled und löst Webhooks claim.withdrawn + claim.closed aus. Gebühren-Policy: free_in_monitoring (Monitoring) · free_before_first_contact (Inkasso vor erstem Schuldnerkontakt) · fees_kept_after_first_contact (RVG-Gebühren bleiben fällig ab erstem Schuldnerkontakt). Die angewandte Policy steht in der Webhook-Payload.

Feld	Typ	Hinweis
`reason`	enum	paid_to_creditor \| agreement \| error \| other
`paid_at`	date (YYYY-MM-DD)	Optional bei paid_to_creditor
`amount`	number	Optional bei paid_to_creditor
`note`	string ≤2000	Optional

Request

curl -X POST https://ergokonzept-inkasso.com/api/public/v1/claims/CLAIM-ID/withdraw \
  -H "x-api-key: lk_IHR_API_KEY_HIER" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "paid_to_creditor",
    "paid_at": "2026-05-28",
    "amount": 1499.00,
    "note": "Schuldner hat direkt an Mandant überwiesen."
  }'

Sub-Ressourcen

Alle Sub-Ressourcen werden unter dem Pfad /v1/claims/{id}/… angesprochen und sind tenant-scoped.

GET / POST/v1/claims/{id}/payments

Zahlungen lesen und melden

GET listet alle Zahlungen (incoming/outgoing). POST meldet eine Zahlung (z. B. Direktzahlung an Mandant). Bei incoming wird open_amount, paid_amount und ggf. Status automatisch aktualisiert; Webhook claim.payment_received wird ausgelöst.

Feld	Typ	Hinweis
`amount`	number > 0	Pflicht
`payment_date`	string (YYYY-MM-DD)	Pflicht
`direction`	enum	incoming (Default) \| outgoing
`description`	string ≤500	Optional

Request

curl -X POST https://ergokonzept-inkasso.com/api/public/v1/claims/CLAIM-ID/payments \
  -H "x-api-key: lk_IHR_API_KEY_HIER" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250.00,
    "payment_date": "2026-05-29",
    "direction": "incoming",
    "description": "Direktzahlung an Mandant per Überweisung"
  }'

POST/v1/claims/{id}/payments/{paymentId}/reverse

Zahlung stornieren / Rücklastschrift

Storniert eine fälschlich gemeldete oder zurückgegebene Zahlung (z. B. Rücklastschrift). Aktualisiert open_amount/paid_amount und ggf. Status, löst Webhook claim.payment_reversed mit amounts-Block aus. Über Idempotency-Key idempotent.

Feld	Typ	Hinweis
`reason`	enum	returned_debit \| chargeback \| error \| other
`note`	string ≤500	Optional

Request

curl -X POST https://ergokonzept-inkasso.com/api/public/v1/claims/CLAIM-ID/payments/PAYMENT-ID/reverse \
  -H "x-api-key: lk_IHR_API_KEY_HIER" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "returned_debit", "note": "Rücklastschrift vom 10.06." }'

GET/v1/claims/{id}/messages

Korrespondenz lesen

Listet die Schuldner- und Mandanten-Korrespondenz (Anschreiben, Antworten, Notizen) zu einer Forderung.

Request

curl https://ergokonzept-inkasso.com/api/public/v1/claims/CLAIM-ID/messages \
  -H "x-api-key: lk_IHR_API_KEY_HIER"

GET / POST/v1/claims/{id}/files

Dateien lesen und hochladen

POST nutzt multipart/form-data. Max. 20 MB. file_type ∈ { invoice, contract, dunning_letter, mandant_dunning_1, mandant_dunning_2, correspondence, court_document, payment_proof, id_document, power_of_attorney, proof_of_service, submission_receipt, integrity_proof, other }. Bei mandant_dunning_1/2 ist amount PFLICHT (Mahngebühr in EUR, ≥ 0, max. 1000) – wird automatisch als Nebenforderung gebucht und im Mahnbrief ausgewiesen. Webhook claim.file_uploaded wird ausgelöst.

Feld	Typ	Hinweis
`file`	binary	Pflicht. Max. 20 MB.
`file_type`	enum	siehe oben
`amount`	number	PFLICHT bei mandant_dunning_1/2 (EUR, 0–1000)
`fee_date`	date	Optional bei mandant_dunning_1/2 (Default: heute)
`description`	string ≤500	Optional

Request

curl -X POST https://ergokonzept-inkasso.com/api/public/v1/claims/CLAIM-ID/files \
  -H "x-api-key: lk_IHR_API_KEY_HIER" \
  -F "file=@./mahnung-1.pdf" \
  -F "file_type=mandant_dunning_1" \
  -F "amount=5.00" \
  -F "fee_date=2026-03-15" \
  -F "description=1. Mahnung vom 15.03.2026"

GET/v1/claims/{id}/fees

Nebenforderungen listen

Listet vom Mandanten erfasste Nebenforderungen gegen den Schuldner (Mahngebühren, Rücklastschriftgebühren, sonstige Nebenkosten). Eigene ERGOKONZEPT-Gebühren (RVG, Pauschalen) tauchen hier nicht auf – die finden sich unter /v1/billing/items.

Request

curl https://ergokonzept-inkasso.com/api/public/v1/claims/CLAIM-ID/fees \
  -H "x-api-key: lk_IHR_API_KEY_HIER"

POST/v1/claims/{id}/fees

Nebenforderung anlegen

Erfasst eine Nebenforderung (§§ 280, 286 BGB / § 288 V BGB) gegen den Schuldner. Nur möglich, solange die Forderung im Debitorenmanagement liegt (service_mode=monitoring, nicht eskaliert). Wirkt auf open_amount; der RVG-Gegenstandswert bleibt unverändert.

Feld	Typ	Hinweis
`fee_type`	enum	dunning_fee \| returned_debit_fee \| other_side_charge
`amount`	number	EUR, 0–10000
`description`	string ≤500	Optional
`fee_date`	date	Optional, Default: heute

Request

curl -X POST https://ergokonzept-inkasso.com/api/public/v1/claims/CLAIM-ID/fees \
  -H "x-api-key: lk_IHR_API_KEY_HIER" \
  -H "Content-Type: application/json" \
  -d '{
    "fee_type": "returned_debit_fee",
    "amount": 3.50,
    "description": "Rücklastschrift vom 10.04.2026",
    "fee_date": "2026-04-10"
  }'

DELETE/v1/claims/{id}/fees/{feeId}

Nebenforderung löschen

Korrektur einer falsch erfassten Nebenforderung. Nur möglich, solange service_mode=monitoring und nicht eskaliert. Ab Inkasso-Übergabe sind alle Posten eingefroren.

Request

curl -X DELETE https://ergokonzept-inkasso.com/api/public/v1/claims/CLAIM-ID/fees/FEE-ID \
  -H "x-api-key: lk_IHR_API_KEY_HIER"

POST/v1/claims/{id}/events

Eigene Aktion des Mandanten zurückmelden

Im Debitorenmanagement-Stadium meldet der Mandant z. B. eigene Mahnungen oder Telefonkontakte. Wird als Activity gespeichert und über Webhook claim.event_logged weitergegeben.

Feld	Typ	Hinweis
`event_type`	enum	mandant_dunning_1 \| mandant_dunning_2 \| mandant_contact \| mandant_note \| mandant_payment_arrangement
`occurred_at`	ISO-8601	Optional, Default: now
`title`	string ≤255	Optional
`description`	string ≤4000	Optional
`metadata`	object	Optional, frei

Request

curl -X POST https://ergokonzept-inkasso.com/api/public/v1/claims/CLAIM-ID/events \
  -H "x-api-key: lk_IHR_API_KEY_HIER" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "mandant_dunning_1",
    "occurred_at": "2026-05-29T10:00:00Z",
    "title": "Mahnung 1 per E-Mail versendet",
    "description": "Mahngebühr 5,00 €",
    "metadata": { "channel": "email" }
  }'

GET/v1/events

Event-Replay (Wiederholung verpasster Webhooks)

Liefert chronologisch alle Webhook-Events des Mandanten ab einem Zeitpunkt zur Wiederherstellung nach Ausfällen des eigenen Empfängers. Antwort enthält dieselbe Payload-Struktur wie der Webhook-Versand. Empfohlen als Recovery-Pfad in jeder Integration.

Feld	Typ	Hinweis
`since`	ISO-8601	Pflicht. Zeitpunkt ab dem Events geliefert werden.
`limit`	number	Default 100, max 500
`event_type`	string	Optional. Filter auf einen Event-Typ.

Request

curl "https://ergokonzept-inkasso.com/api/public/v1/events?since=2026-06-01T00:00:00Z&limit=200" \
  -H "x-api-key: lk_IHR_API_KEY_HIER"

Billing

Abruf der vom System erzeugten Gebühren-Posten und ERG-RG-Rechnungen (Rechnungen von ERGOKONZEPT an den Mandanten). Rechnungsnummer-Schema: ERG-RG-YYYY-NNNNNN.

GET/v1/billing/items

Gebühren-Posten auflisten

RVG-Gebühren, Mahnpauschalen, Monitoring- und Inkasso-Fees. Cursor-Paginierung.

Feld	Typ	Hinweis
`invoice_id`	uuid	Nur Posten einer bestimmten Rechnung
`claim_id`	uuid	Nur Posten zu einer Forderung
`occurred_since`	ISO-8601	Posten seit Zeitpunkt
`unbilled`	bool	Nur noch nicht verrechnete Posten
`cursor / limit`	string / int	Paginierung

Request

curl "https://ergokonzept-inkasso.com/api/public/v1/billing/items?unbilled=true&limit=50" \
  -H "x-api-key: lk_IHR_API_KEY_HIER"

GET/v1/billing/invoices

ERG-RG-Rechnungen auflisten

Optional mit signierter PDF-URL (1 Stunde gültig).

Feld	Typ	Hinweis
`status`	enum	draft \| issued \| paid \| netted \| cancelled
`issued_since`	ISO-8601	Nur Rechnungen seit Zeitpunkt
`include_download_url`	bool	Signierte PDF-URL beilegen

Request

curl "https://ergokonzept-inkasso.com/api/public/v1/billing/invoices?status=issued&include_download_url=true" \
  -H "x-api-key: lk_IHR_API_KEY_HIER"

GET/v1/billing/invoices/{id}

Einzelrechnung mit Posten und PDF-URL

Request

curl https://ergokonzept-inkasso.com/api/public/v1/billing/invoices/RECHNUNGS-ID \
  -H "x-api-key: lk_IHR_API_KEY_HIER"

Lazy-PDF-Generation

Existiert noch kein PDF, wird es beim ersten Abruf mit include_download_url=true oder Download automatisch erzeugt und in den Storage gelegt.

Outbound-Webhooks

ERGOKONZEPT pusht Statusänderungen per HTTPS-POST an Ihre konfigurierten URLs. Endpunkte und Signing-Secrets werden im Mandantenportal → Webhooks verwaltet.

Event-Katalog

Event	Auslöser
`claim.created`	Neue Forderung angelegt (API, Portal, Import)
`claim.updated`	Stammdaten geändert (Fälligkeit, Rechnungsdaten, externe Referenz, Schuldnerdaten)
`claim.status_changed`	Statuswechsel der Forderung
`claim.payment_received`	Zahlungseingang verbucht
`claim.closed`	Forderung abgeschlossen (paid, written_off, withdrawn)
`claim.file_uploaded`	Datei zur Forderung hochgeladen
`claim.legal_action_started`	Mahnbescheid / Klage / Vollstreckung eingeleitet
`claim.escalated`	Eskalation aus Monitoring in Inkasso
`claim.event_logged`	Mandant hat eigene Aktion gemeldet (/events)
`claim.withdrawn`	Forderung zurückgezogen (inkl. amounts & fee_policy)
`claim.payment_reversed`	Zahlung storniert / Rücklastschrift (inkl. amounts)
`claim.fee_added`	Nebenforderung angelegt
`claim.fee_removed`	Nebenforderung gelöscht
`billing.invoice_issued`	ERG-RG-Rechnung an Mandanten erstellt
`person.updated`	Zentrale Schuldner-Stammdaten aktualisiert (mandantenübergreifend)
`*`	Sammel-Abo für alle Ereignisse

Header & Request-Format

Methode POST, Body JSON (UTF-8). Folgende Header werden mitgeschickt:

Content-Type: application/json
x-webhook-event: claim.payment_received
x-webhook-timestamp: 1748000000
x-webhook-signature: 9a8f3c…           # HMAC-SHA-256, hex
x-webhook-delivery: 5f2c…              # eindeutige Delivery-ID (Idempotenzschlüssel)

Signaturprüfung (HMAC-SHA256)

Die Signatur wird über den rohen Request-Body gebildet. Verifizieren Sie sie vor dem Parsen des JSON-Bodies. Beispiele:

Node.js

import { createHmac, timingSafeEqual } from "crypto";

export function verify(rawBody, headers, secret) {
  const sig = headers["x-webhook-signature"];
  const expected = createHmac("sha256", secret)
    .update(rawBody).digest("hex");
  const a = Buffer.from(sig ?? "", "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

PHP

function verify(string $raw, array $headers, string $secret): bool {
  $sig = $headers['x-webhook-signature'] ?? '';
  $expected = hash_hmac('sha256', $raw, $secret);
  return hash_equals($expected, $sig);
}

Python

import hmac, hashlib

def verify(raw: bytes, headers: dict, secret: str) -> bool:
    sig = headers.get("x-webhook-signature", "")
    expected = hmac.new(
        secret.encode(), raw, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig)

Retry & Idempotenz

Erfolgreich bei HTTP 2xx innerhalb von 10 Sekunden.
Bis zu 8 Wiederholungen mit exponentiellem Backoff: 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h, 48 h.
Nach 8 Fehlversuchen wird der Endpunkt automatisch pausiert.
Idempotenz: bereits verarbeitete x-webhook-delivery speichern und Duplikate ignorieren.

Beispiel-Payloads

claim.created

{
  "claim_id": "f3e2a1b4-…",
  "reference": "FOR-2026-000123",
  "external_reference": "RG-2026-00123",
  "service_mode": "inkasso",
  "original_amount": "1499.00",
  "currency": "EUR"
}

claim.updated

{
  "claim_id": "…",
  "reference": "FOR-2026-000123",
  "changed_fields": {
    "due_date": { "old": "2026-05-01", "new": "2026-07-15" }
  },
  "due_date_retroactive": true,
  "changed_at": "2026-06-04T08:11:00Z",
  "api_key_id": "ak_…"
}

claim.status_changed

{
  "claim_id": "…",
  "reference": "FOR-…",
  "from_status": "in_collection",
  "to_status": "partially_paid",
  "changed_at": "2026-05-29T10:12:34Z"
}

claim.payment_received

{
  "claim_id": "…",
  "reference": "FOR-…",
  "payment_id": "…",
  "amount": 250.00,
  "direction": "incoming"
}

claim.closed

{
  "claim_id": "…",
  "reference": "FOR-…",
  "reason": "paid"
}

claim.file_uploaded

{
  "claim_id": "…",
  "file_id": "…",
  "file_type": "invoice",
  "filename": "rechnung.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 84231
}

claim.legal_action_started

{
  "claim_id": "…",
  "reference": "FOR-…",
  "action": "mahnbescheid",
  "court": "AG Berlin-Wedding",
  "started_at": "2026-06-01T09:00:00Z"
}

claim.escalated

{
  "claim_id": "…",
  "reference": "FOR-…",
  "from": "monitoring",
  "to": "inkasso",
  "reason": "Mandanten-Mahnstufe 3 ohne Reaktion"
}

claim.event_logged

{
  "claim_id": "…",
  "event_type": "mandant_dunning_1",
  "occurred_at": "2026-05-29T10:00:00Z",
  "title": "Mahnung 1 per E-Mail versendet"
}

billing.invoice_issued

{
  "invoice_id": "…",
  "invoice_number": "ERG-RG-2026-000123",
  "amount_net": "120.00",
  "amount_gross": "142.80",
  "currency": "EUR",
  "issued_at": "2026-05-31T00:05:00Z"
}

claim.withdrawn

{
  "claim_id": "…",
  "reference": "FOR-…",
  "reason": "paid_to_creditor",
  "fee_policy": "free_before_first_contact",
  "amounts": {
    "principal_open": "0.00",
    "fees_open": "0.00",
    "interest_open": "0.00",
    "total_open": "0.00"
  },
  "withdrawn_at": "2026-05-29T10:12:34Z"
}

claim.payment_reversed

{
  "claim_id": "…",
  "payment_id": "…",
  "amount": 250.00,
  "reason": "returned_debit",
  "amounts": {
    "principal_open": "1499.00",
    "fees_open": "0.00",
    "interest_open": "0.00",
    "total_open": "1499.00"
  },
  "reversed_at": "2026-06-10T08:00:00Z"
}

claim.fee_added

{
  "claim_id": "…",
  "fee_id": "…",
  "fee_type": "returned_debit_fee",
  "amount": 3.50,
  "description": "Rücklastschrift vom 10.04.2026",
  "fee_date": "2026-04-10"
}

claim.fee_removed

{
  "claim_id": "…",
  "fee_id": "…",
  "removed_at": "2026-04-15T12:00:00Z"
}

person.updated

{
  "person_id": "…",
  "changed_fields": {
    "email": { "old": "alt@example.com", "new": "neu@example.com" }
  },
  "affected_claim_ids": ["…", "…"],
  "changed_at": "2026-06-12T09:30:00Z"
}

Fehlerformat & Rate-Limits

Fehler werden mit passendem HTTP-Status und einem JSON-Body zurückgegeben:

{
  "error": "validation_failed",
  "message": "debtor.email must be a valid email",
  "details": { "field": "debtor.email" }
}

Status	error	Bedeutung
400	`validation_failed`	Body verletzt Schema
401	`invalid_api_key`	Key fehlt, falsch oder widerrufen
403	`forbidden`	Key hat keinen Scope für diese Ressource
404	`not_found`	Ressource existiert nicht im Tenant
409	`already_inkasso`	Doppelte Eskalation
413	`payload_too_large`	Datei > 20 MB
429	`rate_limited`	Zu viele Requests
500	`db_error / internal_error`	Serverseitiger Fehler

Rate-Limits

Standard: 120 Requests / Minute pro API-Key (Burst bis 240).
Batch-Endpunkte zählen als ein Request.
Höhere Limits auf Anfrage über Kontakt.

OpenAPI / Postman

Die vollständige OpenAPI-3-Spezifikation steht unter /api/public/v1/openapi bereit und kann direkt in Postman, Insomnia oder einem Code-Generator importiert werden.

OpenAPI-Spec herunterladen Komplette Doku als Markdown In Postman öffnen

Interaktive Referenz

Changelog

v1.62026-06-04
- Neuer Endpoint POST /claims/{id}/withdraw: Forderung sauber zurückziehen inkl. Gebühren-Policy (free_in_monitoring | free_before_first_contact | fees_kept_after_first_contact) und Webhook claim.withdrawn + claim.closed.
- Neuer Endpoint POST /claims/{id}/payments/{paymentId}/reverse: Zahlung stornieren / Rücklastschrift mit Webhook claim.payment_reversed (inkl. amounts-Block).
- Neuer Replay-Endpoint GET /v1/events zum Nachholen verpasster Webhooks.
- amounts-Block (principal_open, fees_open, interest_open, total_open) in Claim-GET sowie Payment-/Withdraw-Webhooks.
- Neuer Webhook person.updated: zentrale Schuldner-Stammdaten wurden mandantenübergreifend aktualisiert.
- Webhook-Header auf x-ergokonzept-* (bzw. x-webhook-*) vereinheitlicht.
- PATCH /claims/{id}: Fälligkeit (due_date) kann nachträglich geändert werden – auch wenn die Forderung bereits in Mahnung oder Inkasso ist. Verzugszinsen werden ab dem neuen Datum berechnet; künftige Mahnschritte verschieben sich, bereits versendete Mahnungen bleiben unverändert.
- Neuer Webhook claim.updated (mit changed_fields und due_date_retroactive) für Stammdaten-Änderungen ohne Statuswechsel.
- Aktivitätsprotokoll führt Fälligkeitsänderungen mit konkretem Vorher/Nachher (z. B. „Fälligkeit geändert: 01.05.2026 → 15.07.2026 (via API)").
v1.52026-06-01
- Mahngebühren-Pflichtfeld: POST /claims/{id}/files erfordert bei mandant_dunning_1/2 jetzt amount (EUR, 0–1000).
- Neue Nebenforderungs-Endpoints: POST/GET /claims/{id}/fees und DELETE /claims/{id}/fees/{feeId}.
- Neue Webhooks: claim.fee_added und claim.fee_removed.
- pre_collection_items und fees werden sofort in open_amount eingerechnet (nicht erst nach Eskalation).
v1.42026-05-29
- Outbound-Webhook claim.event_logged ergänzt (Mandanten-eigene Aktionen).
- Webhook claim.file_uploaded eingeführt.
- Beispiel-Payloads für alle Events in dieser Doku ergänzt.
v1.32026-05-22
- Billing-API: /v1/billing/items, /v1/billing/invoices, /v1/billing/invoices/{id}.
- Webhook billing.invoice_issued eingeführt.
- Lazy-PDF-Generation für ERG-RG-Rechnungen.
v1.22026-05-12
- Endpoint /v1/claims/{id}/escalate (Monitoring → Inkasso).
- Webhook claim.escalated eingeführt.
- Pflichtfeld service_mode (monitoring | inkasso) in /v1/claims.
v1.12026-04-30
- Kompatibilitäts-Endpoint /v1/claims/createOwn (camelCase, ISO3-Länder).
- Login-Endpoint /v1/login mit Token-Antwort.
v1.02026-04-15
- Erstveröffentlichung mit /v1/claims, /v1/claims/batch und Sub-Ressourcen.
- Outbound-Webhooks claim.created, claim.status_changed, claim.payment_received, claim.closed, claim.legal_action_started.

REST-API & Outbound-Webhooks

Einführung

Wann ist die API sinnvoll?

Authentifizierung

Verbindungstest

Login-Endpoint (Kompatibilität)

Forderungen

Forderung anlegen

Mehrere Forderungen in einem Request anlegen

Kompatibilitätsmodus (camelCase)

Forderungen auflisten

Einzelne Forderung abrufen

Forderung aktualisieren (inkl. Fälligkeit nachträglich ändern)

Forderung in Inkasso eskalieren

Forderung zurückziehen

Sub-Ressourcen

Zahlungen lesen und melden

Zahlung stornieren / Rücklastschrift

Korrespondenz lesen

Dateien lesen und hochladen

Nebenforderungen listen

Nebenforderung anlegen

Nebenforderung löschen

Eigene Aktion des Mandanten zurückmelden

Event-Replay (Wiederholung verpasster Webhooks)

Billing

Gebühren-Posten auflisten

ERG-RG-Rechnungen auflisten

Einzelrechnung mit Posten und PDF-URL

Lazy-PDF-Generation

Outbound-Webhooks

Event-Katalog

Header & Request-Format

Signaturprüfung (HMAC-SHA256)

Retry & Idempotenz

Beispiel-Payloads

Fehlerformat & Rate-Limits

Rate-Limits

OpenAPI / Postman

Interaktive Referenz

Changelog

Häufige Fragen

Warum nur ein API-Key statt Public/Secret-Paar?

Verlorener oder kompromittierter Key

Endpoint-URL

Sicherheitshinweise zum Umgang mit dem API-Key