Pular para o conteúdo principal

Como originar um empréstimo via API?

Para contratar um empréstimo para o tomador, use o endpoint POST /api/v1/loan/operation. Requer o escopo LOAN_OPERATION_POST.

A chamada contrata uma simulação aprovada, registra a operação e instrui o Pix que paga o empréstimo. O valor, as parcelas e o período são os da simulação, nunca do corpo. A empresa que origina é a do seu app_id.

Campos do corpo​

CampoTipoObrigatórioDescrição
simulationIdstringSimO simulationId de uma simulação APPROVED da sua empresa, ainda dentro do expiresAt.
correlationIDstringSimSeu identificador, único por empresa.
pixKeystringNãoChave Pix que recebe o dinheiro: CPF/CNPJ só com dígitos, +telefone, e-mail ou chave aleatória. Omitida, o Pix sai para o próprio documento do tomador como chave Pix.

Qualquer outro campo no corpo (como taxID ou amount) é recusado com 400.

Para onde vai o dinheiro​

A pixKey precisa ser do tomador no DICT. Se o fundo foi aberto para pagar a empresa que origina, ela também pode ser uma chave Woovi da sua empresa. Fora isso, a originação é recusada com PIX_KEY_NOT_BORROWER e nenhum dinheiro sai.

Idempotência​

O correlationID é a chave de idempotência. Se a sua aplicação repetir a chamada com o mesmo correlationID, a API devolve a mesma operação com 200 em vez de originar um segundo empréstimo, mesmo que o corpo seja diferente. Uma operação CANCELLED (o Pix de desembolso falhou) também é devolvida: a chave fica consumida e um novo empréstimo precisa de outro correlationID. Em caso de 503, repita com o mesmo correlationID.

Recusas​

Além da validação do corpo (400), toda recusa vem com um error para a sua integração decidir e um message explicando o motivo:

{
"error": "NO_FUNDS",
"message": "the fund cannot pay this loan right now; the simulation stays open until it expires"
}
StatuserrorSignificado
404SIMULATION_NOT_FOUNDO simulationId não existe para a sua empresa.
422SIMULATION_EXPIREDA simulação expirou. Simule de novo.
422SIMULATION_CONSUMEDA simulação já foi contratada ou recusada.
422PIX_KEY_NOT_BORROWERA pixKey não é do tomador nem uma chave Woovi permitida da sua empresa. Veja Para onde vai o dinheiro.
422PIX_KEY_NOT_FOUNDA pixKey não existe no DICT.
422PIX_KEY_UNVERIFIABLENão foi possível confirmar o dono da pixKey no DICT agora. Tente de novo.
422NO_FUNDSO fundo não tem saldo para pagar este empréstimo agora. A simulação continua aberta até expirar.
422UTILIZATION_CAPO fundo chegou ao limite de empréstimos por agora. A simulação continua aberta até expirar.
422COMPANY_CAPA sua empresa chegou à fatia dela no fundo. A simulação continua aberta até expirar.
422ALREADY_ACTIVEO tomador já tem um empréstimo em aberto.
422FUND_INACTIVEO fundo da simulação foi fechado.
422FUND_CLOSEDNenhum fundo ativo atende a sua empresa.

Nas recusas de NO_FUNDS, UTILIZATION_CAP e COMPANY_CAP nenhum dinheiro sai: repita a mesma chamada, com o mesmo simulationId e correlationID, enquanto a simulação não expirar.

Exemplos em código​

curl 'https://api.woovi.com/api/v1/loan/operation' -X POST \
-H "Content-Type: application/json" \
-H "Authorization: {SEU_APP_ID}" \
-d '{
"simulationId": "6abeadd43f02bc8c8675c0ad",
"pixKey": "+5511999999999",
"correlationID": "erp-loan-42"
}'

Exemplo de resposta (201)​

{
"operation": {
"operationId": "6abd072eccca077d96ad9e20",
"correlationID": "erp-loan-42",
"taxID": { "taxID": "12345678909", "type": "BR:CPF" },
"status": "ACTIVE",
"principal": 150000,
"totalDue": 189000,
"outstanding": 189000,
"installmentNumber": 4,
"dueDate": "2027-02-01",
"disbursedAt": "2026-10-01T18:00:00.000Z",
"settledAt": null,
"disbursement": { "status": "PENDING", "endToEndId": null },
"installments": [
{ "seq": 1, "dueDate": "2026-11-01", "amount": 47250, "paid": false, "payoff": null },
{ "seq": 2, "dueDate": "2026-12-01", "amount": 47250, "paid": false, "payoff": null },
{ "seq": 3, "dueDate": "2027-01-01", "amount": 47250, "paid": false, "payoff": null },
{ "seq": 4, "dueDate": "2027-02-01", "amount": 47250, "paid": false, "payoff": null }
],
"payoff": null,
"repayments": [],
"createdAt": "2026-10-01T17:59:40.000Z"
}
}
nota

disbursement.status nasce PENDING, vai a SENT quando o Pix é instruído e a CONFIRMED quando ele é confirmado, com o endToEndId preenchido. Se o Pix falhar, a operação vai para CANCELLED com outstanding zero: nada é devido.