Waafir
Diese Seite ist eine maschinelle Übersetzung, die noch auf eine menschliche Prüfung wartet. Sie kann Fehler enthalten.

Übersicht

Jeder Endpunkt im Kreditbereich teilt den auf dieser Seite beschriebenen Vertrag. Lesen Sie diese Seite zuerst; die Seiten zu den einzelnen Schnittstellen verweisen darauf, statt ihn zu wiederholen.

Basis-URL und Versionierung

Alle Routen im Kreditbereich liegen unter /api/v1/monitoring/loan/. Die Ganzzahl nach v ist die Major-Version: Ein Major-Sprung ist eine Breaking Change und erfolgt nur mit ausdrücklicher Abkündigung. Weiterentwicklungen innerhalb einer Major-Version sind ausschließlich additiv – neue optionale Felder, neue Endpunkte, neue Enum-Werte – und brechen nie eine Integration, die Felder ignoriert, die sie nicht versteht.

Der Produktions-Host ist https://app.waafir.io. Für eine vollständige URL stellen Sie den Host einem beliebigen Pfad auf dieser Referenzseite voran, zum Beispiel https://app.waafir.io/api/v1/monitoring/loan/borrowers.

Authentifizierung

Jeder Request enthält einen Authorization-Header mit einem Bearer-Token:

Authorization: Bearer <PAT>

<PAT> ist ein persönliches Zugriffstoken, das von der Waafir-Control-Plane für genau eine Organisation ausgestellt wird. Die Organisation des Tokens bestimmt den Mandantenbereich jedes Lese- und Schreibvorgangs – in keiner URL und keinem Body gibt es einen Organisationsparameter, weil das Token sie bereits festlegt.

Organisationsübergreifende Requests liefern 404 Not Found, nicht 403 Forbidden. Ein 403 würde die Existenz der Ressource eines anderen Mandanten anhand ihrer ID offenlegen; mit 404 werden unbekannte IDs und IDs anderer Mandanten identisch behandelt.

Ein Request ohne Authorization-Header, mit einem unbekannten Token oder mit einem widerrufenen Token liefert 401 Unauthorized.

Integrationsgarantien

Jede schreibende Route hält die folgenden Garantien ein. Auf jede davon kann sich Ihr Client-Code verlassen; wenn Sie sie hier einmal lesen, können Sie eine robuste Integration in einem Durchgang umsetzen.

Vom Aufrufer vergebene IDs

Jede Entität hat in ihrem Request-Body ein Feld id, das Sie als UUID angeben. Die Plattform erfindet nie IDs für Sie. Das ist die Grundlage aller weiteren Zusagen in dieser Liste: Idempotenz, Abgleich und Wiederholung hängen davon ab, dass Sie eine Zeile über eine selbst gewählte Kennung ansprechen können.

Wenn Sie eine Zeile mit derselben id erneut per POST senden, erhalten Sie 409 ID_CONFLICT und einen fieldErrors-Eintrag, der auf id verweist. Wählen Sie Ihre IDs sorgfältig – generierte UUIDv4 werden empfohlen, aber jede wohlgeformte UUID funktioniert.

Zusätzlich zu id trägt jede Entität eine externalId – eine frei wählbare Zeichenkette mit bis zu 255 Zeichen, mit der Sie die Zeile aus Ihrem eigenen System ansprechen. Eine externalId ist innerhalb eines Portfolios unter den aktiven Zeilen eindeutig; das macht den Abgleich per Caller-ID möglich.

Idempotency-Key-Header

Jede schreibende Route liest einen optionalen HTTP-Header Idempotency-Key. Ist er vorhanden, dedupliziert die Plattform gegen ein internes Archiv: Ein zweiter Request mit demselben Schlüssel liefert dieselbe Response wie der erste, selbst wenn sich der Body leicht unterscheidet. So überstehen Clients Netzwerkaussetzer, nach denen unklar ist, ob ein Request angekommen ist.

Der Header ist bei der Übertragung unabhängig von Groß- und Kleinschreibung (Idempotency-Key, idempotency-key, IDEMPOTENCY-KEY funktionieren alle). Der Wert wird als opak behandelt – wählen Sie pro logischer Operation etwas Stabiles, typischerweise eine UUIDv4 plus ein Routen-Unterscheidungsmerkmal.

?dryRun=true

Jede schreibende Route akzeptiert den Query-Parameter ?dryRun=true. Ein Probelauf führt Validierung und Mandantenprüfungen aus und gibt die validierte Eingabe zurück, zeichnet aber nichts auf und speichert keine Zeile. Damit prüfen Sie, ob ein Body sauber geparst wird, bevor Sie einen echten Schreibvorgang auslösen.

Die Response-Form bei einem erfolgreichen Probelauf ist { "dryRun": true, "validatedInput": <body> } mit 200 OK. Validierungsfehler während eines Probelaufs liefern dieselbe 400-Form wie ein echter Schreibvorgang; nur die Seiteneffekte unterscheiden sich.

fieldErrors-Validierungs-Envelope

Validierungsfehler liefern 400 Bad Request mit einem strukturierten Envelope:

{
  "error": "Validation failed",
  "fieldErrors": [
    { "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
    { "path": "termMonths", "message": "termMonths must be > 0" }
  ]
}

path ist der Punkt-Pfad zum fehlerhaften Feld; message ist eine für Menschen lesbare Erklärung. Das Envelope ist über alle Routen einheitlich, sodass ein einziger clientseitiger Handler jeden Validierungsfehler konsistent darstellen kann.

Enums ohne Beachtung der Groß-/Kleinschreibung mit „Meinten Sie“-Hinweisen

Domänen-Enums (Kreditstatus, Zahlungsmethode, Rückzahlungsfrequenz, Währungscode usw.) akzeptieren bei der Übertragung jede Schreibweise. Die Plattform normalisiert vor dem Speichern auf die kanonische Kleinschreibung.

Ein Fehltreffer liefert 400 mit einem fieldErrors-Eintrag, der den fehlerhaften Wert nennt und den nächstgelegenen akzeptierten Wert vorschlägt:

{
  "error": "Validation failed",
  "fieldErrors": [
    {
      "path": "status",
      "message": "got 'restruktured', did you mean 'restructured'?"
    }
  ]
}

Der Vorschlag wird mit einer kleinen Edit-Distanz-Metrik berechnet, sodass vertauschte Zeichen und einzelne Tippfehler zuverlässig erkannt werden.

metadata-JSONB-Durchreichung

Jede Entität akzeptiert ein optionales Feld metadata vom Typ Objekt. Die Plattform speichert das Objekt unverändert – es werden keine Schlüssel entfernt und keine Werte umgewandelt. Nutzen Sie es, um clientseitigen Kontext anzuhängen, den die Plattform selbst nicht verstehen muss: Ihre interne ID, das Quellsystem, einen Extraktionszeitstempel, einen Kampagnencode.

Zwei Schnittstellen verzichten auf metadata: die Route für Kreditstatuswechsel und die Routen zur Zahlungsstornierung. Die Begründung ist direkt bei diesen Routen dokumentiert.

Abgleich per Caller-ID

Jede Entität ist über die von Ihnen übermittelte externalId ansprechbar, bezogen auf ein Portfolio. Die Abgleichsschnittstelle – GET /loans/{externalId} und GET /counts – nutzt dies, damit Sie Schreibvorgänge prüfen können, ohne jemals die von der Plattform vergebene UUID zu benötigen. Die genauen Formen finden Sie auf der Abgleichsseite.

Darstellung von Geldbeträgen

Geldbeträge werden im Übertragungsformat als Zeichenketten aus Dezimalziffern mit bis zu vier Nachkommastellen dargestellt. JavaScript-number wird abgelehnt, weil binäre IEEE-754-Gleitkommazahlen dezimale Cent-Beträge nicht exakt darstellen können:

{ "amount": "100.50", "currencyCode": "USD" }

Ein Dezimalwert mit mehr als vier Nachkommastellen oder ein Wert mit anderen Zeichen als Ziffern, einem führenden Minus und einem einzelnen Punkt liefert 400 mit einem fieldErrors-Eintrag. Leere Zeichenketten werden abgelehnt.

Währungscodes sind dreistellige ISO-4217-Codes. Die Plattform erkennt die gängigen Codes explizit; unbekannte Codes, die dem Muster aus drei Großbuchstaben entsprechen, werden akzeptiert und unverändert gespeichert, damit Codes exotischer Märkte nicht blockiert werden.

Datumsformat

Datumsangaben sind im Übertragungsformat ISO-8601-Kalenderzeichenketten der Form YYYY-MM-DD:

{ "disbursementDate": "2026-01-15" }

Es gibt keine Zeitzonenkomponente. Datumsangaben sind Kalenderdaten in der Auslegung des Portfolios; die Plattform rechnet nicht um.

Stornierungssemantik

API-Aufrufe löschen nie eine Zeile. Eine Stornierung oder sonstige Rückabwicklung markiert die Zeile stattdessen als storniert. Die Folgen:

  • Eine externalId wird durch eine Stornierung nicht freigegeben. Eine externalId ist innerhalb eines Portfolios nur unter aktiven Zeilen eindeutig. Eine stornierte Zeile ist nicht mehr aktiv, sodass Sie ihre externalId für eine korrigierte erneute Übermittlung wiederverwenden können.
  • Abgleichsabfragen liefern stornierte Zeilen standardmäßig nicht zurück. Die Schnittstellen GET /loans/{externalId} und GET /counts schließen soft-gelöschte Zeilen aus ihrer Standard-Response aus.
  • Übermittlungsdatensätze bleiben in jedem Fall erhalten. Auch wenn eine Zeile storniert wird, bleibt der Datensatz der Übermittlung, die sie erzeugt hat, für Prüfzwecke unverändert bestehen.

Jede Übermittlung wird aufgezeichnet

Jede erfolgreiche Änderung zeichnet den unveränderten Request-Body auf, bevor die Zeile geschrieben wird. Die Folgen für Ihre Integration:

  • Ein 200/201 bedeutet, dass Ihre Übermittlung dauerhaft aufgezeichnet ist, selbst wenn die nachgelagerte Verarbeitung sie später beanstandet. Ihr Prüfpfad beginnt in dem Moment, in dem die Plattform den Request bestätigt.
  • Auch ein 409 ID_CONFLICT wird archiviert. Der Übermittlungsdatensatz enthält sowohl den Konflikt als auch die versuchte Übermittlung, sodass Sie später ohne Unklarheit darüber, was gesendet wurde, nachforschen können.
  • Asynchrone Importe werden zum Commit-Zeitpunkt aufgezeichnet. Die hochgeladene NDJSON-Datei und der Import selbst bilden den Datensatz; für einen asynchronen Import gibt es keinen separaten Datensatz pro Zeile.

Der Übermittlungsdatensatz kann nicht geändert werden. Sie lesen ihn nie direkt über die öffentliche API, aber er ist der Grund, warum die Abgleichsschnittstelle maßgeblich ist – hinter jeder dort sichtbaren Zeile steht ein entsprechender Archiveintrag.

Wie der Rest dieser Referenz aufgebaut ist

Jede weitere Seite dieser Referenzseite dokumentiert eine Aufnahmeform oder die Abgleichsschnittstelle. Jede Routenseite folgt derselben Struktur: ein Satz zum Zweck, die Request-Form (Header, Query, Body), die Response-Form pro Statuscode und ein minimaler cURL-Aufruf. Feldspezifische Einschränkungen stehen in Tabellen, die Sie schnell überfliegen können; ausführliche Beispiele und Codebeispiele in drei Sprachen finden Sie im Cookbook.

Die Seite Fehler und Statuscodes ist die konsolidierte Referenz für die Response-Envelopes, die jede Route dieser Seite verwendet. Lesen Sie sie einmal vor der Integration und schlagen Sie dort nach, wann immer Sie ein Status ungleich 200 überrascht.