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

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

MethodePfadZweck
POST/api/v1/monitoring/loan/borrowersKreditnehmer anlegen
GET/api/v1/monitoring/loan/borrowers/{id}Kreditnehmer per UUID lesen, mit PII-Maskierung
POST/api/v1/monitoring/loan/loansKredit anlegen
POST/api/v1/monitoring/loan/paymentsTatsächliche Zahlung anlegen
GET/api/v1/monitoring/loan/payments/{id}Tatsächliche Zahlung per UUID lesen
PATCH/api/v1/monitoring/loan/loans/{loanRef}/statusKredit in einen neuen Status überführen
POST/api/v1/monitoring/loan/payments/{id}/cancelZahlung 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:

FeldTypPflichtEinschränkung
idUUID-StringjaVom Aufrufer vergebene Plattformkennung.
portfolioIdUUID-StringjaDas zugehörige Portfolio; muss in Ihrer Organisation existieren.
externalIdstringja1–255 Zeichen; eindeutig pro (portfolio, externalId) unter aktiven Zeilen.
namestring | nullneinVollständiger Name des Kreditnehmers. Wird unverändert gespeichert; Lesezugriffe für Investoren maskieren.
emailstring | nullneinE-Mail nach RFC 5322; wird unverändert gespeichert; Lesezugriffe für Investoren maskieren.
phonestring | nullneinTelefonnummer im freien Format; wird unverändert gespeichert; Lesezugriffe für Investoren maskieren.
nationalIdLast4string | nullneinGenau vier Ziffern; die vorangehenden Ziffern werden nie zurückgegeben.
countryCodestring | nullneinZweistelliger ISO-3166-Code (Großbuchstaben).
dobDatums-String | nullneinYYYY-MM-DD.
genderenum | nullneinmale | female | non_binary | other | undisclosed (ohne Beachtung der Groß-/Kleinschreibung).
incomeBandstring | nullneinFreies Format.
employmentStatusstring | nullneinFreies Format.
metadataobject | nullneinUnverä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
}
StatusEnvelopeAuslö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 RequestfieldErrorsValidierungsfehler 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

ParameterPositionPflichtEinschränkung
idPfadjaDie Plattform-UUID des Kreditnehmers.
unmaskQueryneintrue 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": {}
}
StatusAuslöser
200 OKZeile existiert in Ihrer Organisation. PII sind unmaskiert, wenn der Aufrufer Admin ist UND ?unmask=true gesetzt ist; andernfalls sind PII maskiert.
400 Bad Requestid ist keine wohlgeformte UUID.
404 Not FoundZeile 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

FeldTypPflichtEinschränkung
idUUID-StringjaVom Aufrufer vergebene Plattformkennung.
portfolioIdUUID-StringjaDas zugehörige Portfolio.
borrowerIdUUID-StringjaEin aktiver Kreditnehmer im selben Portfolio.
externalIdstringja1–255 Zeichen; eindeutig pro Portfolio unter aktiven Zeilen.
predecessorLoanIdUUID-String | nullneinWird bei einer Restrukturierung gesetzt; verweist auf den ersetzten Kredit.
principalAmountDezimal-StringjaBis zu vier Nachkommastellen.
currencyCodestringjaDreistelliger ISO-4217-Code; ohne Beachtung der Groß-/Kleinschreibung.
interestRateAprDezimal-StringjaBis zu sechs Nachkommastellen; muss >= 0 sein.
disbursementDateDatums-StringjaYYYY-MM-DD.
termMonthsintegerjaMuss > 0 sein.
repaymentFrequencyenumjamonthly | weekly | biweekly | quarterly | bullet (ohne Beachtung der Groß-/Kleinschreibung).
productTypestring | nullneinFreies Format, z. B. "Term loan", "Overdraft".
statusenumjapending | active | paid_off | restructured | written_off | defaulted (ohne Beachtung der Groß-/Kleinschreibung).
metadataobject | nullneinUnveränderte Durchreichung.

Responses

201 Created (oder 200 OK bei idempotenter Wiederholung) mit { id, externalId, bronzeSubmissionId, reused }.

StatusEnvelopeAuslöser
200 OK{ ..., reused: true }Idempotente Wiederholung.
201 Created{ ..., reused: false }Neuer Kredit eingefügt.
400 Bad RequestfieldErrorsValidierungsfehler (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

FeldTypPflichtEinschränkung
idUUID-StringjaVom Aufrufer vergebene Plattformkennung.
portfolioIdUUID-StringjaDas zugehörige Portfolio.
loanIdUUID-StringjaEin aktiver Kredit im selben Portfolio.
externalIdstringja1–255 Zeichen; eindeutig pro Portfolio unter aktiven Zeilen.
paymentDateDatums-StringjaYYYY-MM-DD.
amountDezimal-StringjaDer insgesamt eingegangene Zahlungsbetrag.
currencyCodestringjaISO-4217.
principalPaidDezimal-StringneinStandardwert "0".
interestPaidDezimal-StringneinStandardwert "0".
feesPaidDezimal-StringneinStandardwert "0".
writeOffAmountDezimal-StringneinStandardwert "0". Siehe Regel zum Forderungsverzicht unten.
paymentNotesstring | nullneinMuss "Forgiven" sein (ohne Beachtung der Groß-/Kleinschreibung), wenn writeOffAmount > 0.
paymentMethodenum | nullneincash | bank_transfer | card | mobile_money | check | other.
metadataobject | nullneinUnverä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 }.

StatusEnvelopeAuslöser
200 OK{ ..., reused: true }Idempotente Wiederholung.
201 Created{ ..., reused: false }Neue Zahlung eingefügt.
400 Bad RequestfieldErrorsValidierungsfehler (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

ParameterPositionPflichtEinschränkung
idPfadjaDie 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:

FeldTypPflichtEinschränkung
statusenumjaEiner von active | paid_off | defaulted | written_off | restructured (ohne Beachtung der Groß-/Kleinschreibung).
effectiveDateDatums-StringjaYYYY-MM-DD.
reasonstring | nullnein1–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.

VonZulässige Ziele
pendingactive
activepaid_off, defaulted, written_off, restructured
paid_off(Endzustand)
defaultedwritten_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
}
StatusEnvelopeAuslöser
200 OK{ id, externalId, status, bronzeSubmissionId, reused }Wechsel angewendet (oder idempotente Wiederholung mit reused: true).
400 Bad RequestfieldErrorsValidierungsfehler 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/json

Body (optional):

FeldTypPflichtEinschränkung
reasonstring | nullnein1–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.

StatusEnvelopeAuslöser
200 OK{ id, deletedAt, bronzeSubmissionId, reused, alreadyCancelled }Erste oder weitere Stornierung.
400 Bad RequestfieldErrorsid 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:

  1. POST /api/v1/monitoring/loan/payments/{id}/cancel für die ursprüngliche Zeile.
  2. POST /api/v1/monitoring/loan/payments für eine neue Zeile mit den korrigierten Feldern. Sie dürfen dieselbe externalId wiederverwenden; Sie müssen eine andere id angeben.

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.