Visão geral da API de Empréstimo
A API de Empréstimo permite que um parceiro simule, origine, acompanhe e pague empréstimos concedidos pela Woovi a uma pessoa ou empresa. A Woovi financia; o parceiro informa quem está pedindo, quanto e em quantas parcelas, e acompanha o pagamento.
É uma API REST no estilo OpenPix: autenticação por app_id no cabeçalho
Authorization, corpo em JSON, valores monetários em centavos e escopos por
funcionalidade.
Para utilizar esta API é necessário que a empresa possua a funcionalidade de
Empréstimo habilitada. Caso contrário, as requisições retornam 403.
Ambiente e URL base
| Ambiente | URL base |
|---|---|
| Produção | https://api.woovi.com |
| Sandbox (testes) | https://api.woovi-sandbox.com |
Todos os endpoints ficam sob o prefixo /api/v1/loan.
Autenticação
- Crie uma aplicação em app.woovi.com e copie o
app_id. - Envie-o no cabeçalho
Authorizationde toda requisição. - A empresa que origina é resolvida a partir do
app_id. Você nunca informa ocompanyId.
Authorization: {SEU_APP_ID}
Content-Type: application/json
Além do app_id, a autenticação valida a lista de IPs da aplicação, o
escopo exigido pelo endpoint e a funcionalidade de Empréstimo na empresa.
Escopos
| Escopo | Permite |
|---|---|
LOAN_SIMULATION_POST | Simular um empréstimo |
LOAN_OPERATION_POST | Originar um empréstimo |
LOAN_OPERATION_GET | Consultar um empréstimo ou listar os de um documento |
Regras do produto
Elas simplificam a integração: o parceiro não tem alavancas de preço.
- Limites do fundo. Valor e número de parcelas seguem o fundo que financia (por padrão de R$ 100,00 a R$ 2.500,00 e até 8 parcelas).
- Simule antes de contratar. A originação contrata uma simulação aprovada pelo
simulationId; valor e parcelas vêm dela. - Um empréstimo ativo por vez. Um segundo pedido é recusado com
ALREADY_ACTIVE. - Nenhum endpoint marca parcela como paga. O parceiro pede uma cobrança Pix (próxima parcela, um intervalo ou tudo) e a baixa acontece quando o Pix é pago. Vale uma cobrança viva por parcela: pedido que cubra parcela com cobrança em aberto é recusado com
CHARGE_OVERLAPS. - O dinheiro vai para o tomador. O desembolso vai para uma chave Pix do tomador ou, sem ela, para o próprio documento dele como chave Pix. Um fundo aberto para isso também pode pagar uma chave Woovi da empresa que origina.
- A regra que impede beneficiário de Antecipação de pedir empréstimo ainda não é aplicada pela API.
Convenções
- Valores monetários são inteiros em centavos (
150000= R$ 1.500,00). taxIDpode ser CPF ou CNPJ, com ou sem máscara.- Taxas são decimais (
0.1= 10% ao mês). A taxa por período sai por equivalência, nunca por divisão. - Datas de vencimento são
YYYY-MM-DD; instantes são ISO 8601. correlationIDé seu identificador. EmPOST /operationele é obrigatório e único por empresa: repetir devolve a mesma operação, nunca origina duas.
Endpoints
| Método | Endpoint | Escopo |
|---|---|---|
POST | /api/v1/loan/simulation | LOAN_SIMULATION_POST |
POST | /api/v1/loan/operation | LOAN_OPERATION_POST |
GET | /api/v1/loan/operation?taxID= | LOAN_OPERATION_GET |
GET | /api/v1/loan/operation/{id} | LOAN_OPERATION_GET |
POST | /api/v1/loan/operation/{id}/payoff | LOAN_OPERATION_POST |
Consulte a referência completa na página API (tag loan).
Webhooks
LOAN_PAYMENT_RECEIVED avisa cada pagamento recebido e LOAN_SETTLED avisa a
quitação. Veja Webhooks de Empréstimo.
Erros
| Status | Significado |
|---|---|
400 | Corpo ou parâmetros inválidos. Formato: { "error": "INVALID_REQUEST", "message": "..." } |
401 | app_id inválido ou IP não autorizado. Formato: { "data": null, "errors": [{ "message": "Invalid appID" }] } |
403 | Escopo ausente ou Empréstimo não habilitado para a empresa. |
404 | Operação não encontrada para a empresa. |
422 | Recusa por regra de produto, no formato { "error": "NO_FUNDS", "message": "..." }: error é o código para a sua integração decidir e message explica o motivo. Veja as recusas de Originar e de Pagar. Uma simulação recusada não é 422: volta 200 com status: "REFUSED" (Simular). |
503 | Dependência indisponível (UNAVAILABLE), em qualquer endpoint, porque vem da validação da credencial. Repita mais tarde, com o mesmo correlationID quando houver. |