Pular para o conteúdo principal

Como simular um empréstimo via API?

Para precificar um empréstimo antes de originar, use o endpoint POST /api/v1/loan/simulation. Requer o escopo LOAN_SIMULATION_POST.

A simulação não cria nada para o tomador. Ela fica guardada até a expirationDate e pode ser repetida à vontade.

Campos do corpo​

CampoTipoObrigatórioDescrição
taxIDstringSimCPF ou CNPJ do tomador, com ou sem máscara.
amountintegerSimValor do empréstimo, em centavos, dentro dos limites do fundo que financia (por padrão de 10000 a 250000).
installmentNumberintegerSimNúmero de parcelas, de 1 ao máximo do fundo (por padrão 8).
periodstringNãoWEEKLY ou MONTHLY. Padrão MONTHLY.
correlationIDstringNãoSeu identificador. Repetir devolve a simulação guardada.

Exemplos em código​

curl 'https://api.woovi.com/api/v1/loan/simulation' -X POST \
-H "Content-Type: application/json" \
-H "Authorization: {SEU_APP_ID}" \
-d '{
"taxID": "12345678909",
"amount": 150000,
"installmentNumber": 4,
"period": "MONTHLY",
"correlationID": "erp-sim-42"
}'

Exemplo de resposta​

{
"simulation": {
"simulationId": "6abeadd43f02bc8c8675c0ad",
"correlationID": "erp-sim-42",
"status": "APPROVED",
"refusalReason": null,
"expiresAt": "2026-10-02T15:00:00.000Z",
"expirationDate": "2026-10-02",
"amount": 150000,
"installmentNumber": 4,
"period": "MONTHLY",
"monthlyInterestRate": 0.1,
"totalAmount": 189000,
"installmentPlan": [
{ "seq": 1, "dueDate": "2026-11-01", "amount": 47250 },
{ "seq": 2, "dueDate": "2026-12-01", "amount": 47250 },
{ "seq": 3, "dueDate": "2027-01-01", "amount": 47250 },
{ "seq": 4, "dueDate": "2027-02-01", "amount": 47250 }
]
}
}
nota

Os valores do exemplo são ilustrativos. A tabela Price do serviço é a fonte do cálculo, e a taxa mensal vigente aparece em monthlyInterestRate.

Recusas​

Uma simulação recusada não é erro HTTP: a resposta é 200 com status: "REFUSED", simulationId: null e o motivo em refusalReason.

{
"simulation": {
"simulationId": null,
"correlationID": "erp-sim-42",
"status": "REFUSED",
"refusalReason": "ALREADY_ACTIVE"
}
}
refusalReasonSignificado
ALREADY_ACTIVEO tomador já tem um empréstimo em aberto.
TAXID_TYPE_NOT_ELIGIBLEO fundo não empresta para este tipo de documento (CPF ou CNPJ).
CNPJ_REQUIREDO fundo só empresta para CNPJ.
TICKET_CAPO valor está acima do máximo que o fundo empresta num empréstimo só.
PERSON_CAPO tomador chegou ao máximo que o fundo empresta para uma mesma pessoa.
PERSON_LIMITO valor está acima do que o tomador pode pegar agora.
NOT_ALLOWEDO tomador não está elegível para crédito.
SCREENING_REFUSEDA análise do documento recusou. Um código só, de propósito: a API não diz se foi cadastro ou marcador de fraude.

Os erros HTTP são:

StatuserrorSignificado
400INVALID_REQUESTCorpo inválido: valor ou número de parcelas fora dos limites do fundo, period desconhecido ou documento malformado. message diz qual campo.
422FUND_CLOSEDNenhum fundo ativo atende a sua empresa.

O saldo do fundo não é checado na simulação, e sim na originação: uma simulação aprovada ainda pode ser recusada com NO_FUNDS ao contratar.