Vue d'ensemble
Chaque endpoint du domaine des prêts partage le contrat décrit sur cette page. Lisez-la en premier ; les pages consacrées à chaque surface y renvoient plutôt que de le répéter.
URL de base et versionnement
Toutes les routes du domaine des prêts sont montées sous /api/v1/monitoring/loan/. L'entier qui suit v est la version majeure : un changement de version majeure constitue une rupture de compatibilité et n'intervient qu'après un avis de dépréciation explicite. Au sein d'une version majeure, l'évolution est uniquement additive — nouveaux champs facultatifs, nouveaux endpoints, nouvelles valeurs d'énumération — et ne casse jamais une intégration qui ignore les champs qu'elle ne comprend pas.
L'hôte de production est https://app.waafir.io. Pour obtenir une URL complète, ajoutez l'hôte devant n'importe quel chemin de ce site de référence, par exemple https://app.waafir.io/api/v1/monitoring/loan/borrowers.
Authentification
Chaque requête porte un en-tête Authorization contenant un jeton Bearer :
Authorization: Bearer <PAT><PAT> est un jeton d'accès personnel émis depuis le plan de contrôle Waafir pour une seule organisation. L'organisation du jeton détermine le périmètre de locataire de chaque lecture et de chaque écriture — aucune URL ni aucun corps ne comporte de paramètre d'organisation, puisque le jeton la fixe déjà.
Les requêtes inter-organisations renvoient 404 Not Found, et non 403 Forbidden. Renvoyer 403 divulguerait l'existence de la ressource d'un autre locataire à partir de son identifiant ; la posture 404 traite de la même manière les identifiants inconnus et ceux d'un autre locataire.
Une requête sans en-tête Authorization, avec un jeton inconnu ou avec un jeton révoqué renvoie 401 Unauthorized.
Garanties d'intégration
Chaque route de modification respecte les garanties ci-dessous. Votre code client peut s'appuyer sur chacune d'elles ; les lire une fois ici vous permet de réaliser une intégration robuste en une seule passe.
Identifiants fournis par l'appelant
Chaque entité possède dans le corps de sa requête un champ id que vous fournissez sous forme d'UUID. La plateforme n'invente jamais d'identifiant à votre place. C'est le fondement de tous les autres engagements de cette liste : l'idempotence, le rapprochement et la relecture reposent tous sur votre capacité à désigner une ligne par un identifiant que vous avez choisi.
Si vous renvoyez par POST une ligne avec le même id, vous recevez 409 ID_CONFLICT et une entrée fieldErrors pointant vers id. Choisissez vos identifiants avec soin — des UUIDv4 générés sont recommandés, mais tout UUID bien formé convient.
En plus de id, chaque entité porte aussi un externalId — une chaîne libre de 255 caractères au maximum qui vous sert à désigner la ligne depuis votre propre système. Un externalId est unique au sein d'un portefeuille pour les lignes actives, ce qui rend possible le rapprochement par identifiant appelant.
En-tête Idempotency-Key
Chaque route de modification lit un en-tête HTTP facultatif Idempotency-Key. Lorsqu'il est présent, la plateforme déduplique à l'aide d'une archive interne : une seconde requête avec la même clé renvoie la même réponse que la première, même si le corps diffère légèrement. C'est ainsi que les clients survivent aux coupures réseau qui les laissent dans l'incertitude quant à l'aboutissement d'une requête.
L'en-tête est insensible à la casse sur le réseau (Idempotency-Key, idempotency-key, IDEMPOTENCY-KEY fonctionnent tous). La valeur est traitée comme opaque — choisissez n'importe quelle valeur stable par opération logique, typiquement un UUIDv4 accompagné d'un discriminant de route.
?dryRun=true
Chaque route de modification accepte un paramètre de requête ?dryRun=true. Une requête de simulation exécute la validation et les contrôles de locataire et renvoie l'entrée validée, mais n'enregistre rien et ne stocke aucune ligne. Utilisez-la pour confirmer qu'un corps est correctement analysé avant de lancer une véritable écriture.
En cas de simulation réussie, la réponse a la forme { "dryRun": true, "validatedInput": <body> } avec un 200 OK. Les échecs de validation pendant une simulation renvoient la même forme 400 qu'une véritable écriture ; seuls les effets de bord diffèrent.
Enveloppe de validation fieldErrors
Les échecs de validation renvoient 400 Bad Request avec une enveloppe structurée :
{
"error": "Validation failed",
"fieldErrors": [
{ "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
{ "path": "termMonths", "message": "termMonths must be > 0" }
]
}path est le chemin pointé vers le champ en cause ; message est une explication lisible. L'enveloppe est uniforme sur toutes les routes, de sorte qu'un seul gestionnaire côté client peut afficher chaque échec de validation de façon cohérente.
Énumérations insensibles à la casse avec suggestions « vouliez-vous dire »
Les énumérations du domaine (statut du prêt, mode de paiement, fréquence de remboursement, code de devise, etc.) acceptent n'importe quelle casse sur le réseau. La plateforme les normalise sous leur forme canonique en minuscules avant de les persister.
Une valeur non reconnue renvoie 400 avec une entrée fieldErrors qui nomme la valeur en cause et suggère la valeur acceptée la plus proche :
{
"error": "Validation failed",
"fieldErrors": [
{
"path": "status",
"message": "got 'restruktured', did you mean 'restructured'?"
}
]
}La suggestion est calculée à l'aide d'une petite métrique de distance d'édition, de sorte que les inversions de caractères et les fautes de frappe isolées sont détectées de manière fiable.
Transmission telle quelle de metadata (JSONB)
Chaque entité accepte un champ facultatif metadata de type objet. La plateforme persiste l'objet tel quel — aucune clé n'est supprimée, aucune valeur n'est convertie. Utilisez-le pour joindre un contexte côté client que la plateforme elle-même n'a pas besoin de comprendre : votre identifiant interne, le système source, un horodatage d'extraction, un code de campagne.
Deux surfaces n'acceptent pas metadata : la transition de statut d'un prêt et les routes d'annulation de paiement. La justification est documentée directement sur ces routes.
Rapprochement par identifiant appelant
Chaque entité peut être désignée par l'externalId que vous avez soumis, dans le périmètre d'un portefeuille. La surface de rapprochement — GET /loans/{externalId} et GET /counts — s'en sert pour vous permettre de vérifier vos écritures sans jamais avoir besoin de l'UUID attribué par la plateforme. Consultez la page Rapprochement pour les formes exactes.
Représentation des montants
Les valeurs monétaires sont transmises sous forme de chaînes de chiffres décimaux, avec au plus quatre décimales. Le type JavaScript number est refusé, car les flottants binaires IEEE-754 ne peuvent pas représenter exactement les centimes décimaux :
{ "amount": "100.50", "currencyCode": "USD" }Un décimal comportant plus de quatre décimales, ou une valeur contenant d'autres caractères que des chiffres, un signe moins initial et un seul point, renvoie 400 avec une entrée fieldErrors. Les chaînes vides sont refusées.
Les codes de devise sont des codes ISO-4217 à trois lettres. La plateforme reconnaît explicitement l'ensemble courant ; les codes inconnus respectant la forme de trois lettres majuscules sont acceptés et persistés tels quels, afin de ne pas bloquer les codes des marchés exotiques.
Format des dates
Les dates sont transmises sous forme de chaînes de date calendaire ISO-8601 au format YYYY-MM-DD :
{ "disbursementDate": "2026-01-15" }Il n'y a pas de composante de fuseau horaire. Les dates sont des dates calendaires selon l'interprétation du portefeuille ; la plateforme n'effectue aucune conversion.
Sémantique d'annulation
Les appels d'API n'effacent jamais une ligne. Une annulation ou toute autre contre-passation marque plutôt la ligne comme annulée. Les conséquences :
- Une annulation ne libère pas l'
externalId. UnexternalIdest unique au sein d'un portefeuille parmi les lignes actives uniquement. Une ligne annulée n'est plus active ; vous pouvez donc réutiliser sonexternalIdpour une nouvelle soumission corrigée. - Les lectures de rapprochement ne renvoient pas les lignes annulées par défaut. Les surfaces
GET /loans/{externalId}etGET /countsexcluent de leur réponse par défaut les lignes supprimées logiquement. - Les enregistrements de soumission sont conservés dans tous les cas. Même lorsqu'une ligne est annulée, l'enregistrement de la soumission qui l'a créée reste intact à des fins d'audit.
Chaque soumission est enregistrée
Chaque modification réussie enregistre le corps brut de la requête avant l'écriture de la ligne. Les conséquences pour votre intégration :
- Un
200/201signifie que votre soumission est enregistrée de façon durable, même si un traitement en aval la signale ensuite. Votre piste d'audit commence dès que la plateforme accuse réception de la requête. - Un
409 ID_CONFLICTest tout de même archivé. L'enregistrement de soumission conserve à la fois le conflit et la soumission tentée, ce qui vous permet d'enquêter plus tard sans ambiguïté sur ce qui a été envoyé. - Les imports asynchrones sont enregistrés au moment de la validation (commit). Le fichier NDJSON téléversé et l'import lui-même constituent l'enregistrement ; il n'existe pas d'enregistrement distinct par ligne pour un import asynchrone.
L'enregistrement de soumission ne peut pas être modifié. Vous ne le lisez jamais directement via l'API publique, mais c'est lui qui rend la surface de rapprochement faisant foi — chaque ligne visible à cet endroit est adossée à une entrée d'archive correspondante.
Organisation du reste de cette référence
Chaque page suivante de ce site de référence documente un mode d'ingestion ou la surface de rapprochement. Chaque page de route suit la même structure : un objectif en une phrase, la forme de la requête (en-têtes, paramètres de requête, corps), la forme de la réponse pour chaque code de statut et un appel cURL minimal. Les contraintes champ par champ figurent dans des tableaux faciles à parcourir ; les exemples approfondis et les extraits de code en trois langages se trouvent dans les Recettes.
La page Erreurs et codes de statut est la référence consolidée des enveloppes de réponse utilisées par chaque route de ce site. Lisez-la une fois avant l'intégration ; revenez-y chaque fois qu'un statut autre que 200 vous surprend.