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

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étodoCaminhoFinalidade
POST/api/v1/monitoring/loan/borrowersCriar um tomador
GET/api/v1/monitoring/loan/borrowers/{id}Ler um tomador por UUID, com mascaramento de PII
POST/api/v1/monitoring/loan/loansCriar um empréstimo
POST/api/v1/monitoring/loan/paymentsCriar um pagamento efetivo
GET/api/v1/monitoring/loan/payments/{id}Ler um pagamento efetivo por UUID
PATCH/api/v1/monitoring/loan/loans/{loanRef}/statusFazer a transição de um empréstimo para um novo status
POST/api/v1/monitoring/loan/payments/{id}/cancelExcluir 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:

CampoTipoObrigatórioRestrição
idstring UUIDsimIdentificador da plataforma fornecido pelo chamador.
portfolioIdstring UUIDsimO portfólio proprietário; deve existir na sua organização.
externalIdstringsim1 a 255 caracteres; único por (portfolio, externalId) entre linhas ativas.
namestring | nullnãoNome completo do tomador. Persistido sem alteração; leituras voltadas a investidores mascaram.
emailstring | nullnãoE-mail conforme a RFC 5322; persistido sem alteração; leituras voltadas a investidores mascaram.
phonestring | nullnãoTelefone em formato livre; persistido sem alteração; leituras voltadas a investidores mascaram.
nationalIdLast4string | nullnãoExatamente quatro dígitos; os dígitos iniciais nunca são retornados.
countryCodestring | nullnãoCódigo ISO-3166 de duas letras (maiúsculas).
dobstring de data | nullnãoYYYY-MM-DD.
genderenum | nullnãomale | female | non_binary | other | undisclosed (sem distinção de maiúsculas e minúsculas).
incomeBandstring | nullnãoFormato livre.
employmentStatusstring | nullnãoFormato livre.
metadataobject | nullnãoRepasse 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
}
StatusEnvelopeGatilho
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 RequestfieldErrorsFalha 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âmetroPosiçãoObrigatórioRestrição
idcaminhosimO UUID da plataforma do tomador.
unmaskquerynãotrue 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": {}
}
StatusGatilho
200 OKA 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 Requestid não é um UUID bem formado.
404 Not FoundA 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

CampoTipoObrigatórioRestrição
idstring UUIDsimIdentificador da plataforma fornecido pelo chamador.
portfolioIdstring UUIDsimO portfólio proprietário.
borrowerIdstring UUIDsimUm tomador ativo no mesmo portfólio.
externalIdstringsim1 a 255 caracteres; único por portfólio entre linhas ativas.
predecessorLoanIdstring UUID | nullnãoDefinido em uma reestruturação; aponta para o empréstimo que está sendo substituído.
principalAmountstring decimalsimAté quatro casas decimais.
currencyCodestringsimISO-4217 de três letras; sem distinção de maiúsculas e minúsculas.
interestRateAprstring decimalsimAté seis casas decimais; deve ser >= 0.
disbursementDatestring de datasimYYYY-MM-DD.
termMonthsintegersimDeve ser > 0.
repaymentFrequencyenumsimmonthly | weekly | biweekly | quarterly | bullet (sem distinção de maiúsculas e minúsculas).
productTypestring | nullnãoFormato livre, por exemplo "Term loan", "Overdraft".
statusenumsimpending | active | paid_off | restructured | written_off | defaulted (sem distinção de maiúsculas e minúsculas).
metadataobject | nullnãoRepasse literal.

Respostas

201 Created (ou 200 OK em repetição idempotente) com { id, externalId, bronzeSubmissionId, reused }.

StatusEnvelopeGatilho
200 OK{ ..., reused: true }Repetição idempotente.
201 Created{ ..., reused: false }Novo empréstimo inserido.
400 Bad RequestfieldErrorsFalha 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

CampoTipoObrigatórioRestrição
idstring UUIDsimIdentificador da plataforma fornecido pelo chamador.
portfolioIdstring UUIDsimO portfólio proprietário.
loanIdstring UUIDsimUm empréstimo ativo no mesmo portfólio.
externalIdstringsim1 a 255 caracteres; único por portfólio entre linhas ativas.
paymentDatestring de datasimYYYY-MM-DD.
amountstring decimalsimO valor total do pagamento recebido.
currencyCodestringsimISO-4217.
principalPaidstring decimalnãoPadrão "0".
interestPaidstring decimalnãoPadrão "0".
feesPaidstring decimalnãoPadrão "0".
writeOffAmountstring decimalnãoPadrão "0". Veja a regra de perdão abaixo.
paymentNotesstring | nullnãoDeve ser "Forgiven" (sem distinção de maiúsculas e minúsculas) quando writeOffAmount > 0.
paymentMethodenum | nullnãocash | bank_transfer | card | mobile_money | check | other.
metadataobject | nullnãoRepasse 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 }.

StatusEnvelopeGatilho
200 OK{ ..., reused: true }Repetição idempotente.
201 Created{ ..., reused: false }Novo pagamento inserido.
400 Bad RequestfieldErrorsFalha 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âmetroPosiçãoObrigatórioRestrição
idcaminhosimO 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:

CampoTipoObrigatórioRestrição
statusenumsimUm de active | paid_off | defaulted | written_off | restructured (sem distinção de maiúsculas e minúsculas).
effectiveDatestring de datasimYYYY-MM-DD.
reasonstring | nullnão1 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.

DeDestinos permitidos
pendingactive
activepaid_off, defaulted, written_off, restructured
paid_off(terminal)
defaultedwritten_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
}
StatusEnvelopeGatilho
200 OK{ id, externalId, status, bronzeSubmissionId, reused }Transição aplicada (ou repetição idempotente com reused: true).
400 Bad RequestfieldErrorsFalha 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/json

Corpo (opcional):

CampoTipoObrigatórioRestrição
reasonstring | nullnão1 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.

StatusEnvelopeGatilho
200 OK{ id, deletedAt, bronzeSubmissionId, reused, alreadyCancelled }Primeiro cancelamento ou cancelamentos seguintes.
400 Bad RequestfieldErrorsid 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 é:

  1. POST /api/v1/monitoring/loan/payments/{id}/cancel na linha original.
  2. POST /api/v1/monitoring/loan/payments para uma nova linha com os campos corrigidos. Você pode reutilizar o mesmo externalId; deve informar um id diferente.

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.