{"openapi":"3.0.3","info":{"title":"ERGOKONZEPT Inkasso API","version":"1.6.0","description":"Moderne REST-API für die Einreichung und Verwaltung von Inkasso-Forderungen.\n\n**Authentifizierung:** Header `x-api-key` mit Ihrem API-Key.\n\n**IP-Allowlist (empfohlen für Server-zu-Server):** Pro API-Key konfigurierbare Liste erlaubter IPv4/IPv6-Adressen oder CIDR-Bereiche mit Modi `off` / `warn` / `enforce`. Im Modus `enforce` werden Requests von nicht erlaubten IPs mit 403 `ip_not_allowed` abgelehnt.\n\n**Idempotenz:** Optionaler Header `Idempotency-Key` (UUID v4) auf allen POST-Endpunkten. Retries mit gleichem Key liefern die ursprüngliche Antwort (24h Cache).\n\n**Paginierung:** Cursor-basiert via `?cursor=...&limit=...` (max. 500/Seite).\n\n**Offene Beträge:** GET `/claims/{id}` sowie die Webhook-Events `claim.payment_received`, `claim.payment_reversed` und `claim.withdrawn` enthalten den Block `amounts` mit `principal_open`, `fees_open`, `interest_open` und `total_open` – die robuste Grundlage für „Hauptforderung gedeckt\"-Logiken statt eigener Heuristiken.\n\n**Webhooks (Outbound):** Events `claim.created`, `claim.updated`, `claim.status_changed`, `claim.payment_received`, `claim.payment_reversed`, `claim.withdrawn`, `claim.closed`, `claim.escalated`, `claim.event_logged`, `claim.file_uploaded`, `claim.legal_action_started`, `claim.fee_added`, `claim.fee_removed`, `billing.invoice_issued`, `person.updated`. Konfiguration im Mandantenportal unter Webhooks. Header bei jedem Delivery:\n- `x-ergokonzept-signature: sha256=<hex>` — HMAC-SHA256 über den **Rohbody** mit Endpoint-Secret\n- `x-ergokonzept-event: <event-typ>`\n- `x-ergokonzept-delivery: <uuid>` — eindeutig pro Zustellversuch, für Dedup geeignet\n- `user-agent: ERGOKONZEPT-Webhook/1.0`\n\nEmpfänger MÜSSEN die Signatur vor dem Parsen verifizieren und über `x-ergokonzept-delivery` deduplizieren.\n\n**Verpasste Webhooks nachholen:** GET `/events?since=<iso>` liefert deduplizierte Events der letzten 30 Tage (Cursor-paginiert). Pro Event-ID nur ein Eintrag, unabhängig davon, ob/wie oft die Webhook-Zustellung damals erfolgreich war.","contact":{"name":"ERGOKONZEPT AG","url":"https://ergokonzept-inkasso.com"}},"servers":[{"url":"/api/public/v1"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Address":{"type":"object","required":["street","house_number","postal_code","city","country"],"properties":{"street":{"type":"string"},"house_number":{"type":"string"},"postal_code":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string","example":"DE"},"additional_info":{"type":"string","description":"Zusatz (c/o, Stockwerk, …)."}}},"Debtor":{"type":"object","required":["email","phone","address"],"properties":{"type":{"type":"string","enum":["private","business"]},"salutation":{"type":"string","description":"z.B. 'Herr', 'Frau', 'Divers'."},"title":{"type":"string","description":"Akad. Titel, z.B. 'Dr.'."},"first_name":{"type":"string"},"last_name":{"type":"string"},"company_name":{"type":"string"},"contact_person":{"type":"string","description":"Pflicht bei type=business."},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"mobile":{"type":"string"},"date_of_birth":{"type":"string","format":"date"},"vat_id":{"type":"string","description":"USt-IdNr."},"tax_id":{"type":"string","description":"Steuernummer."},"external_reference":{"type":"string","description":"Externe Schuldner-ID des Mandanten."},"address":{"$ref":"#/components/schemas/Address"}}},"Claim":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string"},"external_reference":{"type":"string"},"status":{"type":"string"},"original_amount":{"type":"number"},"open_amount":{"type":"number"},"paid_amount":{"type":"number"},"currency":{"type":"string"},"claim_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"invoice_number":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ClaimInput":{"type":"object","required":["original_amount","invoice_number","invoice_date","due_date","debtor","documents"],"properties":{"original_amount":{"type":"number"},"currency":{"type":"string","default":"EUR"},"external_reference":{"type":"string","description":"Eindeutig pro Mandant. Bei Duplikat → 409."},"invoice_number":{"type":"string"},"invoice_date":{"type":"string","format":"date"},"claim_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"contract_date":{"type":"string","format":"date","description":"Datum des zugrundeliegenden Vertrags."},"service_description":{"type":"string"},"customer_notes":{"type":"string","description":"Sichtbar für Schuldner (z.B. im Portal/Brief)."},"internal_notes":{"type":"string","description":"Nur intern, nicht für Schuldner sichtbar."},"pre_collection_fees":{"type":"number","description":"DEPRECATED. Wird seit 06/2026 abgelehnt (HTTP 422 dunning_fee_requires_document). Mahngebühren MÜSSEN zusammen mit der zugehörigen Mahn-PDF gesendet werden – siehe documents[] mit file_type=mandant_dunning_1/2 und Feld amount, oder späterer Upload via POST /claims/{id}/files."},"pre_collection_items":{"type":"array","maxItems":20,"description":"Optionale Aufschlüsselung vorgerichtlicher Kosten. WICHTIG: Positionen vom Typ dunning_fee oder reminder_fee werden seit 06/2026 abgelehnt (HTTP 422 dunning_fee_requires_document) – sie müssen zusammen mit der Mahn-PDF gebucht werden. Andere Typen (late_fee, other) bleiben erlaubt.","items":{"type":"object","required":["amount"],"properties":{"type":{"type":"string","enum":["dunning_fee","reminder_fee","late_fee","other"],"default":"dunning_fee"},"amount":{"type":"number"},"date":{"type":"string","format":"date","description":"Datum der Position."},"description":{"type":"string"}}}},"debtor":{"$ref":"#/components/schemas/Debtor"},"documents":{"type":"array","minItems":1,"maxItems":20,"description":"Pflicht: mindestens eine Rechnung mit file_type=invoice als Base64-Dokument.","items":{"type":"object","required":["file_type","filename","content_base64"],"properties":{"file_type":{"$ref":"#/components/schemas/FileType"},"filename":{"type":"string"},"mime_type":{"type":"string","default":"application/pdf"},"content_base64":{"type":"string","description":"Base64-Inhalt ohne data:-Prefix."},"description":{"type":"string"}}}}}},"FileType":{"type":"string","enum":["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"]},"Pagination":{"type":"object","properties":{"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"BillingItem":{"type":"object","description":"Einzelner Gebühren-Posten (RVG-Gebühr, Mahnkosten, etc.) gegenüber dem Mandanten.","properties":{"id":{"type":"string","format":"uuid"},"claim_id":{"type":"string","format":"uuid","nullable":true},"item_type":{"type":"string","description":"z.B. monitoring_fee, inkasso_fee, rvg_geschaeftsgebuehr, mahnpauschale."},"description":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"quantity":{"type":"number"},"unit_price_net":{"type":"number"},"amount_net":{"type":"number"},"vat_rate":{"type":"number","description":"Dezimalbruch, z.B. 0.19 = 19%."},"vat_amount":{"type":"number"},"amount_gross":{"type":"number"},"vat_treatment":{"type":"string","enum":["standard_de","reverse_charge_eu","export_third_country","small_business","exempt","custom"]},"invoice_id":{"type":"string","format":"uuid","nullable":true,"description":"NULL = noch nicht in Rechnung gestellt."},"metadata":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"BillingInvoice":{"type":"object","description":"ERG-RG-Rechnung von ERGOKONZEPT an den Mandanten (mit Netting-Verknüpfung zum Payout).","properties":{"id":{"type":"string","format":"uuid"},"invoice_number":{"type":"string","example":"ERG-RG-2026-000123"},"period_from":{"type":"string","format":"date"},"period_to":{"type":"string","format":"date"},"issued_at":{"type":"string","format":"date-time"},"due_date":{"type":"string","format":"date","nullable":true},"amount_net":{"type":"number"},"vat_amount":{"type":"number"},"amount_gross":{"type":"number"},"vat_treatment":{"type":"string"},"currency":{"type":"string","example":"EUR"},"status":{"type":"string","enum":["draft","issued","paid","netted","cancelled"]},"netted_against_payout_id":{"type":"string","format":"uuid","nullable":true},"pdf_storage_path":{"type":"string","nullable":true},"pdf_download_url":{"type":"string","nullable":true,"description":"Nur bei ?include_download_url=true oder im Einzelabruf. Signiert, 1h gültig."},"items":{"type":"array","items":{"$ref":"#/components/schemas/BillingItem"},"description":"Nur im Einzelabruf gesetzt."},"created_at":{"type":"string","format":"date-time"}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Eindeutiger Schlüssel pro logischem Request für sicheres Retry."}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/login":{"post":{"summary":"Kompatibilitäts-Login (Username/Password → Bearer-Token)","description":"Für Clients, die einen klassischen Login erwarten. `password` ist der API-Key (lk_…). Antwort enthält `token`, `userId` (=tenantId) und `scopes`. Der Token wird anschließend als `Authorization: Bearer …` oder `x-api-key` Header verwendet.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["password"],"properties":{"username":{"type":"string","description":"Optional, nur zur Protokollierung."},"password":{"type":"string","description":"API-Key (lk_…)."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"refreshToken":{"type":"string"},"userId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"scopes":{"type":"array","items":{"type":"string"}},"tokenType":{"type":"string","example":"Bearer"},"expiresIn":{"type":"integer"}}}}}},"401":{"description":"Ungültige Zugangsdaten"}}}},"/claims/createOwn":{"post":{"summary":"Forderung anlegen (Kompatibilitätsmodus, camelCase + verschachtelt)","description":"Akzeptiert camelCase-Payload. Server-seitig: Adress-Split (addressLine1 → street/house_number), ISO3→ISO2 Ländercodes, businessType→type Mapping. Dokumente sind optional und können anschließend per `POST /claims/{id}/files` hochgeladen werden.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["originalAmountDue","debtor"],"properties":{"title":{"type":"string"},"invoiceNumber":{"type":"string"},"originalAmountDue":{"type":"number"},"currency":{"type":"string","default":"EUR"},"dueDate":{"type":"string","format":"date"},"invoiceDate":{"type":"string","format":"date"},"externalReference":{"type":"string"},"serviceDescription":{"type":"string"},"debtor":{"type":"object","required":["email","address"],"properties":{"businessType":{"type":"string","enum":["Consumer","Business"]},"firstName":{"type":"string"},"lastName":{"type":"string"},"companyName":{"type":"string"},"contactPerson":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"address":{"type":"object","required":["postalCode","city","country"],"properties":{"addressLine1":{"type":"string","description":"Straße + Hausnummer kombiniert; wird serverseitig zerlegt."},"street":{"type":"string"},"houseNumber":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"country":{"type":"string","description":"ISO2 oder ISO3 (z.B. DE oder DEU)."}}}}}}}}}},"responses":{"201":{"description":"Erstellt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Claim"}}}}}},"409":{"description":"Duplikat","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/claims":{"get":{"summary":"Forderungen auflisten (Cursor-Paginierung)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":100,"minimum":1,"maximum":500}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Nur Forderungen seit diesem Zeitpunkt"},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"post":{"summary":"Forderung anlegen","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimInput"}}}},"responses":{"201":{"description":"Erstellt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Claim"}}}}}},"409":{"description":"Duplikat (external_reference oder Idempotency-Key-Konflikt)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/claims/batch":{"post":{"summary":"Bulk-Import: bis zu 500 Forderungen in einem Call","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claims"],"properties":{"claims":{"type":"array","minItems":1,"maxItems":500,"items":{"$ref":"#/components/schemas/ClaimInput"}}}}}}},"responses":{"207":{"description":"Multi-Status: pro Eintrag Erfolg oder Fehler","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"created":{"type":"integer"},"failed":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"status":{"type":"string","enum":["created","error"]},"claim_id":{"type":"string","format":"uuid"},"reference":{"type":"string"},"external_reference":{"type":"string"},"error":{"$ref":"#/components/schemas/Error"}}}}}}}}}}}}}},"/claims/{id}":{"get":{"summary":"Forderung abrufen","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}},"patch":{"summary":"Forderung aktualisieren (Status, Notizen, Fälligkeit, Rechnungsdaten, Schuldnerdaten)","description":"Partial Update einer bestehenden Forderung. Unterstützt insbesondere die **nachträgliche Änderung der Fälligkeit** (`due_date`). Wirkungen: Verzugszinsen werden ab dem neuen Datum berechnet, künftige Mahnschritte verschieben sich entsprechend, bereits versendete Mahnungen bleiben unverändert. Jede Änderung wird im Aktivitätsprotokoll der Forderung dokumentiert (inkl. auslösendem API-Key). Bei Änderungen ohne Statuswechsel wird der Webhook `claim.updated` ausgelöst; der Payload enthält `changed_fields` mit alt/neu sowie `due_date_retroactive: true`, falls die Fälligkeit verschoben wurde.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["draft","open","in_dunning","in_collection","payment_plan","partially_paid","paid","settled","on_hold","cancelled","legal","uncollectible"]},"customer_notes":{"type":"string"},"internal_notes":{"type":"string"},"due_date":{"type":"string","format":"date","description":"Neue Fälligkeit. Nachträgliche Änderung erlaubt, auch wenn die Forderung bereits in Mahnung oder Inkasso ist."},"invoice_number":{"type":"string"},"invoice_date":{"type":"string","format":"date"},"external_reference":{"type":"string"}}},"examples":{"due_date_change":{"summary":"Fälligkeit nachträglich verschieben","value":{"due_date":"2026-07-15"}}}}}},"responses":{"200":{"description":"Aktualisiert"},"404":{"description":"Not found"}}}},"/claims/{id}/files":{"get":{"summary":"Dateien einer Forderung listen (mit signierten Download-URLs)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}},"post":{"summary":"Datei hochladen (Rechnung, Mahnung, Vertrag, …)","description":"Bei file_type=mandant_dunning_1 / mandant_dunning_2 ist `amount` PFLICHT (in EUR, ≥ 0, max. 1000). Wird automatisch als Nebenforderung claim_fees.fee_type=dunning_fee gebucht und im Mahnbrief ausgewiesen. `fee_date` ist optional (Default: heute).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","file_type"],"properties":{"file":{"type":"string","format":"binary","description":"Max. 20 MB"},"file_type":{"$ref":"#/components/schemas/FileType"},"description":{"type":"string","maxLength":500},"amount":{"type":"number","description":"Pflicht bei mandant_dunning_1/2; Mahngebühr in EUR (≥ 0, max. 1000)."},"fee_date":{"type":"string","format":"date","description":"Optional bei mandant_dunning_1/2; Default: heute."}}}}}},"responses":{"201":{"description":"Hochgeladen"},"400":{"description":"Validierung fehlgeschlagen (z. B. missing_amount)"},"413":{"description":"Datei zu groß"},"415":{"description":"Falscher Content-Type"}}}},"/claims/{id}/fees":{"get":{"summary":"Nebenforderungen (Mahngebühren, Rücklastschrift, …) listen","description":"Nur vom Mandanten erfasste Nebenforderungen (dunning_fee, returned_debit_fee, other_side_charge). RVG-Posten von ERGOKONZEPT (collection_fee) sind hier NICHT enthalten.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}},"post":{"summary":"Nebenforderung anlegen","description":"Erfasst eine Nebenforderung gegen den Schuldner (§§ 280, 286 BGB / § 288 Abs. 5 BGB). Nur erlaubt, solange die Forderung im Debitorenmanagement ist (service_mode=monitoring, nicht eskaliert). Wirkt auf open_amount, NICHT auf den RVG-Gegenstandswert.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fee_type","amount"],"properties":{"fee_type":{"type":"string","enum":["dunning_fee","returned_debit_fee","other_side_charge"]},"amount":{"type":"number","minimum":0,"maximum":10000,"description":"Betrag in EUR."},"description":{"type":"string","maxLength":500},"fee_date":{"type":"string","format":"date"}}}}}},"responses":{"201":{"description":"Angelegt"},"409":{"description":"fees_locked – Forderung bereits eskaliert"}}}},"/claims/{id}/fees/{feeId}":{"delete":{"summary":"Nebenforderung stornieren (nur im Monitoring)","description":"Storniert eine vom Mandanten erfasste Nebenforderung. Bei fee_type=dunning_fee wird der zugehörige Debitorenmanagement-Posten (Mahn-PDF derselben Stufe) automatisch gegengebucht: noch nicht abgerechnet → Posten wird entfernt; bereits in einer Monats­rechnung enthalten → negativer Storno-Posten, der im Folgemonat als Gutschrift verrechnet wird. Jede Stornierung wird in den Forderungs-Aktivitäten protokolliert (mit API-Schlüssel-ID und Grund) und löst das Webhook-Event `claim.fee_removed` aus.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"feeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"reason","in":"query","required":false,"schema":{"type":"string","maxLength":500},"description":"Optionaler Stornogrund (z. B. 'doppelt gebucht durch API-Wiederholung'). Wird auch im JSON-Body unter `reason` akzeptiert."}],"responses":{"200":{"description":"Storniert. data enthält fee_id, fee_type, amount, dunning_stage und billing_reversal (mode=deleted|credited oder null)."},"404":{"description":"fee_not_found"},"409":{"description":"fees_locked – Forderung bereits eskaliert"}}}},"/claims/{id}/payments":{"get":{"summary":"Zahlungen einer Forderung","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}},"post":{"summary":"Zahlung manuell melden (z.B. Direktzahlung an Mandant)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","payment_date"],"properties":{"amount":{"type":"number"},"payment_date":{"type":"string","format":"date"},"direction":{"type":"string","enum":["incoming","outgoing"],"default":"incoming"},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Gemeldet"}}}},"/claims/{id}/messages":{"get":{"summary":"Nachrichten zur Forderung (Schuldner ↔ Sachbearbeiter)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}}},"/claims/{id}/payments/{paymentId}/reverse":{"post":{"summary":"Zahlung stornieren (Rücklastschrift, Fehlbuchung, Rückzahlung)","description":"Bucht eine negative Gegenposition zur ursprünglichen Zahlung und reduziert paid_amount entsprechend. Pro Original-Zahlung ist nur **eine** Stornobuchung erlaubt (zweiter Aufruf → 409 already_reversed). Löst Webhook `claim.payment_reversed` mit aktualisiertem `amounts`-Block aus.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"paymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":1,"maxLength":500,"description":"Stornogrund (Pflicht), z.B. 'Rücklastschrift Bank'."},"reversal_date":{"type":"string","format":"date","description":"Optional, Default: heute."}}}}}},"responses":{"201":{"description":"Storniert"},"404":{"description":"payment_not_found"},"409":{"description":"already_reversed oder already_reversal"}}}},"/claims/{id}/withdraw":{"post":{"summary":"Forderung zurückziehen (z.B. nach Direktzahlung an Gläubiger)","description":"Beendet alle weiteren Inkasso-Maßnahmen. Setzt Status auf `cancelled` mit `reason='withdrawn'`. Optional kann gleichzeitig eine Direktzahlung an den Mandanten gemeldet werden (`amount`).\n\n**Gebühren-Policy (automatisch angewendet):**\n- Debitorenmanagement (Monitoring): Rückzug **immer kostenfrei**, alle Mahnpauschalen werden storniert.\n- Inkasso, **vor** erstem Schuldnerkontakt durch ERGOKONZEPT: kostenfrei, RVG-Gebühr wird storniert.\n- Inkasso, **nach** erstem Schuldnerkontakt: alle Maßnahmen stoppen sofort, bestehende Gebühren bleiben bestehen.\n\nLöst Webhooks `claim.withdrawn` (mit `cancelled_fees[]` und `amounts`) sowie `claim.closed` aus.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"description":"Optionaler Freitext, z.B. 'Direktzahlung an Mandant'."},"amount":{"type":"number","description":"Optional: Direktzahlung in EUR, die gleichzeitig gebucht werden soll."},"paid_at":{"type":"string","format":"date","description":"Optional: Datum der Direktzahlung, Default heute."}}}}}},"responses":{"200":{"description":"Zurückgezogen"},"404":{"description":"Forderung nicht gefunden"},"409":{"description":"Forderung bereits abgeschlossen"}}}},"/events":{"get":{"summary":"Webhook-Events nachholen (Replay verpasster Zustellungen)","description":"Liefert alle Events der letzten 30 Tage, die der Mandant per Webhook erhalten hätte – unabhängig vom damaligen Zustell-Erfolg. Pro Event-ID nur ein Eintrag (dedupliziert über alle Endpunkte und Versuche). Cursor-paginiert aufsteigend nach `created_at`.","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO-8601 Startzeitpunkt. Default: vor 7 Tagen. Max. 30 Tage rückwirkend."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor aus pagination.next_cursor der Vorseite."},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"minimum":1,"maximum":500}},{"name":"event_type","in":"query","schema":{"type":"string"},"description":"Optionaler Filter, z.B. claim.payment_received."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Event-ID (stabil pro Event)."},"type":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"window_too_large oder invalid_since"}}}},"/billing/items":{"get":{"summary":"Gebühren-Posten auflisten (Cursor-Paginierung)","description":"Alle vom System erzeugten Gebühren-Posten gegenüber dem Mandanten (RVG, Mahnpauschalen, monitoring_fee, inkasso_fee, …). Optional nur unverrechnete Posten via `?unbilled=true`.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":100,"minimum":1,"maximum":500}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"invoice_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Nur Posten dieser Rechnung."},{"name":"claim_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Nur Posten zu dieser Forderung."},{"name":"occurred_since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"unbilled","in":"query","schema":{"type":"boolean"},"description":"Nur noch nicht in Rechnung gestellte Posten."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BillingItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}},"/billing/invoices":{"get":{"summary":"ERG-RG-Rechnungen auflisten (Cursor-Paginierung)","description":"Rechnungen von ERGOKONZEPT an den Mandanten. Werden beim Payout-Netting automatisch erzeugt.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":200}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","issued","paid","netted","cancelled"]}},{"name":"issued_since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"include_download_url","in":"query","schema":{"type":"boolean"},"description":"Wenn true, wird je Rechnung eine signierte PDF-Download-URL angehängt (1h gültig)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BillingInvoice"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}},"/billing/invoices/{id}":{"get":{"summary":"Einzelne ERG-RG-Rechnung inkl. Posten + signierter PDF-URL","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BillingInvoice"}}}}}},"404":{"description":"Nicht gefunden"}}}}}}