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

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

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

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.

• De R$ 100,00 a R$ 2.500,00 por empréstimo (10000 a 250000 centavos), para qualquer tomador.
• 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.
• Onde a pessoa recebe não importa. O desembolso vai para a chave Pix informada ou, sem ela, para o próprio documento do tomador como chave Pix.
• 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é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).

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. Em POST /simulation: TAXID_TYPE_NOT_ELIGIBLE. Em POST /operation: ALREADY_ACTIVE, ORIGINATION_CLOSED, TAXID_TYPE_NOT_ELIGIBLE, SCREENING_REFUSED, FUND_INACTIVE, FUND_CLOSED. Em POST /operation/{id}/payoff: veja Pagar empréstimo.
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.