> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Pré-requisitos

> O que precisa estar pronto antes da sua primeira chamada ao Lender: os serviços de que ele depende, os dois conjuntos de migrations, a configuração que a originação exige e o token que carrega o analista.

O Lender precisa de um conjunto pequeno de coisas prontas antes da primeira chamada de API. Esta página lista essas coisas na ordem em que você as configura. Quando cada item aqui estiver pronto, siga o [Início rápido](/pt/products/lender/lender-quick-start) para originar um empréstimo.

## Serviços de que o Lender depende

***

| Serviço                           | Versão | Por que o Lender precisa                                                                                   |
| --------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| **PostgreSQL**                    | 17     | O armazenamento de dados principal. Cada produto, proposta, cronograma e intenção de lançamento vive aqui. |
| **Valkey** (compatível com Redis) | 8      | Registros de idempotência, cache e rate limit.                                                             |
| **Provedor de identidade**        | —      | Emite os tokens bearer contra os quais o Lender autoriza cada rota.                                        |
| **Midaz**                         | —      | O ledger que o lançamento de desembolso alcança. Opcional para o seu primeiro empréstimo.                  |
| **RedPanda**                      | —      | O backbone de streaming do catálogo de eventos. Opcional.                                                  |

PostgreSQL e Valkey são obrigatórios para originar. Um provedor de identidade é obrigatório quando a autorização de rota está habilitada. Produção exige um. Um primeiro empréstimo não precisa de Midaz nem de RedPanda. Leia [Lançamentos no ledger](#ledger-postings) abaixo para saber o que fica esperando.

## Rode o Lender localmente

***

O Lender é um único serviço Go. Uma execução local precisa do toolchain Go na versão 1.26 ou posterior, Docker com Compose e Make.

<Steps>
  <Step title="Crie o arquivo de ambiente">
    `make set-env` copia `config/.env.example` para `config/.env`. Edite esse arquivo para cada ajuste desta página.
  </Step>

  <Step title="Suba as dependências">
    `make up` sobe as dependências do Compose e o serviço na porta `8080`.
  </Step>

  <Step title="Aplique as migrations">
    `make migrate-up` aplica os dois conjuntos de migrations. Veja a próxima seção.
  </Step>

  <Step title="Rode com live reload">
    `make dev` roda o serviço com o Air.
  </Step>
</Steps>

## Aplique os dois conjuntos de migrations

***

O Lender não migra o banco de dados quando sobe. Você aplica as migrations por fora, e existem dois conjuntos:

| Conjunto de migrations | Diretório fixo                         | Conteúdo                                                                |
| ---------------------- | -------------------------------------- | ----------------------------------------------------------------------- |
| Core                   | `migrations`                           | O schema core: produtos, propostas, cronogramas, contabilidade, outbox. |
| Jurisdição Brasil      | `internal/jurisdictions/br/migrations` | O schema da jurisdição Brasil.                                          |

Aplique os dois. `make migrate-up` lê os dois caminhos.

O conjunto core também popula o **registro de jurisdições**: duas jurisdições ativas, `BR` para o Brasil e `XX`, o perfil genérico. Nenhuma API cria uma jurisdição. O binário em produção carrega o comportamento de cada perfil, e a tabela registra quais códigos esse binário conhece. Leia [Jurisdições](/pt/products/lender/jurisdictions) para saber o que um perfil decide.

## Configuração obrigatória

***

O outbox em PostgreSQL é obrigatório e é inicializado automaticamente. Configure a autenticação quando o seu deploy habilita a autorização de rota.

### Um subject autenticado: quando `PLUGIN_AUTH_ENABLED=true`

O Lender registra quem agiu em cada proposta de empréstimo. Ele lê o **analista responsável a partir do subject do token bearer**, não do corpo da requisição. Cada chamada de proposta de empréstimo precisa, portanto, de uma identidade autenticada.

Defina duas variáveis:

| Variável              | Valor                                     |
| --------------------- | ----------------------------------------- |
| `PLUGIN_AUTH_ENABLED` | `true`                                    |
| `PLUGIN_AUTH_HOST`    | O endereço do seu provedor de identidade. |

Depois, envie um token bearer em cada chamada. O token precisa de uma claim de subject não vazia e, sob o perfil genérico `XX`, o mesmo subject deve criar, aprovar e desembolsar a proposta.

O Lender define os papéis e as permissões dele em um arquivo de seed. Carregue esse seed no seu provedor de identidade. O papel do analista precisa destas permissões:

| Recurso             | Ações                                               |
| ------------------- | --------------------------------------------------- |
| `loan_product`      | `write`                                             |
| `accounting`        | `write`                                             |
| `loan_applications` | `preview:schedule`, `create`, `approve`, `disburse` |
| `loan_accounts`     | `read`                                              |

### Um destino durável de lançamento: sempre presente

Um empréstimo desembolsado registra a intenção de lançamento dele de forma durável. O Lender inicializa o outbox transacional em PostgreSQL em cada deploy, na mesma transação de banco de dados que move a proposta para `disbursed`. `OUTBOX_ENABLED` não existe.

O dispatcher repassa cada intenção depois, na cadência que `OUTBOX_DISPATCH_INTERVAL_SEC` define. Leia [Contabilidade e rodadas de apropriação](/pt/products/lender/accounting-and-accrual-runs) para saber o que o ledger recebe.

<h2 id="ledger-postings">
  Lançamentos no ledger
</h2>

***

Aponte o Lender para o Midaz quando você quiser que os lançamentos caiam no ledger:

| Variável                                          | Objetivo                                              |
| ------------------------------------------------- | ----------------------------------------------------- |
| `MIDAZ_LEDGER_BASE_URL`                           | O endereço do ledger.                                 |
| `MIDAZ_OAUTH_TOKEN_URL`                           | Onde o Lender pega as credenciais de ledger dele.     |
| `MIDAZ_LEDGER_ORGANIZATION_ID`, `MIDAZ_LEDGER_ID` | O destino padrão de lançamento no modo single-tenant. |

O empréstimo é originado com ou sem essas variáveis. Enquanto você não configurar um endpoint de ledger, as intenções de lançamento ficam duráveis no outbox e o lançamento no ledger espera. Configure o ledger antes de esperar contabilizações.

## Padrões single-tenant

***

`MULTI_TENANT_ENABLED` tem `false` como padrão. Nesse modo, `DEFAULT_TENANT_ID` identifica o único tenant, e deve ser um UUID válido.

## Acréscimos do modo multi-tenant

***

O modo multi-tenant dá a cada tenant um schema próprio e um pool de clientes de ledger próprio. Ele adiciona quatro requisitos:

1. Defina `MULTI_TENANT_ENABLED=true` e aponte o Lender para o tenant manager.
2. Cada token carrega uma claim `tenantId`.
3. `public.tenant_jurisdictions` carrega uma linha para cada par de tenant e jurisdição.
4. Cada perfil contábil declara o `midazOrganizationId` e o `midazLedgerId` próprios. O modo multi-tenant não recorre aos padrões de ambiente.

## Streaming de eventos

***

O streaming vem desligado por padrão e a originação não precisa dele. Para publicar o catálogo de eventos de ciclo de vida, defina `STREAMING_ENABLED=true`, aponte `STREAMING_BROKERS` para o RedPanda e defina `STREAMING_CLOUDEVENTS_SOURCE=lender`. O Lender valida esse valor de source quando sobe.

## Checklist

***

* PostgreSQL 17 e Valkey 8 acessíveis.
* Os dois conjuntos de migrations aplicados.
* Quando a autorização de rota está habilitada, defina `PLUGIN_AUTH_ENABLED=true`, garanta que o provedor de identidade está acessível e use um token bearer com um subject e cada permissão da tabela acima.
* `DEFAULT_TENANT_ID` um UUID válido, no modo single-tenant.

## Próximos passos

***

<Card title="Início rápido" icon="rocket" href="/pt/products/lender/lender-quick-start" horizontal>
  Seis chamadas de um banco de dados vazio até um empréstimo desembolsado.
</Card>

<Card title="Configuração e deploy" icon="sliders" href="/pt/products/lender/configuration-and-deploy" horizontal>
  O formato completo do container, a superfície de ambiente mais ampla e o caminho de lançamento no ledger.
</Card>