CRUD de registro único
A interface CRUD de registro único é o caminho de baixo volume: uma chamada HTTP por linha. Use-a para gravações operacionais — um único empréstimo novo, um único pagamento que não veio no lote diário, uma transição de status — e para leituras de volta pelo UUID da plataforma. Para lotes de fim de dia, use NDJSON em lote; para cargas históricas, use importações assíncronas.
Toda rota desta página respeita o contrato documentado na visão geral: autenticação por bearer token, as garantias de integração, o envelope fieldErrors, a semântica de cancelamento e o registro de cada envio. A documentação rota a rota abaixo cita apenas os formatos específicos de cada rota; para o comportamento transversal, consulte a visão geral.
Rotas em resumo
| Método | Caminho | Finalidade |
|---|---|---|
POST | /api/v1/monitoring/loan/borrowers | Criar um tomador |
GET | /api/v1/monitoring/loan/borrowers/{id} | Ler um tomador por UUID, com mascaramento de PII |
POST | /api/v1/monitoring/loan/loans | Criar um empréstimo |
POST | /api/v1/monitoring/loan/payments | Criar um pagamento efetivo |
GET | /api/v1/monitoring/loan/payments/{id} | Ler um pagamento efetivo por UUID |
PATCH | /api/v1/monitoring/loan/loans/{loanRef}/status | Fazer a transição de um empréstimo para um novo status |
POST | /api/v1/monitoring/loan/payments/{id}/cancel | Excluir logicamente (soft delete) um pagamento |
Todas as rotas de escrita aceitam o cabeçalho Idempotency-Key e o parâmetro de query ?dryRun=true, e retornam o envelope estruturado fieldErrors em caso de falha de validação.
POST /api/v1/monitoring/loan/borrowers
Cria um tomador no portfólio identificado por portfolioId.
Requisição
POST /api/v1/monitoring/loan/borrowers HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>Corpo:
| Campo | Tipo | Obrigatório | Restrição |
|---|---|---|---|
id | string UUID | sim | Identificador da plataforma fornecido pelo chamador. |
portfolioId | string UUID | sim | O portfólio proprietário; deve existir na sua organização. |
externalId | string | sim | 1 a 255 caracteres; único por (portfolio, externalId) entre linhas ativas. |
name | string | null | não | Nome completo do tomador. Persistido sem alteração; leituras voltadas a investidores mascaram. |
email | string | null | não | E-mail conforme a RFC 5322; persistido sem alteração; leituras voltadas a investidores mascaram. |
phone | string | null | não | Telefone em formato livre; persistido sem alteração; leituras voltadas a investidores mascaram. |
nationalIdLast4 | string | null | não | Exatamente quatro dígitos; os dígitos iniciais nunca são retornados. |
countryCode | string | null | não | Código ISO-3166 de duas letras (maiúsculas). |
dob | string de data | null | não | YYYY-MM-DD. |
gender | enum | null | não | male | female | non_binary | other | undisclosed (sem distinção de maiúsculas e minúsculas). |
incomeBand | string | null | não | Formato livre. |
employmentStatus | string | null | não | Formato livre. |
metadata | object | null | não | Repasse literal. |
Respostas
201 Created em uma gravação nova, 200 OK em uma repetição idempotente:
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "BORROWER-001",
"bronzeSubmissionId": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
"reused": false
}| Status | Envelope | Gatilho |
|---|---|---|
200 OK | { id, externalId, bronzeSubmissionId, reused: true } | O Idempotency-Key corresponde a uma requisição anterior; nenhuma nova gravação. |
201 Created | { id, externalId, bronzeSubmissionId, reused: false } | Nova linha inserida. |
400 Bad Request | fieldErrors | Falha de validação em qualquer campo do corpo. |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | portfolioId não existe ou pertence a outra organização. |
409 Conflict | { error, code: "ID_CONFLICT", fieldErrors: [...] } | Já existe um tomador ativo com o mesmo id. |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/borrowers \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e" \
-d '{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"gender": "female",
"countryCode": "KE"
}'GET /api/v1/monitoring/loan/borrowers/{id}
Lê um tomador pelo UUID da plataforma. Os campos de PII são mascarados por padrão; administradores podem solicitar PII sem máscara com ?unmask=true, o que grava uma entrada no log de auditoria.
Requisição
| Parâmetro | Posição | Obrigatório | Restrição |
|---|---|---|---|
id | caminho | sim | O UUID da plataforma do tomador. |
unmask | query | não | true retorna PII sem máscara; somente administradores. O padrão mascara. |
Respostas
200 OK com o registro mascarado do tomador:
{
"id": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"externalId": "BORROWER-001",
"name": "J***",
"email": "j***@example.com",
"phone": "***-***-1234",
"nationalIdLast4": "1234",
"countryCode": "KE",
"dob": "1985-03-20",
"gender": "female",
"incomeBand": null,
"employmentStatus": null,
"metadata": {}
}| Status | Gatilho |
|---|---|
200 OK | A linha existe na sua organização. A PII vem sem máscara se o chamador for administrador E houver ?unmask=true; caso contrário, vem mascarada. |
400 Bad Request | id não é um UUID bem formado. |
404 Not Found | A linha não existe, está cancelada ou pertence a outra organização. |
O mascaramento de PII se aplica a name, email, phone e nationalIdLast4. O campo nationalIdLast4 já armazena apenas os quatro últimos dígitos no momento da gravação; ainda assim, o mascaramento na leitura os oculta de leituras feitas por quem não é administrador.
Um chamador que não é administrador e envia ?unmask=true não recebe 403 — a resposta continua sendo 200 com o formato mascarado, e é gravada uma entrada no log de auditoria registrando a tentativa negada de remover a máscara. A plataforma não expõe a verificação de papel como erro porque o formato mascarado é o padrão seguro; é a trilha de auditoria que torna a tentativa visível para a equipe de segurança.
Um administrador que envia ?unmask=true recebe a PII sem máscara, e a requisição grava uma entrada separada no log de auditoria registrando a remoção da máscara. A resposta inclui Cache-Control: private, no-store para impedir que intermediários armazenem em cache o payload com PII sem máscara.
POST /api/v1/monitoring/loan/loans
Cria um empréstimo para um tomador existente no mesmo portfólio.
Requisição
| Campo | Tipo | Obrigatório | Restrição |
|---|---|---|---|
id | string UUID | sim | Identificador da plataforma fornecido pelo chamador. |
portfolioId | string UUID | sim | O portfólio proprietário. |
borrowerId | string UUID | sim | Um tomador ativo no mesmo portfólio. |
externalId | string | sim | 1 a 255 caracteres; único por portfólio entre linhas ativas. |
predecessorLoanId | string UUID | null | não | Definido em uma reestruturação; aponta para o empréstimo que está sendo substituído. |
principalAmount | string decimal | sim | Até quatro casas decimais. |
currencyCode | string | sim | ISO-4217 de três letras; sem distinção de maiúsculas e minúsculas. |
interestRateApr | string decimal | sim | Até seis casas decimais; deve ser >= 0. |
disbursementDate | string de data | sim | YYYY-MM-DD. |
termMonths | integer | sim | Deve ser > 0. |
repaymentFrequency | enum | sim | monthly | weekly | biweekly | quarterly | bullet (sem distinção de maiúsculas e minúsculas). |
productType | string | null | não | Formato livre, por exemplo "Term loan", "Overdraft". |
status | enum | sim | pending | active | paid_off | restructured | written_off | defaulted (sem distinção de maiúsculas e minúsculas). |
metadata | object | null | não | Repasse literal. |
Respostas
201 Created (ou 200 OK em repetição idempotente) com { id, externalId, bronzeSubmissionId, reused }.
| Status | Envelope | Gatilho |
|---|---|---|
200 OK | { ..., reused: true } | Repetição idempotente. |
201 Created | { ..., reused: false } | Novo empréstimo inserido. |
400 Bad Request | fieldErrors | Falha de validação (por exemplo, interestRateApr negativo, currencyCode malformado). |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | Portfólio inexistente ou de outra organização. |
409 Conflict | { error, code: "ID_CONFLICT" } | Já existe um empréstimo ativo com o mesmo id. |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "borrowerId", ... }] } | borrowerId não corresponde a um tomador ativo no mesmo portfólio. |
cURL
curl -X POST https://app.waafir.io/api/v1/monitoring/loan/loans \
-H "Authorization: Bearer $WAAFIR_PAT" \
-H "Content-Type: application/json" \
-d '{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"portfolioId": "ddf63d12-1234-5678-9abc-def012345678",
"borrowerId": "5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e",
"externalId": "LOAN-001",
"principalAmount": "10000.00",
"currencyCode": "USD",
"interestRateApr": "0.18",
"disbursementDate": "2026-01-15",
"termMonths": 12,
"repaymentFrequency": "monthly",
"status": "active"
}'POST /api/v1/monitoring/loan/payments
Registra um pagamento efetivo de um empréstimo existente. Use esta rota para pagamentos recebidos, pagamentos parciais e baixas. Reestruturações são modeladas como um novo empréstimo com predecessorLoanId definido, não como um pagamento.
Requisição
| Campo | Tipo | Obrigatório | Restrição |
|---|---|---|---|
id | string UUID | sim | Identificador da plataforma fornecido pelo chamador. |
portfolioId | string UUID | sim | O portfólio proprietário. |
loanId | string UUID | sim | Um empréstimo ativo no mesmo portfólio. |
externalId | string | sim | 1 a 255 caracteres; único por portfólio entre linhas ativas. |
paymentDate | string de data | sim | YYYY-MM-DD. |
amount | string decimal | sim | O valor total do pagamento recebido. |
currencyCode | string | sim | ISO-4217. |
principalPaid | string decimal | não | Padrão "0". |
interestPaid | string decimal | não | Padrão "0". |
feesPaid | string decimal | não | Padrão "0". |
writeOffAmount | string decimal | não | Padrão "0". Veja a regra de perdão abaixo. |
paymentNotes | string | null | não | Deve ser "Forgiven" (sem distinção de maiúsculas e minúsculas) quando writeOffAmount > 0. |
paymentMethod | enum | null | não | cash | bank_transfer | card | mobile_money | check | other. |
metadata | object | null | não | Repasse literal. |
Regra de perdão. Se writeOffAmount > 0, paymentNotes deve ser igual a "Forgiven", sem distinção de maiúsculas e minúsculas. A plataforma rejeita a requisição já na fronteira da API, de modo que um pagamento inválido é recusado antes de qualquer registro.
Respostas
201 Created (ou 200 OK em repetição idempotente) com { id, externalId, bronzeSubmissionId, reused }.
| Status | Envelope | Gatilho |
|---|---|---|
200 OK | { ..., reused: true } | Repetição idempotente. |
201 Created | { ..., reused: false } | Novo pagamento inserido. |
400 Bad Request | fieldErrors | Falha de validação (valores malformados, valor de enum não reconhecido, campo obrigatório ausente). |
404 Not Found | { error, code: "PORTFOLIO_NOT_FOUND" } | Portfólio inexistente ou de outra organização. |
409 Conflict | { error, code: "ID_CONFLICT" } | Já existe um pagamento ativo com o mesmo id. |
422 Unprocessable Entity | { error, code: "REFERENCED_ENTITY_NOT_FOUND", fieldErrors: [{ path: "loanId", ... }] } | loanId não corresponde a um empréstimo ativo no mesmo portfólio. |
400 Bad Request | { error, code: "CHECK_VIOLATION", fieldErrors: [...] } | A regra de perdão foi violada no momento em que o pagamento foi armazenado (raro; a validação rejeita o mesmo formato antes). |
GET /api/v1/monitoring/loan/payments/{id}
Lê um pagamento efetivo pelo UUID da plataforma, incluindo linhas canceladas (com exclusão lógica). Use para verificar uma gravação ou inspecionar um registro cancelado.
Requisição
| Parâmetro | Posição | Obrigatório | Restrição |
|---|---|---|---|
id | caminho | sim | O UUID da plataforma do pagamento. |
Respostas
200 OK com o registro completo do pagamento. Linhas canceladas aparecem com deletedAt preenchido; linhas ativas têm deletedAt: null. 404 Not Found para UUID de outra organização ou desconhecido. 400 Bad Request se id não for um UUID bem formado.
PATCH /api/v1/monitoring/loan/loans/{loanRef}/status
Faz a transição de um empréstimo para um novo status. O segmento de caminho {loanRef} aceita ou o UUID da plataforma do empréstimo ou o seu externalId. Ao passar um externalId, você também deve informar ?portfolioId=<UUID>, porque IDs externos não são únicos entre portfólios.
Requisição
PATCH /api/v1/monitoring/loan/loans/LOAN-001/status?portfolioId=ddf63d12-1234-5678-9abc-def012345678 HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/json
Idempotency-Key: <opaque-key>Corpo:
| Campo | Tipo | Obrigatório | Restrição |
|---|---|---|---|
status | enum | sim | Um de active | paid_off | defaulted | written_off | restructured (sem distinção de maiúsculas e minúsculas). |
effectiveDate | string de data | sim | YYYY-MM-DD. |
reason | string | null | não | 1 a 500 caracteres; registrado no log de auditoria. |
Matriz de transição de status
A plataforma aplica uma matriz de transição; uma transição inválida retorna 422 INVALID_STATUS_TRANSITION com fieldErrors indicando os status de origem e de destino.
| De | Destinos permitidos |
|---|---|
pending | active |
active | paid_off, defaulted, written_off, restructured |
paid_off | (terminal) |
defaulted | written_off, restructured |
written_off | (terminal) |
restructured | (terminal) |
Ao fazer a transição de um empréstimo para restructured, o passo seguinte natural é um POST /loans para o empréstimo substituto, com predecessorLoanId definido. As duas gravações intencionalmente não são atômicas — se o POST do substituto falhar, o antecessor permanece em restructured e a interface de conciliação mostrará a divergência na próxima consulta.
Respostas
200 OK em caso de sucesso:
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"externalId": "LOAN-001",
"status": "restructured",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false
}| Status | Envelope | Gatilho |
|---|---|---|
200 OK | { id, externalId, status, bronzeSubmissionId, reused } | Transição aplicada (ou repetição idempotente com reused: true). |
400 Bad Request | fieldErrors | Falha de validação do corpo, portfolioId ausente ao buscar por externalId, valor de enum malformado. |
404 Not Found | { error, code: "NOT_FOUND" } | Empréstimo não encontrado pelo UUID, ou (portfolioId, externalId) não é resolvido. |
422 Unprocessable Entity | { error, code: "INVALID_STATUS_TRANSITION", fieldErrors: [...] } | O par origem/destino não está na matriz de transição; fieldErrors[].message lista os destinos permitidos. |
409 Conflict | { error, code: "IDEMPOTENCY_CONFLICT" } | A Idempotency-Key já foi usada para uma transição diferente. A gravação anterior permanece; envie a nova transição com uma nova chave. |
O effectiveDate que você informa é registrado com o envio e no log de auditoria; ele não aparece no corpo da resposta. metadata intencionalmente não é aceito nesta rota — a própria transição é o evento de auditoria, e o campo opcional reason traz o contexto legível.
POST /api/v1/monitoring/loan/payments/{id}/cancel
Exclui logicamente (soft delete) um pagamento registrado anteriormente. O endpoint de cancelamento é a única interface de reversão do domínio de empréstimos — não existe PATCH /loans/{id}/adjust e não existirá.
Requisição
POST /api/v1/monitoring/loan/payments/7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f/cancel HTTP/1.1
Authorization: Bearer <PAT>
Content-Type: application/jsonCorpo (opcional):
| Campo | Tipo | Obrigatório | Restrição |
|---|---|---|---|
reason | string | null | não | 1 a 500 caracteres; registrado no evento de auditoria do cancelamento. |
Um corpo vazio é aceito; você pode omitir totalmente o cabeçalho Content-Type.
Respostas
200 OK em caso de sucesso:
{
"id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
"deletedAt": "2026-03-15T11:02:33Z",
"bronzeSubmissionId": "9d8c7b6a-5432-1098-7654-321098765432",
"reused": false,
"alreadyCancelled": false
}Em uma segunda chamada para o mesmo pagamento, o formato da resposta é idêntico, exceto que alreadyCancelled: true e deletedAt é o timestamp original do cancelamento. A flag reused acompanha o estado de idempotência, enquanto alreadyCancelled indica se a linha foi alterada por esta chamada.
| Status | Envelope | Gatilho |
|---|---|---|
200 OK | { id, deletedAt, bronzeSubmissionId, reused, alreadyCancelled } | Primeiro cancelamento ou cancelamentos seguintes. |
400 Bad Request | fieldErrors | id não é um UUID bem formado, ou reason excede 500 caracteres. |
404 Not Found | { error, code: "NOT_FOUND" } | O pagamento não existe ou pertence a outra organização. |
Um registro de envio é gravado a cada cancelamento — inclusive no segundo — para que a auditoria fique completa. A linha só é alterada na primeira chamada.
Exclusão lógica e reutilização de externalId
Um pagamento cancelado deixa o seu externalId disponível para reutilização em uma gravação futura, porque a restrição de unicidade se aplica apenas a linhas ativas. Para corrigir um envio errado, o caminho canônico é:
POST /api/v1/monitoring/loan/payments/{id}/cancelna linha original.POST /api/v1/monitoring/loan/paymentspara uma nova linha com os campos corrigidos. Você pode reutilizar o mesmoexternalId; deve informar umiddiferente.
Isso é intencional: cancelamentos não são destrutivos (a linha original é preservada para auditoria), e a reutilização do externalId mantém denso o espaço operacional de IDs do chamador para fins de conciliação.