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

Rapprochement

La surface de rapprochement vous permet de vérifier ce qui est arrivé dans Waafir à l'aide de vos propres identifiants appelant plutôt que des UUID attribués par la plateforme. Elle est volontairement minimale — deux routes — mais elle constitue l'épine dorsale opérationnelle d'une intégration robuste : toute ingestion quotidienne saine se termine par un appel de rapprochement.

Pourquoi rapprocher par identifiant appelant

Lorsque vous soumettez un prêt avec externalId: "L-001", votre système connaît déjà la ligne sous ce nom. Demander à la plateforme « avez-vous L-001 ? » est la suite naturelle — et ne pas avoir à le convertir d'abord en UUID de plateforme permet à votre logique de rapprochement de s'appuyer sur les mêmes identifiants que votre comptabilité.

La plateforme garantit qu'un externalId est unique au sein d'un portefeuille pour les lignes actives, ce qui fait de la recherche par externalId une lecture d'une seule ligne.

Routes

MéthodeCheminObjet
GET/api/v1/monitoring/loan/loans/{externalId}?portfolioId=<UUID>Lire un prêt par identifiant appelant.
GET/api/v1/monitoring/loan/countsLire le total de lignes par entité, éventuellement restreint par portefeuille, date ou entité.

GET /api/v1/monitoring/loan/loans/{externalId}

Lit un prêt à partir de l'externalId que vous avez soumis. Exclut les lignes annulées (supprimées logiquement).

Requête

ParamètrePositionObligatoireContrainte
externalIdcheminoui1 à 255 caractères ; encodez en pourcentage tout caractère non sûr dans une URL.
portfolioIdrequêteouiUUID du portefeuille propriétaire du prêt.

Le portfolioId est obligatoire, car externalId n'est pas unique d'un portefeuille à l'autre — il n'est unique qu'au sein d'un portefeuille.

Réponse — 200 OK

{
  "loan": {
    "id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
    "borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
    "externalId": "L-001",
    "predecessorLoanId": null,
    "principalAmount": "10000.0000",
    "currencyCode": "USD",
    "interestRateApr": "0.180000",
    "disbursementDate": "2026-01-15",
    "termMonths": 12,
    "repaymentFrequency": "monthly",
    "productType": "Term loan",
    "status": "active",
    "metadata": {},
    "createdAt": "2026-01-15T08:00:00Z",
    "updatedAt": "2026-01-15T08:00:00Z"
  },
  "borrower": {
    "id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
    "externalId": "B-001",
    "name": "J***",
    "email": "j***@example.com",
    "phone": "***-***-1234",
    "nationalIdLast4": "1234",
    "countryCode": "KE",
    "dob": "1985-03-20",
    "gender": "female",
    "incomeBand": null,
    "employmentStatus": null
  }
}

La réponse intègre l'emprunteur du prêt avec les PII masquées. Il s'agit de la vue de périmètre investisseur — le même masquage que celui qui s'applique à l'endpoint GET de l'emprunteur. Le masquage vous permet de confirmer que « ce prêt est bien rattaché au bon emprunteur » sans exposer de PII au système appelant. Les administrateurs qui ont besoin des PII brutes passent par la surface de l'emprunteur par UUID avec ?unmask=true et consignation dans le journal d'audit.

Les champs monétaires apparaissent avec toute la précision stockée (quatre décimales pour les montants ; six pour interestRateApr) ; votre client doit les traiter comme des chaînes décimales opaques plutôt que de les convertir en flottants.

Codes de statut

StatutDéclencheur
200 OKPrêt trouvé dans votre organisation.
400 Bad RequestportfolioId absent ou mal formé, ou externalId contenant un encodage en pourcentage mal formé.
404 Not FoundLe prêt n'existe pas à l'état actif dans le portefeuille fourni, ou le portefeuille appartient à une autre organisation.

cURL

curl https://app.waafir.io/api/v1/monitoring/loan/loans/L-001?portfolioId=ddf63d12-1234-5678-9abc-def012345678 \
  -H "Authorization: Bearer $WAAFIR_PAT"

GET /api/v1/monitoring/loan/counts

Lit le nombre de lignes par entité, éventuellement restreint par portefeuille, par date ou à une seule entité. Les lignes supprimées logiquement sont exclues.

Requête

ParamètrePositionObligatoireContrainte
portfolioIdrequêtenonUUID ; restreint à un seul portefeuille. Omettez-le pour un cumul à l'échelle de l'organisation.
daterequêtenonYYYY-MM-DD ; lorsqu'il est fourni, la réponse inclut un compteur onDate par entité.
entityrequêtenonL'une des valeurs borrowers, loans, scheduled_repayments, actual_payments, collateral, collateral_valuations (insensible à la casse). Lorsqu'il est fourni, seule cette entité est renvoyée.

Réponse — 200 OK

Cumul par défaut, les six entités :

{
  "counts": {
    "borrowers": { "total": 1200 },
    "loans": { "total": 3450 },
    "scheduled_repayments": { "total": 41400 },
    "actual_payments": { "total": 32118 },
    "collateral": { "total": 600 },
    "collateral_valuations": { "total": 1840 }
  },
  "date": null,
  "portfolioId": null
}

Avec ?date=2026-05-22, chaque entité reçoit un compteur onDate des lignes créées à la date fournie :

{
  "counts": {
    "borrowers": { "total": 1200, "onDate": 0 },
    "loans": { "total": 3450, "onDate": 12 },
    "scheduled_repayments": { "total": 41400, "onDate": 144 },
    "actual_payments": { "total": 32118, "onDate": 1207 },
    "collateral": { "total": 600, "onDate": 0 },
    "collateral_valuations": { "total": 1840, "onDate": 0 }
  },
  "date": "2026-05-22",
  "portfolioId": null
}

Avec ?entity=loans, seule l'entrée loans apparaît.

Codes de statut

StatutDéclencheur
200 OKRequête analysée ; compteurs renvoyés.
400 Bad RequestportfolioId, date ou entity mal formé.

Un portfolioId qui n'existe pas ou qui appartient à une autre organisation ne renvoie pas 404 ; il renvoie 200 avec des zéros partout. Ce comportement est voulu — la surface des compteurs est une lecture de vos propres données, et un portefeuille inconnu est fonctionnellement indiscernable d'un portefeuille sans aucune ligne.

cURL

# Full daily reconciliation for one portfolio:
curl "https://app.waafir.io/api/v1/monitoring/loan/counts?portfolioId=ddf63d12-1234-5678-9abc-def012345678&date=2026-05-22" \
  -H "Authorization: Bearer $WAAFIR_PAT"

Un rapprochement quotidien type

Une fois les soumissions du jour terminées, le flux de rapprochement canonique est le suivant :

  1. Appelez GET /counts?date=<today> avec votre portefeuille. Comparez le compteur onDate de chaque entité à ce que vous avez soumis aujourd'hui. Si les compteurs correspondent à vos envois, votre lot est bien arrivé.
  2. Pour tout écart, recherchez les lignes concernées avec GET /loans/{externalId}. Ces recherches sont peu coûteuses — un seul parcours d'index chacune — et elles renvoient l'état canonique de la ligne, y compris l'UUID attribué par la plateforme, que vous pouvez ensuite utiliser pour approfondir l'enquête.
  3. Pour une investigation au niveau de la ligne, les endpoints GET unitaires et l'endpoint d'erreurs paginées des imports asynchrones sont les surfaces qui exposent le détail des échecs par ligne.

La surface de rapprochement est volontairement en lecture seule et peu coûteuse — c'est le pouls de l'intégration, pas une surface de chargement. Appelez-la une ou deux fois par jour et par portefeuille ; elle n'a pas de limite de débit qui lui soit propre, mais merci de ne pas l'interroger dans une boucle serrée.