API-Referenz
Dieser Abschnitt ist das Referenzhandbuch für die Waafir-API im Kreditbereich – die HTTP-Schnittstelle, über die Fintechs Portfoliodaten für das Investoren-Monitoring an Waafir übertragen. Er dokumentiert jede Route unter /api/v1/monitoring/loan/, die Request- und Response-Schemas, jeden Statuscode, den gemeinsamen Developer-Experience-Vertrag und die Fehler-Envelopes, mit denen Sie rechnen sollten.
Die Referenz ist vollständig, aber nicht erzählend. Wenn Sie zum ersten Mal integrieren und eine geführte End-to-End-Anleitung suchen – mit cURL, TypeScript und Python nebeneinander –, lesen Sie das Cookbook parallel zu dieser Referenz; beide sind darauf ausgelegt, zusammen gelesen zu werden.
Was die API abdeckt
Die Kredit-API bietet vier Aufnahmeformen sowie eine Abgleichsschnittstelle:
- CRUD für Einzeldatensätze – ein HTTP-Aufruf pro Zeile. Für operative Schreibvorgänge mit geringem Volumen: ein einzelner neuer Kredit, eine einzelne Zahlung, ein Statuswechsel.
- Bulk-NDJSON – bis zu zehntausend Zeilen in einem synchronen Aufruf. Für Tagesend-Batches, die in einen einzigen HTTP-Request passen.
- Asynchrone Importe – ein direkter Datei-Upload, gefolgt von asynchroner Verarbeitung. Für historische Ladevorgänge oder jeden Batch mit mehr als zehntausend Zeilen.
- Abgleich – Rücklesen übermittelter Zeilen anhand Ihrer eigenen Caller-IDs sowie Zeilenzahlen pro Entität. Damit prüfen Sie, ob die gestrige Übermittlung sauber angekommen ist, bevor Sie die heutige übermitteln.
Jede Form wird auf einer eigenen Seite behandelt. Die Seitenreihenfolge entspricht der Reihenfolge, in der die meisten Integratoren sie durchlaufen: zuerst die Übersicht, dann der Aufnahmemodus, den Sie zuerst nutzen wollen, dann der Abgleich und schließlich die Fehlerreferenz.
Die sechs Entitäten im Kreditbereich
Jede Route arbeitet mit einer oder mehreren der folgenden Entitäten. Ihre vollständigen Schemas sind pro Route dokumentiert – diese Liste ist der Katalog:
borrower– die natürliche oder juristische Person, die den Kredit aufnimmt, mit optionalen PII-Feldern, die beim Lesen maskiert werden.loan– der Kreditvertrag selbst: Kapitalbetrag, Währung, effektiver Jahreszins (APR), Laufzeit, Rückzahlungsfrequenz, Status.scheduled_repayment– der vertragliche Rückzahlungsplan, eine Zeile pro Fälligkeitsdatum.actual_payment– die tatsächlich eingegangenen Zahlungen, einschließlich Abschreibungen und Teilzahlungen.collateral– für einen Kredit gestellte Sicherheiten.collateral_valuation– stichtagsbezogene Bewertungen einer Sicherheitenzeile, mit Unterstützung mehrerer Methoden.
Jede Entität gehört zu einem Portfolio in Ihrer Organisation. Das Portfolio wird bei jedem Schreibvorgang angegeben; die Organisation ergibt sich aus Ihrem persönlichen Zugriffstoken und erscheint nie in einem Request-Body.
Authentifizierung in einem Satz
Jeder Request enthält Authorization: Bearer <PAT>, wobei <PAT> ein persönliches Zugriffstoken ist, das von der Waafir-Control-Plane ausgestellt wird. Tokens sind auf eine Organisation beschränkt – ein für Organisation A ausgestelltes Token kann die Daten von Organisation B weder lesen noch schreiben, und organisationsübergreifende Lesezugriffe liefern 404 Not Found statt 403 Forbidden, damit die Existenz der Ressourcen eines anderen Mandanten nicht offengelegt wird.
Das vollständige Authentifizierungs- und Autorisierungsmodell wird in der Übersicht behandelt.
So verwenden Sie diese Referenz
Lesen Sie die Seiten der Reihe nach oder springen Sie direkt zur benötigten Schnittstelle:
- Übersicht – der gemeinsame Vertrag, den jede Route im Kreditbereich einhält: Authentifizierung, die Integrationsgarantien (vom Aufrufer vergebene IDs, Idempotenz, Probeläufe), Fehler-Envelopes, Konventionen für Geldbeträge und Datumsangaben, Stornierungssemantik und wie jede Übermittlung aufgezeichnet wird.
- CRUD für Einzeldatensätze – jede POST-, GET-, PATCH- und Storno-Route für einzelne Zeilen.
- Bulk-NDJSON – synchrone Massenaufnahme mit Fehlerberichten pro Zeile.
- Asynchrone Importe – der Lebenszyklus aus zweiphasigem Upload, Status-Polling und seitenweisem Abruf der Fehler.
- Abgleich – Rücklesen per Caller-ID und Zeilenzahlen pro Entität.
- Fehler und Statuscodes – der konsolidierte Katalog aller Statuscodes, Fehler-Envelopes und benannten Fehlercodes, die die Kredit-API ausgibt.
Aufgabenorientierte Anleitungen – ein Portfolio vollständig onboarden, einen täglichen Abgleich durchführen, sich von einem teilweise fehlgeschlagenen Import erholen – finden Sie im Cookbook (das zusammen mit dieser Referenz bereitgestellt wird). Das Cookbook führt jede Aufgabe in drei Sprachen durch; diese Referenz ist die maßgebliche Quelle dafür, was jede Route akzeptiert und zurückgibt.
Was diese Referenz nicht abdeckt
- Onboarding und Tokens – wie Sie eine Organisation registrieren, ein Portfolio anlegen und ein persönliches Zugriffstoken ausstellen. Diese Abläufe werden in der Dokumentation zur Plattformadministration und im Einstiegsrezept des Cookbooks behandelt.
- Analysen für Investoren – Chart-Pakete, der Tape-Export und die Download-Schnittstelle für das Loan Tape. Diese laufen über separate Routen und werden hier nicht behandelt.
- Webhooks und geplante Tape-Zustellung – hier nicht behandelt.