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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
simulationId | string | Sim | O simulationId de uma simulação APPROVED da sua empresa, ainda dentro do expiresAt. |
correlationID | string | Sim | Seu identificador, único por empresa. |
pixKey | string | Não | Chave 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"
}
| Status | error | Significado |
|---|---|---|
404 | SIMULATION_NOT_FOUND | O simulationId não existe para a sua empresa. |
422 | SIMULATION_EXPIRED | A simulação expirou. Simule de novo. |
422 | SIMULATION_CONSUMED | A simulação já foi contratada ou recusada. |
422 | PIX_KEY_NOT_BORROWER | A pixKey não é do tomador nem uma chave Woovi permitida da sua empresa. Veja Para onde vai o dinheiro. |
422 | PIX_KEY_NOT_FOUND | A pixKey não existe no DICT. |
422 | PIX_KEY_UNVERIFIABLE | Não foi possível confirmar o dono da pixKey no DICT agora. Tente de novo. |
422 | NO_FUNDS | O fundo não tem saldo para pagar este empréstimo agora. A simulação continua aberta até expirar. |
422 | UTILIZATION_CAP | O fundo chegou ao limite de empréstimos por agora. A simulação continua aberta até expirar. |
422 | COMPANY_CAP | A sua empresa chegou à fatia dela no fundo. A simulação continua aberta até expirar. |
422 | ALREADY_ACTIVE | O tomador já tem um empréstimo em aberto. |
422 | FUND_INACTIVE | O fundo da simulação foi fechado. |
422 | FUND_CLOSED | Nenhum 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
- Shell + cURL
- JavaScript + Fetch
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"
}'
fetch('https://api.woovi.com/api/v1/loan/operation', {
method: 'POST',
headers: {
Authorization: '{SEU_APP_ID}',
'Content-Type': 'application/json',
},
body: JSON.stringify({
simulationId: '6abeadd43f02bc8c8675c0ad',
pixKey: '+5511999999999',
correlationID: 'erp-loan-42',
}),
}).then((res) => res.json());
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"
}
}
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.