Skip to main content

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.

info

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​

AmbienteURL base
Produçãohttps://api.woovi.com
Sandbox (testes)https://api.woovi-sandbox.com

Todos os endpoints ficam sob o prefixo /api/v1/loan.

Autenticação​

  1. Crie uma aplicação em app.woovi.com e copie o app_id.
  2. Envie-o no cabeçalho Authorization de toda requisição.
  3. A empresa que origina é resolvida a partir do app_id. Você nunca informa o companyId.
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​

EscopoPermite
LOAN_SIMULATION_POSTSimular um empréstimo
LOAN_OPERATION_POSTOriginar um empréstimo
LOAN_OPERATION_GETConsultar 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).
  • taxID pode 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. Em POST /operation ele é obrigatório e único por empresa: repetir devolve a mesma operação, nunca origina duas.

Endpoints​

MétodoEndpointEscopo
POST/api/v1/loan/simulationLOAN_SIMULATION_POST
POST/api/v1/loan/operationLOAN_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}/payoffLOAN_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​

StatusSignificado
400Corpo ou parâmetros inválidos. Formato: { "error": "INVALID_REQUEST", "message": "..." }
401app_id inválido ou IP não autorizado. Formato: { "data": null, "errors": [{ "message": "Invalid appID" }] }
403Escopo ausente ou Empréstimo não habilitado para a empresa.
404Operação não encontrada para a empresa.
422Recusa 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).
503Dependência indisponível (UNAVAILABLE), em qualquer endpoint, porque vem da validação da credencial. Repita mais tarde, com o mesmo correlationID quando houver.