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éthode | Chemin | Objet |
|---|---|---|
POST | /api/v1/monitoring/loan/borrowers | Créer un emprunteur |
GET | /api/v1/monitoring/loan/borrowers/{id} | Lire un emprunteur par UUID avec masquage des PII |
POST | /api/v1/monitoring/loan/loans | Créer un prêt |
POST | /api/v1/monitoring/loan/payments | Créer un paiement effectif |
GET | /api/v1/monitoring/loan/payments/{id} | Lire un paiement effectif par UUID |
PATCH | /api/v1/monitoring/loan/loans/{loanRef}/status | Faire passer un prêt à un nouveau statut |
POST | /api/v1/monitoring/loan/payments/{id}/cancel | Supprimer 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 :
| Champ | Type | Obligatoire | Contrainte |
|---|---|---|---|
id | chaîne UUID | oui | Identifiant de plateforme fourni par l'appelant. |
portfolioId | chaîne UUID | oui | Le portefeuille propriétaire ; il doit exister dans votre organisation. |
externalId | chaîne | oui | 1 à 255 caractères ; unique par (portfolio, externalId) pour les lignes actives. |
name | chaîne | null | non | Nom complet de l'emprunteur. Persisté brut ; masqué dans les lectures côté investisseur. |
email | chaîne | null | non | E-mail RFC 5322 ; persisté brut ; masqué dans les lectures côté investisseur. |
phone | chaîne | null | non | Téléphone au format libre ; persisté brut ; masqué dans les lectures côté investisseur. |
nationalIdLast4 | chaîne | null | non | Exactement quatre chiffres ; ne renvoie jamais les chiffres de tête. |
countryCode | chaîne | null | non | Code ISO-3166 à deux lettres (majuscules). |
dob | chaîne de date | null | non | YYYY-MM-DD. |
gender | énumération | null | non | male | female | non_binary | other | undisclosed (insensible à la casse). |
incomeBand | chaîne | null | non | Format libre. |
employmentStatus | chaîne | null | non | Format libre. |
metadata | objet | null | non | Transmis 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
}| Statut | Enveloppe | Dé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 Request | fieldErrors | É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ètre | Position | Obligatoire | Contrainte |
|---|---|---|---|
id | chemin | oui | L'UUID de plateforme de l'emprunteur. |
unmask | requête | non | true 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": {}
}| Statut | Déclencheur |
|---|---|
200 OK | La 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 Request | id n'est pas un UUID bien formé. |
404 Not Found | La 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
| Champ | Type | Obligatoire | Contrainte |
|---|---|---|---|
id | chaîne UUID | oui | Identifiant de plateforme fourni par l'appelant. |
portfolioId | chaîne UUID | oui | Le portefeuille propriétaire. |
borrowerId | chaîne UUID | oui | Un emprunteur actif du même portefeuille. |
externalId | chaîne | oui | 1 à 255 caractères ; unique par portefeuille pour les lignes actives. |
predecessorLoanId | chaîne UUID | null | non | Renseigné lors d'une restructuration ; pointe vers le prêt remplacé. |
principalAmount | chaîne décimale | oui | Au plus quatre décimales. |
currencyCode | chaîne | oui | ISO-4217 à trois lettres ; insensible à la casse. |
interestRateApr | chaîne décimale | oui | Au plus six décimales ; doit être >= 0. |
disbursementDate | chaîne de date | oui | YYYY-MM-DD. |
termMonths | entier | oui | Doit être > 0. |
repaymentFrequency | énumération | oui | monthly | weekly | biweekly | quarterly | bullet (insensible à la casse). |
productType | chaîne | null | non | Format libre, par ex. « Term loan », « Overdraft ». |
status | énumération | oui | pending | active | paid_off | restructured | written_off | defaulted (insensible à la casse). |
metadata | objet | null | non | Transmis tel quel. |
Réponses
201 Created (ou 200 OK en cas de relecture idempotente) avec { id, externalId, bronzeSubmissionId, reused }.
| Statut | Enveloppe | Déclencheur |
|---|---|---|
200 OK | { ..., reused: true } | Relecture idempotente. |
201 Created | { ..., reused: false } | Nouveau prêt inséré. |
400 Bad Request | fieldErrors | É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
| Champ | Type | Obligatoire | Contrainte |
|---|---|---|---|
id | chaîne UUID | oui | Identifiant de plateforme fourni par l'appelant. |
portfolioId | chaîne UUID | oui | Le portefeuille propriétaire. |
loanId | chaîne UUID | oui | Un prêt actif du même portefeuille. |
externalId | chaîne | oui | 1 à 255 caractères ; unique par portefeuille pour les lignes actives. |
paymentDate | chaîne de date | oui | YYYY-MM-DD. |
amount | chaîne décimale | oui | Le montant total du paiement reçu. |
currencyCode | chaîne | oui | ISO-4217. |
principalPaid | chaîne décimale | non | "0" par défaut. |
interestPaid | chaîne décimale | non | "0" par défaut. |
feesPaid | chaîne décimale | non | "0" par défaut. |
writeOffAmount | chaîne décimale | non | "0" par défaut. Voir la règle d'abandon de créance ci-dessous. |
paymentNotes | chaîne | null | non | Doit valoir "Forgiven" (insensible à la casse) lorsque writeOffAmount > 0. |
paymentMethod | énumération | null | non | cash | bank_transfer | card | mobile_money | check | other. |
metadata | objet | null | non | Transmis 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 }.
| Statut | Enveloppe | Déclencheur |
|---|---|---|
200 OK | { ..., reused: true } | Relecture idempotente. |
201 Created | { ..., reused: false } | Nouveau paiement inséré. |
400 Bad Request | fieldErrors | É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ètre | Position | Obligatoire | Contrainte |
|---|---|---|---|
id | chemin | oui | L'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 :
| Champ | Type | Obligatoire | Contrainte |
|---|---|---|---|
status | énumération | oui | L'une des valeurs active | paid_off | defaulted | written_off | restructured (insensible à la casse). |
effectiveDate | chaîne de date | oui | YYYY-MM-DD. |
reason | chaîne | null | non | 1 à 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.
| De | Cibles autorisées |
|---|---|
pending | active |
active | paid_off, defaulted, written_off, restructured |
paid_off | (terminal) |
defaulted | written_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
}| Statut | Enveloppe | Déclencheur |
|---|---|---|
200 OK | { id, externalId, status, bronzeSubmissionId, reused } | Transition appliquée (ou relecture idempotente avec reused: true). |
400 Bad Request | fieldErrors | É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/jsonCorps (facultatif) :
| Champ | Type | Obligatoire | Contrainte |
|---|---|---|---|
reason | chaîne | null | non | 1 à 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.
| Statut | Enveloppe | Déclencheur |
|---|---|---|
200 OK | { id, deletedAt, bronzeSubmissionId, reused, alreadyCancelled } | Première annulation ou annulation suivante. |
400 Bad Request | fieldErrors | id 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 :
POST /api/v1/monitoring/loan/payments/{id}/cancelsur la ligne d'origine.POST /api/v1/monitoring/loan/paymentspour une nouvelle ligne avec les champs corrigés. Vous pouvez réutiliser le mêmeexternalId; vous devez fournir uniddiffé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.