Conciliação
A interface de conciliação permite verificar o que chegou ao Waafir usando os seus próprios IDs do chamador, em vez dos UUIDs atribuídos pela plataforma. Ela é intencionalmente mínima — duas rotas —, mas é a espinha dorsal operacional de uma integração robusta: toda ingestão diária saudável termina com uma chamada de conciliação.
Por que conciliar pelo ID do chamador
Quando você envia um empréstimo com externalId: "L-001", o seu sistema já conhece a linha por esse nome. Perguntar à plataforma "você tem o L-001?" é o passo seguinte natural — e, como não é preciso traduzir antes para um UUID da plataforma, a sua lógica de conciliação pode usar os mesmos identificadores da sua contabilidade.
A plataforma garante que um externalId é único dentro de um portfólio entre as linhas ativas, e é isso que faz da busca por externalId uma leitura de linha única.
Rotas
| Método | Caminho | Finalidade |
|---|---|---|
GET | /api/v1/monitoring/loan/loans/{externalId}?portfolioId=<UUID> | Ler um único empréstimo pelo ID do chamador. |
GET | /api/v1/monitoring/loan/counts | Ler os totais de linhas por entidade, opcionalmente filtrados por portfólio, data ou entidade. |
GET /api/v1/monitoring/loan/loans/{externalId}
Lê um único empréstimo pelo externalId que você enviou. Exclui linhas canceladas (com exclusão lógica).
Requisição
| Parâmetro | Posição | Obrigatório | Restrição |
|---|---|---|---|
externalId | caminho | sim | 1 a 255 caracteres; aplique codificação percentual a qualquer caractere não seguro para URL. |
portfolioId | query | sim | UUID do portfólio ao qual o empréstimo pertence. |
O portfolioId é obrigatório porque o externalId não é único entre portfólios — ele só é único dentro de um portfólio.
Resposta — 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
}
}A resposta inclui o tomador do empréstimo com PII mascarada. Esta é a visão no escopo do investidor — o mesmo mascaramento aplicado ao endpoint GET de tomador. O mascaramento permite confirmar que "este empréstimo está vinculado ao tomador certo" sem expor PII ao sistema chamador. Administradores que precisam de PII sem máscara usam a interface de tomador por UUID com ?unmask=true e registro no log de auditoria.
Os campos monetários aparecem com a precisão total armazenada (quatro casas decimais para valores monetários; seis para interestRateApr); o seu cliente deve tratá-los como strings decimais opacas, em vez de convertê-los em floats.
Códigos de status
| Status | Gatilho |
|---|---|
200 OK | Empréstimo encontrado na sua organização. |
400 Bad Request | portfolioId ausente ou malformado, ou externalId contém codificação percentual malformada. |
404 Not Found | O empréstimo não existe como linha ativa no portfólio informado, ou o portfólio pertence a outra organização. |
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
Lê as contagens de linhas por entidade, opcionalmente filtradas por portfólio, por data ou para uma única entidade. Linhas com exclusão lógica são excluídas.
Requisição
| Parâmetro | Posição | Obrigatório | Restrição |
|---|---|---|---|
portfolioId | query | não | UUID; restringe a um único portfólio. Omita para um consolidado de toda a organização. |
date | query | não | YYYY-MM-DD; quando informado, a resposta inclui uma contagem onDate por entidade. |
entity | query | não | Um de borrowers, loans, scheduled_repayments, actual_payments, collateral, collateral_valuations (sem distinção de maiúsculas e minúsculas). Quando informado, só essa entidade é retornada. |
Resposta — 200 OK
Consolidado padrão, todas as seis entidades:
{
"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
}Com ?date=2026-05-22, cada entidade ganha uma contagem onDate das linhas criadas na data informada:
{
"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
}Com ?entity=loans, só a entrada loans aparece.
Códigos de status
| Status | Gatilho |
|---|---|
200 OK | Consulta interpretada; contagens retornadas. |
400 Bad Request | portfolioId, date ou entity malformado. |
Um portfolioId que não existe ou que pertence a outra organização não retorna 404; ele retorna 200 com zeros em tudo. Isso é intencional — a interface de contagens é uma leitura dos seus próprios dados, e um portfólio desconhecido é, na prática, indistinguível de um portfólio sem linhas.
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"Uma conciliação diária típica
Depois de concluir os envios do dia, o fluxo canônico de conciliação é:
- Chame
GET /counts?date=<today>com o seu portfólio. Compare a contagemonDatede cada entidade com o que você enviou hoje. Se as contagens baterem com o que você enviou, o seu lote chegou corretamente. - Para qualquer divergência, consulte as linhas específicas com
GET /loans/{externalId}. As consultas são baratas — uma única varredura de índice cada — e retornam o estado canônico da linha, incluindo o UUID atribuído pela plataforma, que você pode usar para investigar mais a fundo. - Para investigar no nível da linha, os endpoints GET de registro único e o endpoint de erros paginados das importações assíncronas são as interfaces que expõem o detalhe das falhas por linha.
A interface de conciliação é intencionalmente somente leitura e barata — é o batimento cardíaco da integração, não uma interface de carga. Chame-a uma ou duas vezes por dia por portfólio; não há limite de taxa específico para ela, mas não a consulte em um loop apertado.