# Visão geral da API de Empréstimo

> Como autenticar e integrar a API REST de Empréstimo da Woovi para simular, originar, acompanhar e pagar empréstimos a partir do seu sistema.

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](https://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`.

```sh
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](/api-redoc/) (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](./how-to-pay-a-loan-using-api). |
| `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. |