Référence de l'API
Cette section est le manuel de référence de l'API du domaine des prêts de Waafir — la surface HTTP qu'utilisent les fintechs pour transmettre en continu les données de leur portefeuille à Waafir à des fins de suivi par les investisseurs. Elle documente chaque route sous /api/v1/monitoring/loan/, les schémas de requête et de réponse, chaque code de statut, le contrat commun d'expérience développeur et les enveloppes d'erreur auxquelles vous devez vous attendre.
La référence est exhaustive mais non narrative. Si vous intégrez l'API pour la première fois et souhaitez une recette guidée de bout en bout — avec cURL, TypeScript et Python côte à côte — lisez les Recettes en parallèle de cette référence ; les deux sont conçues pour être lues ensemble.
Ce que couvre l'API
L'API du domaine des prêts expose quatre modes d'ingestion ainsi qu'une surface de rapprochement :
- CRUD unitaire — un appel HTTP par ligne. À utiliser pour les écritures opérationnelles à faible volume : un nouveau prêt, un paiement, une transition de statut.
- NDJSON en masse — jusqu'à dix mille lignes en un seul appel synchrone. À utiliser pour les lots de fin de journée qui tiennent dans une seule requête HTTP.
- Imports asynchrones — un téléversement direct de fichier suivi d'un traitement asynchrone. À utiliser pour les chargements historiques ou tout lot de plus de dix mille lignes.
- Rapprochement — relecture des lignes soumises à l'aide de vos propres identifiants appelant, et nombre de lignes par entité. À utiliser pour vérifier que la soumission d'hier est bien arrivée avant d'envoyer celle d'aujourd'hui.
Chaque mode est décrit sur sa propre page. L'ordre des pages suit celui que parcourent la plupart des intégrateurs : lisez la vue d'ensemble, puis le mode d'ingestion que vous comptez utiliser en premier, puis le rapprochement, puis la référence des erreurs.
Les six entités du domaine des prêts
Chaque route agit sur une ou plusieurs des entités suivantes. Leurs schémas complets sont documentés route par route — cette liste en est le catalogue :
borrower— la personne physique ou morale qui contracte le prêt, avec des champs PII facultatifs masqués en lecture.loan— le contrat de prêt lui-même : principal, devise, APR, durée, fréquence de remboursement, statut.scheduled_repayment— l'échéancier contractuel de remboursement, une ligne par date d'échéance.actual_payment— les paiements effectivement reçus, y compris les passages en perte et les paiements partiels.collateral— la garantie nantie au titre d'un prêt.collateral_valuation— les évaluations à une date donnée d'une ligne de garantie, avec prise en charge de plusieurs méthodes.
Chaque entité appartient à un portefeuille de votre organisation. Le portefeuille est fourni à chaque écriture ; l'organisation est déduite de votre jeton d'accès personnel et n'apparaît jamais dans le corps d'une requête.
L'authentification en une ligne
Chaque requête porte Authorization: Bearer <PAT>, où <PAT> est un jeton d'accès personnel émis par le plan de contrôle Waafir. Les jetons sont limités à une organisation — un jeton émis pour l'organisation A ne peut ni lire ni écrire les données de l'organisation B, et les lectures inter-organisations renvoient 404 Not Found plutôt que 403 Forbidden afin de ne pas divulguer l'existence des ressources d'un autre locataire.
Le modèle complet d'authentification et d'autorisation est décrit dans la vue d'ensemble.
Comment utiliser cette référence
Lisez les pages dans l'ordre, ou allez directement à la surface dont vous avez besoin :
- Vue d'ensemble — le contrat commun que respecte chaque route du domaine des prêts : authentification, garanties d'intégration (identifiants fournis par l'appelant, idempotence, simulations), enveloppes d'erreur, conventions de montants et de dates, sémantique d'annulation et enregistrement de chaque soumission.
- CRUD unitaire — chaque route unitaire POST, GET, PATCH et d'annulation.
- NDJSON en masse — ingestion synchrone en masse avec rapport d'erreurs par ligne.
- Imports asynchrones — le cycle de vie en deux phases : téléversement, interrogation du statut et pagination des erreurs.
- Rapprochement — relecture par identifiant appelant et nombre de lignes par entité.
- Erreurs et codes de statut — le catalogue consolidé de chaque code de statut, enveloppe d'erreur et code d'erreur nommé émis par la surface du domaine des prêts.
Pour des guides orientés tâches — intégrer un portefeuille de bout en bout, exécuter un rapprochement quotidien, se remettre d'un import partiellement échoué — consultez les Recettes (publiées en même temps que cette référence). Les Recettes présentent chaque tâche dans trois langages ; cette référence fait foi pour ce que chaque route accepte et renvoie.
Ce qui ne figure pas dans cette référence
- Intégration initiale et jetons — comment enregistrer une organisation, créer un portefeuille et émettre un jeton d'accès personnel. Ces procédures sont décrites dans la documentation d'administration de la plateforme et dans la recette de démarrage des Recettes.
- Analyses destinées aux investisseurs — les packs de graphiques, l'export de la bande de prêts (loan tape) et la surface de téléchargement de la bande de prêts. Ils sont servis par des routes distinctes et ne sont pas couverts ici.
- Webhooks et livraison planifiée de la bande de prêts — non couverts ici.