Waafir
Cette page est une traduction automatique en attente de relecture humaine. Elle peut contenir des erreurs.

CRUD unitaire

La surface CRUD unitaire est la voie à faible volume : un appel HTTP par ligne. Utilisez-la pour les écritures opérationnelles — un nouveau prêt, un paiement absent du lot quotidien, une transition de statut — et pour les relectures par UUID de plateforme. Pour les lots de fin de journée, utilisez le NDJSON en masse ; pour les chargements historiques, les imports asynchrones.

Chaque route de cette page respecte le contrat documenté dans la vue d'ensemble : authentification par jeton bearer, garanties d'intégration, enveloppe fieldErrors, sémantique d'annulation et enregistrement de chaque soumission. La documentation route par route ci-dessous ne décrit que les formes propres à chaque route ; reportez-vous à la vue d'ensemble pour le comportement transversal.

Aperçu des routes

MéthodeCheminObjet
POST/api/v1/monitoring/loan/borrowersCréer un emprunteur
GET/api/v1/monitoring/loan/borrowers/{id}Lire un emprunteur par UUID avec masquage des PII
POST/api/v1/monitoring/loan/loansCréer un prêt
POST/api/v1/monitoring/loan/paymentsCréer un paiement effectif
GET/api/v1/monitoring/loan/payments/{id}Lire un paiement effectif par UUID
PATCH/api/v1/monitoring/loan/loans/{loanRef}/statusFaire passer un prêt à un nouveau statut
POST/api/v1/monitoring/loan/payments/{id}/cancelSupprimer logiquement un paiement

Toutes les routes de modification acceptent l'en-tête Idempotency-Key et le paramètre de requête ?dryRun=true, et renvoient l'enveloppe structurée fieldErrors en cas d'échec de validation.

POST /api/v1/monitoring/loan/borrowers

Crée un emprunteur dans le portefeuille identifié par portfolioId.

Requête

POST /api/v1/monitoring/loan/borrowers HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>

Corps :

ChampTypeObligatoireContrainte
idchaîne UUIDouiIdentifiant de plateforme fourni par l'appelant.
portfolioIdchaîne UUIDouiLe portefeuille propriétaire ; il doit exister dans votre organisation.
externalIdchaîneoui1 à 255 caractères ; unique par (portfolio, externalId) pour les lignes actives.
namechaîne | nullnonNom complet de l'emprunteur. Persisté brut ; masqué dans les lectures côté investisseur.
emailchaîne | nullnonE-mail RFC 5322 ; persisté brut ; masqué dans les lectures côté investisseur.
phonechaîne | nullnonTéléphone au format libre ; persisté brut ; masqué dans les lectures côté investisseur.
nationalIdLast4chaîne | nullnonExactement quatre chiffres ; ne renvoie jamais les chiffres de tête.
countryCodechaîne | nullnonCode ISO-3166 à deux lettres (majuscules).
dobchaîne de date | nullnonYYYY-MM-DD.
genderénumération | nullnonmale | female | non_binary | other | undisclosed (insensible à la casse).
incomeBandchaîne | nullnonFormat libre.
employmentStatuschaîne | nullnonFormat libre.
metadataobjet | nullnonTransmis tel quel.

Réponses

201 Created pour une nouvelle écriture, 200 OK pour une relecture idempotente :

{
  "id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
  "externalId": "BORROWER-001",
  "bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
  "reused": false
}
StatutEnveloppeDéclencheur
200 OK{ id, externalId, bronzeSubmissionId, reused: true }Idempotency-Key correspond à une requête antérieure ; aucune nouvelle écriture.
201 Created{ id, externalId, bronzeSubmissionId, reused: false }Nouvelle ligne insérée.
400 Bad RequestfieldErrorsÉchec de validation sur un champ du corps.
404 Not Found{ error, code: "PORTFOLIO_NOT_FOUND" }portfolioId n'existe pas ou appartient à une autre organisation.
409 Conflict{ error, code: "ID_CONFLICT", fieldErrors: [...] }Un emprunteur actif avec le même id existe déjà.

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}

Lit un emprunteur par UUID de plateforme. Les champs PII sont masqués par défaut ; les administrateurs peuvent demander les PII brutes avec ?unmask=true, ce qui écrit une entrée dans le journal d'audit.

Requête

ParamètrePositionObligatoireContrainte
idcheminouiL'UUID de plateforme de l'emprunteur.
unmaskrequêtenontrue renvoie les PII brutes ; réservé aux administrateurs. Masquage par défaut.

Réponses

200 OK avec la fiche d'emprunteur masquée :

{
  "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": {}
}
StatutDéclencheur
200 OKLa ligne existe dans votre organisation. Les PII sont brutes si l'appelant est administrateur ET que ?unmask=true est passé ; sinon, elles sont masquées.
400 Bad Requestid n'est pas un UUID bien formé.
404 Not FoundLa ligne n'existe pas, est annulée ou appartient à une autre organisation.

Le masquage des PII s'applique à name, email, phone et nationalIdLast4. Le champ nationalIdLast4 ne stocke déjà que les quatre derniers chiffres au moment de l'écriture ; le masquage en lecture les cache malgré tout aux lectures non administrateurs.

Un appelant non administrateur qui passe ?unmask=true ne reçoit pas de 403 — la réponse reste 200 avec la forme masquée, et une entrée de journal d'audit consignant la tentative de démasquage refusée est écrite. La plateforme ne présente pas le contrôle de rôle comme une erreur, car la forme masquée est le comportement sûr par défaut ; c'est la piste d'audit qui rend la tentative visible pour l'équipe de sécurité.

Un appelant administrateur qui passe ?unmask=true reçoit les PII brutes, et la requête écrit une entrée distincte dans le journal d'audit consignant le démasquage. La réponse porte Cache-Control: private, no-store pour empêcher les intermédiaires de mettre en cache la charge utile contenant les PII brutes.

POST /api/v1/monitoring/loan/loans

Crée un prêt rattaché à un emprunteur existant du même portefeuille.

Requête

ChampTypeObligatoireContrainte
idchaîne UUIDouiIdentifiant de plateforme fourni par l'appelant.
portfolioIdchaîne UUIDouiLe portefeuille propriétaire.
borrowerIdchaîne UUIDouiUn emprunteur actif du même portefeuille.
externalIdchaîneoui1 à 255 caractères ; unique par portefeuille pour les lignes actives.
predecessorLoanIdchaîne UUID | nullnonRenseigné lors d'une restructuration ; pointe vers le prêt remplacé.
principalAmountchaîne décimaleouiAu plus quatre décimales.
currencyCodechaîneouiISO-4217 à trois lettres ; insensible à la casse.
interestRateAprchaîne décimaleouiAu plus six décimales ; doit être >= 0.
disbursementDatechaîne de dateouiYYYY-MM-DD.
termMonthsentierouiDoit être > 0.
repaymentFrequencyénumérationouimonthly | weekly | biweekly | quarterly | bullet (insensible à la casse).
productTypechaîne | nullnonFormat libre, par ex. « Term loan », « Overdraft ».
statusénumérationouipending | active | paid_off | restructured | written_off | defaulted (insensible à la casse).
metadataobjet | nullnonTransmis tel quel.

Réponses

201 Created (ou 200 OK en cas de relecture idempotente) avec { id, externalId, bronzeSubmissionId, reused }.

StatutEnveloppeDéclencheur
200 OK{ ..., reused: true }Relecture idempotente.
201 Created{ ..., reused: false }Nouveau prêt inséré.
400 Bad RequestfieldErrorsÉchec de validation (par ex. interestRateApr négatif, currencyCode mal formé).
404 Not Found{ error, code: "PORTFOLIO_NOT_FOUND" }Portefeuille absent ou d'une autre organisation.
409 Conflict{ error, code: "ID_CONFLICT" }Un prêt actif avec le même id existe déjà.
422 Unprocessable Entity{ error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "borrowerId", ... }] }borrowerId ne correspond à aucun emprunteur actif du même portefeuille.

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

Enregistre un paiement effectif sur un prêt existant. À utiliser pour les paiements reçus, les paiements partiels et les passages en perte. Les restructurations sont modélisées comme un nouveau prêt dont predecessorLoanId est renseigné, et non comme un paiement.

Requête

ChampTypeObligatoireContrainte
idchaîne UUIDouiIdentifiant de plateforme fourni par l'appelant.
portfolioIdchaîne UUIDouiLe portefeuille propriétaire.
loanIdchaîne UUIDouiUn prêt actif du même portefeuille.
externalIdchaîneoui1 à 255 caractères ; unique par portefeuille pour les lignes actives.
paymentDatechaîne de dateouiYYYY-MM-DD.
amountchaîne décimaleouiLe montant total du paiement reçu.
currencyCodechaîneouiISO-4217.
principalPaidchaîne décimalenon"0" par défaut.
interestPaidchaîne décimalenon"0" par défaut.
feesPaidchaîne décimalenon"0" par défaut.
writeOffAmountchaîne décimalenon"0" par défaut. Voir la règle d'abandon de créance ci-dessous.
paymentNoteschaîne | nullnonDoit valoir "Forgiven" (insensible à la casse) lorsque writeOffAmount > 0.
paymentMethodénumération | nullnoncash | bank_transfer | card | mobile_money | check | other.
metadataobjet | nullnonTransmis tel quel.

Règle d'abandon de créance. Si writeOffAmount > 0, paymentNotes doit être égal à "Forgiven" sans tenir compte de la casse. La plateforme fait échouer la requête dès la frontière de l'API, de sorte qu'un paiement incorrect est refusé avant que quoi que ce soit ne soit enregistré.

Réponses

201 Created (ou 200 OK en cas de relecture idempotente) avec { id, externalId, bronzeSubmissionId, reused }.

StatutEnveloppeDéclencheur
200 OK{ ..., reused: true }Relecture idempotente.
201 Created{ ..., reused: false }Nouveau paiement inséré.
400 Bad RequestfieldErrorsÉchec de validation (montants mal formés, valeur d'énumération inconnue, champ obligatoire manquant).
404 Not Found{ error, code: "PORTFOLIO_NOT_FOUND" }Portefeuille absent ou d'une autre organisation.
409 Conflict{ error, code: "ID_CONFLICT" }Un paiement actif avec le même id existe déjà.
422 Unprocessable Entity{ error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "loanId", ... }] }loanId ne correspond à aucun prêt actif du même portefeuille.
400 Bad Request{ error, code: "CHECK_VIOLATION", fieldErrors: [...] }La règle d'abandon de créance a été rejetée au moment du stockage du paiement (rare ; la validation rejette la même forme en amont).

GET /api/v1/monitoring/loan/payments/{id}

Lit un paiement effectif par UUID de plateforme, y compris les lignes annulées (supprimées logiquement). À utiliser pour vérifier une écriture ou examiner une fiche annulée.

Requête

ParamètrePositionObligatoireContrainte
idcheminouiL'UUID de plateforme du paiement.

Réponses

200 OK avec la fiche de paiement complète. Les lignes annulées apparaissent avec deletedAt renseigné ; les lignes actives ont deletedAt: null. 404 Not Found pour un UUID d'une autre organisation ou inconnu. 400 Bad Request si id n'est pas un UUID bien formé.

PATCH /api/v1/monitoring/loan/loans/{loanRef}/status

Fait passer un prêt à un nouveau statut. Le segment de chemin {loanRef} accepte soit l'UUID de plateforme du prêt, soit son externalId. Lorsque vous passez un externalId, vous devez aussi fournir ?portfolioId=<UUID>, car les identifiants externes ne sont pas uniques d'un portefeuille à l'autre.

Requête

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>

Corps :

ChampTypeObligatoireContrainte
statusénumérationouiL'une des valeurs active | paid_off | defaulted | written_off | restructured (insensible à la casse).
effectiveDatechaîne de dateouiYYYY-MM-DD.
reasonchaîne | nullnon1 à 500 caractères ; consigné dans le journal d'audit.

Matrice des transitions de statut

La plateforme applique une matrice de transitions ; une transition invalide renvoie 422 INVALID_STATUS_TRANSITION avec des fieldErrors nommant les états de départ et d'arrivée.

DeCibles autorisées
pendingactive
activepaid_off, defaulted, written_off, restructured
paid_off(terminal)
defaultedwritten_off, restructured
written_off(terminal)
restructured(terminal)

Lorsque vous faites passer un prêt à restructured, la suite naturelle est un POST /loans pour le prêt de remplacement avec predecessorLoanId renseigné. Les deux écritures ne sont volontairement pas atomiques — si le POST de remplacement échoue, le prédécesseur reste à restructured et la surface de rapprochement fera apparaître l'écart lors de votre prochaine requête.

Réponses

200 OK en cas de succès :

{
  "id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "externalId": "LOAN-001",
  "status": "restructured",
  "bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
  "reused": false
}
StatutEnveloppeDéclencheur
200 OK{ id, externalId, status, bronzeSubmissionId, reused }Transition appliquée (ou relecture idempotente avec reused: true).
400 Bad RequestfieldErrorsÉchec de validation du corps, portfolioId manquant lors d'une recherche par externalId, énumération mal formée.
404 Not Found{ error, code: "NOT_FOUND" }Prêt introuvable par UUID, ou (portfolioId, externalId) ne correspond à rien.
422 Unprocessable Entity{ error, code: "INVALID_STATUS_TRANSITION", fieldErrors: [...] }Le couple départ/arrivée ne figure pas dans la matrice de transitions ; fieldErrors[].message liste les cibles autorisées.
409 Conflict{ error, code: "IDEMPOTENCY_CONFLICT" }L'Idempotency-Key a déjà servi pour une autre transition. L'écriture précédente est conservée ; envoyez la nouvelle transition avec une nouvelle clé.

La valeur effectiveDate que vous fournissez est consignée avec la soumission et dans le journal d'audit ; elle n'apparaît pas dans le corps de la réponse. metadata n'est volontairement pas accepté sur cette route — la transition elle-même constitue l'événement d'audit, et le champ facultatif reason porte le contexte lisible.

POST /api/v1/monitoring/loan/payments/{id}/cancel

Supprime logiquement un paiement précédemment enregistré. L'endpoint d'annulation est la seule surface de contre-passation du domaine des prêts — il n'existe pas de PATCH /loans/{id}/adjust et il n'y en aura pas.

Requête

POST /api/v1/monitoring/loan/payments/7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f/cancel HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json

Corps (facultatif) :

ChampTypeObligatoireContrainte
reasonchaîne | nullnon1 à 500 caractères ; consigné sur l'événement d'audit d'annulation.

Un corps vide est accepté ; vous pouvez omettre entièrement l'en-tête Content-Type.

Réponses

200 OK en cas de succès :

{
  "id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "deletedAt": "2026-03-15T11:02:33Z",
  "bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
  "reused": false,
  "alreadyCancelled": false
}

Lors d'un second appel sur le même paiement, la forme de la réponse est identique, à ceci près que alreadyCancelled: true et que deletedAt correspond à l'horodatage de l'annulation d'origine. L'indicateur reused reflète l'état d'idempotence, tandis que alreadyCancelled indique si la ligne a été modifiée par cet appel.

StatutEnveloppeDéclencheur
200 OK{ id, deletedAt, bronzeSubmissionId, reused, alreadyCancelled }Première annulation ou annulation suivante.
400 Bad RequestfieldErrorsid n'est pas un UUID bien formé, ou reason dépasse 500 caractères.
404 Not Found{ error, code: "NOT_FOUND" }Le paiement n'existe pas ou appartient à une autre organisation.

Un enregistrement de soumission est écrit à chaque annulation — y compris la seconde — par souci d'exhaustivité de l'audit. La ligne n'est modifiée qu'au premier appel.

Suppression logique et réutilisation de l'externalId

Un paiement annulé laisse son externalId disponible pour une écriture ultérieure, car la contrainte d'unicité ne s'applique qu'aux lignes actives. Pour corriger une soumission erronée, la démarche canonique est la suivante :

  1. POST /api/v1/monitoring/loan/payments/{id}/cancel sur la ligne d'origine.
  2. POST /api/v1/monitoring/loan/payments pour une nouvelle ligne avec les champs corrigés. Vous pouvez réutiliser le même externalId ; vous devez fournir un id différent.

Ce comportement est voulu : les annulations ne sont pas destructives (la ligne d'origine est conservée à des fins d'audit), et la réutilisation de l'externalId maintient un espace d'identifiants appelant dense pour les besoins du rapprochement.