Waafir
Esta página é uma tradução automática pendente de revisão humana. Pode conter erros.

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étodoCaminhoFinalidade
GET/api/v1/monitoring/loan/loans/{externalId}?portfolioId=<UUID>Ler um único empréstimo pelo ID do chamador.
GET/api/v1/monitoring/loan/countsLer 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âmetroPosiçãoObrigatórioRestrição
externalIdcaminhosim1 a 255 caracteres; aplique codificação percentual a qualquer caractere não seguro para URL.
portfolioIdquerysimUUID 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

StatusGatilho
200 OKEmpréstimo encontrado na sua organização.
400 Bad RequestportfolioId ausente ou malformado, ou externalId contém codificação percentual malformada.
404 Not FoundO 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âmetroPosiçãoObrigatórioRestrição
portfolioIdquerynãoUUID; restringe a um único portfólio. Omita para um consolidado de toda a organização.
datequerynãoYYYY-MM-DD; quando informado, a resposta inclui uma contagem onDate por entidade.
entityquerynãoUm 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

StatusGatilho
200 OKConsulta interpretada; contagens retornadas.
400 Bad RequestportfolioId, 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 é:

  1. Chame GET /counts?date=<today> com o seu portfólio. Compare a contagem onDate de cada entidade com o que você enviou hoje. Se as contagens baterem com o que você enviou, o seu lote chegou corretamente.
  2. 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.
  3. 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.