CRUD für Einzeldatensätze
Die CRUD-Schnittstelle für Einzeldatensätze ist der Weg für geringe Volumen: ein HTTP-Aufruf pro Zeile. Nutzen Sie sie für operative Schreibvorgänge – ein einzelner neuer Kredit, eine einzelne Zahlung, die nicht im Tages-Batch enthalten war, ein Statuswechsel – sowie zum Rücklesen per Plattform-UUID. Für Tagesend-Batches verwenden Sie Bulk-NDJSON; für historische Ladevorgänge asynchrone Importe.
Jede Route auf dieser Seite hält den in der Übersicht dokumentierten Vertrag ein: Bearer-Token-Authentifizierung, die Integrationsgarantien, das fieldErrors-Envelope, die Stornierungssemantik und die Aufzeichnung jeder Übermittlung. Die folgende Dokumentation pro Route nennt nur die routenspezifischen Formen; für übergreifendes Verhalten lesen Sie die Übersicht.
Routen im Überblick
| Methode | Pfad | Zweck |
|---|---|---|
POST | /api/v1/monitoring/loan/borrowers | Kreditnehmer anlegen |
GET | /api/v1/monitoring/loan/borrowers/{id} | Kreditnehmer per UUID lesen, mit PII-Maskierung |
POST | /api/v1/monitoring/loan/loans | Kredit anlegen |
POST | /api/v1/monitoring/loan/payments | Tatsächliche Zahlung anlegen |
GET | /api/v1/monitoring/loan/payments/{id} | Tatsächliche Zahlung per UUID lesen |
PATCH | /api/v1/monitoring/loan/loans/{loanRef}/status | Kredit in einen neuen Status überführen |
POST | /api/v1/monitoring/loan/payments/{id}/cancel | Zahlung per Soft-Delete entfernen |
Alle schreibenden Routen akzeptieren den Header Idempotency-Key und den Query-Parameter ?dryRun=true und liefern bei Validierungsfehlern das strukturierte fieldErrors-Envelope.
POST /api/v1/monitoring/loan/borrowers
Legt einen Kreditnehmer in dem durch portfolioId angegebenen Portfolio an.
Request
POST /api/v1/monitoring/loan/borrowers HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>Body:
| Feld | Typ | Pflicht | Einschränkung |
|---|---|---|---|
id | UUID-String | ja | Vom Aufrufer vergebene Plattformkennung. |
portfolioId | UUID-String | ja | Das zugehörige Portfolio; muss in Ihrer Organisation existieren. |
externalId | string | ja | 1–255 Zeichen; eindeutig pro (portfolio, externalId) unter aktiven Zeilen. |
name | string | null | nein | Vollständiger Name des Kreditnehmers. Wird unverändert gespeichert; Lesezugriffe für Investoren maskieren. |
email | string | null | nein | E-Mail nach RFC 5322; wird unverändert gespeichert; Lesezugriffe für Investoren maskieren. |
phone | string | null | nein | Telefonnummer im freien Format; wird unverändert gespeichert; Lesezugriffe für Investoren maskieren. |
nationalIdLast4 | string | null | nein | Genau vier Ziffern; die vorangehenden Ziffern werden nie zurückgegeben. |
countryCode | string | null | nein | Zweistelliger ISO-3166-Code (Großbuchstaben). |
dob | Datums-String | null | nein | YYYY-MM-DD. |
gender | enum | null | nein | male | female | non_binary | other | undisclosed (ohne Beachtung der Groß-/Kleinschreibung). |
incomeBand | string | null | nein | Freies Format. |
employmentStatus | string | null | nein | Freies Format. |
metadata | object | null | nein | Unveränderte Durchreichung. |
Responses
201 Created bei einem neuen Schreibvorgang, 200 OK bei einer idempotenten Wiederholung:
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "BORROWER-001",
"bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
"reused": false
}| Status | Envelope | Auslöser |
|---|---|---|
200 OK | { id, externalId, bronzeSubmissionId, reused: true } | Idempotency-Key entsprach einem früheren Request; kein neuer Schreibvorgang. |
201 Created | { id, externalId, bronzeSubmissionId, reused: false } | Neue Zeile eingefügt. |
400 Bad Request | fieldErrors | Validierungsfehler in einem beliebigen Body-Feld. |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | portfolioId existiert nicht oder gehört zu einer anderen Organisation. |
409 Conflict | { error, code: "ID_CONFLICT", fieldErrors: [...] } | Ein aktiver Kreditnehmer mit derselben id existiert bereits. |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/borrowers \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e" \
-d '{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"gender": "female",
"countryCode": "KE"
}'GET /api/v1/monitoring/loan/borrowers/{id}
Liest einen Kreditnehmer per Plattform-UUID. PII-Felder sind standardmäßig maskiert; Admins können mit ?unmask=true unmaskierte PII anfordern, was einen Audit-Log-Eintrag erzeugt.
Request
| Parameter | Position | Pflicht | Einschränkung |
|---|---|---|---|
id | Pfad | ja | Die Plattform-UUID des Kreditnehmers. |
unmask | Query | nein | true liefert unmaskierte PII; nur für Admins. Standardmäßig maskiert. |
Responses
200 OK mit dem maskierten Kreditnehmer-Datensatz:
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"name": "J***",
"email": "j***@example.com",
"phone": "***-***-1234",
"nationalIdLast4": "1234",
"countryCode": "KE",
"dob": "1985-03-20",
"gender": "female",
"incomeBand": null,
"employmentStatus": null,
"metadata": {}
}| Status | Auslöser |
|---|---|
200 OK | Zeile existiert in Ihrer Organisation. PII sind unmaskiert, wenn der Aufrufer Admin ist UND ?unmask=true gesetzt ist; andernfalls sind PII maskiert. |
400 Bad Request | id ist keine wohlgeformte UUID. |
404 Not Found | Zeile existiert nicht, ist storniert oder gehört zu einer anderen Organisation. |
Die PII-Maskierung gilt für name, email, phone und nationalIdLast4. Das Feld nationalIdLast4 speichert schon beim Schreiben nur die letzten vier Ziffern; die Maskierung beim Lesen verbirgt sie dennoch vor Lesezugriffen ohne Admin-Rechte.
Ein Aufrufer ohne Admin-Rechte, der ?unmask=true übergibt, erhält kein 403 – die Response ist weiterhin 200 mit der maskierten Form, und es wird ein Audit-Log-Eintrag über den abgelehnten Demaskierungsversuch geschrieben. Die Plattform meldet die Rollenprüfung nicht als Fehler, weil die maskierte Form der sichere Standard ist; erst der Prüfpfad macht den Versuch für das Sicherheitsteam sichtbar.
Ein Admin, der ?unmask=true übergibt, erhält die unmaskierten PII, und der Request schreibt einen separaten Audit-Log-Eintrag, der die Demaskierung festhält. Die Response enthält Cache-Control: private, no-store, damit Zwischenstationen die unmaskierten PII-Daten nicht zwischenspeichern.
POST /api/v1/monitoring/loan/loans
Legt einen Kredit für einen bestehenden Kreditnehmer im selben Portfolio an.
Request
| Feld | Typ | Pflicht | Einschränkung |
|---|---|---|---|
id | UUID-String | ja | Vom Aufrufer vergebene Plattformkennung. |
portfolioId | UUID-String | ja | Das zugehörige Portfolio. |
borrowerId | UUID-String | ja | Ein aktiver Kreditnehmer im selben Portfolio. |
externalId | string | ja | 1–255 Zeichen; eindeutig pro Portfolio unter aktiven Zeilen. |
predecessorLoanId | UUID-String | null | nein | Wird bei einer Restrukturierung gesetzt; verweist auf den ersetzten Kredit. |
principalAmount | Dezimal-String | ja | Bis zu vier Nachkommastellen. |
currencyCode | string | ja | Dreistelliger ISO-4217-Code; ohne Beachtung der Groß-/Kleinschreibung. |
interestRateApr | Dezimal-String | ja | Bis zu sechs Nachkommastellen; muss >= 0 sein. |
disbursementDate | Datums-String | ja | YYYY-MM-DD. |
termMonths | integer | ja | Muss > 0 sein. |
repaymentFrequency | enum | ja | monthly | weekly | biweekly | quarterly | bullet (ohne Beachtung der Groß-/Kleinschreibung). |
productType | string | null | nein | Freies Format, z. B. "Term loan", "Overdraft". |
status | enum | ja | pending | active | paid_off | restructured | written_off | defaulted (ohne Beachtung der Groß-/Kleinschreibung). |
metadata | object | null | nein | Unveränderte Durchreichung. |
Responses
201 Created (oder 200 OK bei idempotenter Wiederholung) mit { id, externalId, bronzeSubmissionId, reused }.
| Status | Envelope | Auslöser |
|---|---|---|
200 OK | { ..., reused: true } | Idempotente Wiederholung. |
201 Created | { ..., reused: false } | Neuer Kredit eingefügt. |
400 Bad Request | fieldErrors | Validierungsfehler (z. B. negativer interestRateApr, fehlerhafter currencyCode). |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | Portfolio fehlt oder gehört zu einer anderen Organisation. |
409 Conflict | { error, code: "ID_CONFLICT" } | Ein aktiver Kredit mit derselben id existiert bereits. |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "borrowerId", ... }] } | borrowerId verweist auf keinen aktiven Kreditnehmer im selben Portfolio. |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/loans \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-d '{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "LOAN-001",
"principalAmount": "10000.00",
"currencyCode": "USD",
"interestRateApr": "0.18",
"disbursementDate": "2026-01-15",
"termMonths": 12,
"repaymentFrequency": "monthly",
"status": "active"
}'POST /api/v1/monitoring/loan/payments
Erfasst eine tatsächliche Zahlung zu einem bestehenden Kredit. Verwenden Sie diese Route für eingegangene Zahlungen, Teilzahlungen und Abschreibungen. Restrukturierungen werden als neuer Kredit mit gesetztem predecessorLoanId abgebildet, nicht als Zahlung.
Request
| Feld | Typ | Pflicht | Einschränkung |
|---|---|---|---|
id | UUID-String | ja | Vom Aufrufer vergebene Plattformkennung. |
portfolioId | UUID-String | ja | Das zugehörige Portfolio. |
loanId | UUID-String | ja | Ein aktiver Kredit im selben Portfolio. |
externalId | string | ja | 1–255 Zeichen; eindeutig pro Portfolio unter aktiven Zeilen. |
paymentDate | Datums-String | ja | YYYY-MM-DD. |
amount | Dezimal-String | ja | Der insgesamt eingegangene Zahlungsbetrag. |
currencyCode | string | ja | ISO-4217. |
principalPaid | Dezimal-String | nein | Standardwert "0". |
interestPaid | Dezimal-String | nein | Standardwert "0". |
feesPaid | Dezimal-String | nein | Standardwert "0". |
writeOffAmount | Dezimal-String | nein | Standardwert "0". Siehe Regel zum Forderungsverzicht unten. |
paymentNotes | string | null | nein | Muss "Forgiven" sein (ohne Beachtung der Groß-/Kleinschreibung), wenn writeOffAmount > 0. |
paymentMethod | enum | null | nein | cash | bank_transfer | card | mobile_money | check | other. |
metadata | object | null | nein | Unveränderte Durchreichung. |
Regel zum Forderungsverzicht. Wenn writeOffAmount > 0, muss paymentNotes ohne Beachtung der Groß-/Kleinschreibung "Forgiven" entsprechen. Die Plattform lässt den Request bereits an der API-Grenze scheitern, sodass eine fehlerhafte Zahlung abgelehnt wird, bevor irgendetwas aufgezeichnet wird.
Responses
201 Created (oder 200 OK bei idempotenter Wiederholung) mit { id, externalId, bronzeSubmissionId, reused }.
| Status | Envelope | Auslöser |
|---|---|---|
200 OK | { ..., reused: true } | Idempotente Wiederholung. |
201 Created | { ..., reused: false } | Neue Zahlung eingefügt. |
400 Bad Request | fieldErrors | Validierungsfehler (fehlerhafte Beträge, unbekannter Enum-Wert, fehlendes Pflichtfeld). |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | Portfolio fehlt oder gehört zu einer anderen Organisation. |
409 Conflict | { error, code: "ID_CONFLICT" } | Eine aktive Zahlung mit derselben id existiert bereits. |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "loanId", ... }] } | loanId verweist auf keinen aktiven Kredit im selben Portfolio. |
400 Bad Request | { error, code: "CHECK_VIOLATION", fieldErrors: [...] } | Die Regel zum Forderungsverzicht wurde beim Speichern der Zahlung verletzt (selten; die Validierung lehnt dieselbe Form vorher ab). |
GET /api/v1/monitoring/loan/payments/{id}
Liest eine tatsächliche Zahlung per Plattform-UUID, einschließlich stornierter (soft-gelöschter) Zeilen. Nutzen Sie diese Route, um einen Schreibvorgang zu prüfen oder einen stornierten Datensatz einzusehen.
Request
| Parameter | Position | Pflicht | Einschränkung |
|---|---|---|---|
id | Pfad | ja | Die Plattform-UUID der Zahlung. |
Responses
200 OK mit dem vollständigen Zahlungsdatensatz. Stornierte Zeilen erscheinen mit befülltem deletedAt; aktive Zeilen haben deletedAt: null. 404 Not Found bei Zugriff auf eine andere Organisation oder unbekannter UUID. 400 Bad Request, wenn id keine wohlgeformte UUID ist.
PATCH /api/v1/monitoring/loan/loans/{loanRef}/status
Überführt einen Kredit in einen neuen Status. Das Pfadsegment {loanRef} akzeptiert entweder die Plattform-UUID des Kredits oder seine externalId. Wenn Sie eine externalId übergeben, müssen Sie zusätzlich ?portfolioId=<UUID> angeben, weil externe IDs nicht portfolioübergreifend eindeutig sind.
Request
PATCH /api/v1/monitoring/loan/loans/LOAN-001/status?portfolioId=ddf63d12-1234-5678-9abc-def012345678 HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>Body:
| Feld | Typ | Pflicht | Einschränkung |
|---|---|---|---|
status | enum | ja | Einer von active | paid_off | defaulted | written_off | restructured (ohne Beachtung der Groß-/Kleinschreibung). |
effectiveDate | Datums-String | ja | YYYY-MM-DD. |
reason | string | null | nein | 1–500 Zeichen; wird im Audit-Log festgehalten. |
Matrix der Statuswechsel
Die Plattform erzwingt eine Übergangsmatrix; ein unzulässiger Wechsel liefert 422 INVALID_STATUS_TRANSITION mit fieldErrors, die Ausgangs- und Zielstatus nennen.
| Von | Zulässige Ziele |
|---|---|
pending | active |
active | paid_off, defaulted, written_off, restructured |
paid_off | (Endzustand) |
defaulted | written_off, restructured |
written_off | (Endzustand) |
restructured | (Endzustand) |
Wenn Sie einen Kredit auf restructured setzen, ist der natürliche nächste Schritt ein POST /loans für den Ersatzkredit mit gesetztem predecessorLoanId. Die beiden Schreibvorgänge sind bewusst nicht atomar – schlägt der POST für den Ersatzkredit fehl, bleibt der Vorgänger im Status restructured, und die Abgleichsschnittstelle zeigt die Abweichung bei Ihrer nächsten Abfrage.
Responses
200 OK bei Erfolg:
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"externalId": "LOAN-001",
"status": "restructured",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false
}| Status | Envelope | Auslöser |
|---|---|---|
200 OK | { id, externalId, status, bronzeSubmissionId, reused } | Wechsel angewendet (oder idempotente Wiederholung mit reused: true). |
400 Bad Request | fieldErrors | Validierungsfehler im Body, fehlende portfolioId bei Suche per externalId, fehlerhafter Enum-Wert. |
404 Not Found | { error, code: "NOT_FOUND" } | Kredit per UUID nicht gefunden, oder (portfolioId, externalId) lässt sich nicht auflösen. |
422 Unprocessable Entity | { error, code: "INVALID_STATUS_TRANSITION", fieldErrors: [...] } | Das Paar aus Ausgangs- und Zielstatus ist nicht in der Übergangsmatrix enthalten; fieldErrors[].message listet die zulässigen Ziele auf. |
409 Conflict | { error, code: "IDEMPOTENCY_CONFLICT" } | Der Idempotency-Key wurde bereits für einen anderen Statuswechsel verwendet. Der frühere Schreibvorgang bleibt bestehen; senden Sie den neuen Statuswechsel mit einem neuen Schlüssel. |
Das von Ihnen angegebene effectiveDate wird mit der Übermittlung und im Audit-Log festgehalten; es erscheint nicht im Response-Body. metadata wird auf dieser Route bewusst nicht akzeptiert – der Wechsel selbst ist das Audit-Ereignis, und das optionale Feld reason liefert den für Menschen lesbaren Kontext.
POST /api/v1/monitoring/loan/payments/{id}/cancel
Entfernt eine zuvor erfasste Zahlung per Soft-Delete. Der Storno-Endpunkt ist die einzige Schnittstelle für Rückabwicklungen im Kreditbereich – es gibt kein PATCH /loans/{id}/adjust, und es wird auch keines geben.
Request
POST /api/v1/monitoring/loan/payments/7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f/cancel HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/jsonBody (optional):
| Feld | Typ | Pflicht | Einschränkung |
|---|---|---|---|
reason | string | null | nein | 1–500 Zeichen; wird im Audit-Ereignis der Stornierung festgehalten. |
Ein leerer Body wird akzeptiert; Sie können den Content-Type-Header ganz weglassen.
Responses
200 OK bei Erfolg:
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"deletedAt": "2026-03-15T11:02:33Z",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false,
"alreadyCancelled": false
}Bei einem zweiten Aufruf für dieselbe Zahlung ist die Response-Form identisch, außer dass alreadyCancelled: true gilt und deletedAt der ursprüngliche Stornierungszeitpunkt ist. Das Flag reused gibt den Idempotenzzustand wieder, während alreadyCancelled anzeigt, ob die Zeile durch diesen Aufruf verändert wurde.
| Status | Envelope | Auslöser |
|---|---|---|
200 OK | { id, deletedAt, bronzeSubmissionId, reused, alreadyCancelled } | Erste oder weitere Stornierung. |
400 Bad Request | fieldErrors | id ist keine wohlgeformte UUID, oder reason überschreitet 500 Zeichen. |
404 Not Found | { error, code: "NOT_FOUND" } | Zahlung existiert nicht oder gehört zu einer anderen Organisation. |
Bei jeder Stornierung – auch bei der zweiten – wird ein Übermittlungsdatensatz geschrieben, damit der Prüfpfad vollständig ist. Die Zeile selbst wird nur beim ersten Aufruf verändert.
Soft-Delete und Wiederverwendung der externalId
Eine stornierte Zahlung gibt ihre externalId für einen künftigen Schreibvorgang frei, weil die Eindeutigkeitsbedingung nur für aktive Zeilen gilt. Um eine fehlerhafte Übermittlung zu korrigieren, ist der kanonische Weg:
POST /api/v1/monitoring/loan/payments/{id}/cancelfür die ursprüngliche Zeile.POST /api/v1/monitoring/loan/paymentsfür eine neue Zeile mit den korrigierten Feldern. Sie dürfen dieselbeexternalIdwiederverwenden; Sie müssen eine andereidangeben.
Das ist beabsichtigt: Stornierungen sind nicht destruktiv (die ursprüngliche Zeile bleibt für Prüfzwecke erhalten), und die Wiederverwendung der externalId hält den operativen Raum der Caller-IDs für den Abgleich lückenlos.