> ## 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 migrações, a configuração que a originação exige e o token que carrega o oficial.

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 tudo aqui é verdadeiro, siga o [Início rápido](/pt/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 dele                                                                          |
| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| **PostgreSQL**                    | 17     | O armazenamento de dados primário. Cada produto, proposta, cronograma e intenção de posting vive aqui. |
| **Valkey** (compatível com Redis) | 8      | Registros de idempotência, cache e rate limiting.                                                      |
| **Provedor de identidade**        | —      | Emite os tokens bearer contra os quais o Lender autoriza cada rota.                                    |
| **Midaz**                         | —      | O ledger onde chega o posting do desembolso. Opcional para o seu primeiro empréstimo.                  |
| **RedPanda**                      | —      | A espinha dorsal de streaming do catálogo de eventos. Opcional.                                        |

PostgreSQL, Valkey e um provedor de identidade são os três sem os quais você não origina. Um primeiro empréstimo não precisa de Midaz nem de RedPanda. Leia [Postings no ledger](#postings-no-ledger) mais abaixo para saber o que fica esperando.

## Execute o Lender localmente

***

O Lender é um único serviço em Go. Uma execução local precisa do toolchain de Go em 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 migrações">
    `make migrate-up` aplica os dois conjuntos de migrações. Veja a seção seguinte.
  </Step>

  <Step title="Execute com recarga ao vivo">
    `make dev` executa o serviço com Air.
  </Step>
</Steps>

## Aplique os dois conjuntos de migrações

***

O Lender não migra o banco de dados quando sobe. Você aplica as migrações fora de banda, e há dois conjuntos:

| Ajuste               | Valor padrão                           | Conteúdo                                                                     |
| -------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
| `MIGRATIONS_PATH`    | `migrations`                           | O esquema central — produtos, propostas, cronogramas, contabilidade, outbox. |
| `MIGRATIONS_BR_PATH` | `internal/jurisdictions/br/migrations` | O esquema da jurisdição do Brasil.                                           |

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

O conjunto central também semeia 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 implantado carrega o comportamento de cada perfil, e a tabela registra quais códigos esse binário conhece. Leia [Jurisdições](/pt/lender/jurisdictions) para saber o que um perfil decide.

## Configuração obrigatória

***

Dois ajustes governam a originação. Configure os dois antes da primeira chamada.

### Um sujeito autenticado — `PLUGIN_AUTH_ENABLED=true`

O Lender registra quem agiu sobre cada proposta de empréstimo. Ele lê o **oficial designado a partir do subject do token bearer**, não a partir do corpo da requisição. Cada chamada de proposta de empréstimo precisa então de uma identidade autenticada.

Configure 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 um claim subject não vazio, e sob o perfil genérico `XX` o mesmo subject deve criar, aprovar e desembolsar a proposta.

`make generate-casdoor` escreve os papéis e permissões do Lender em `config/casdoor/init_data.json`. Carregue essa semente no seu provedor de identidade. O papel do oficial 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 para o posting — `OUTBOX_ENABLED=true`

Um empréstimo desembolsado precisa registrar sua intenção de posting de forma durável. O Lender escreve essa intenção em um outbox transacional, na mesma transação de banco que move a proposta para `disbursed`. Configure `OUTBOX_ENABLED=true` para que o outbox esteja disponível quando você desembolsar.

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

## Postings no ledger

***

Aponte o Lender para o Midaz quando você quiser que os postings cheguem ao ledger:

| Variável                                          | Propósito                                          |
| ------------------------------------------------- | -------------------------------------------------- |
| `MIDAZ_LEDGER_BASE_URL`                           | O endereço do ledger.                              |
| `MIDAZ_OAUTH_TOKEN_URL`                           | De onde o Lender obtém suas credenciais do ledger. |
| `MIDAZ_LEDGER_ORGANIZATION_ID`, `MIDAZ_LEDGER_ID` | O destino de posting padrão no modo single-tenant. |

O empréstimo se origina com ou sem essas variáveis. Até você configurar um endpoint do ledger, as intenções de posting 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` é `false` por padrão. Nesse modo `DEFAULT_TENANT_ID` identifica o único tenant, e precisa ser um UUID válido.

## Acréscimos multi-tenant

***

O modo multi-tenant dá a cada tenant o seu próprio esquema e o seu próprio pool de clientes do ledger. Ele acrescenta quatro requisitos:

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

## Streaming de eventos

***

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

## Lista de verificação

***

* PostgreSQL 17 e Valkey 8 alcançáveis.
* Os dois conjuntos de migrações aplicados.
* `PLUGIN_AUTH_ENABLED=true` e o provedor de identidade alcançável.
* Um token bearer com subject e cada permissão da tabela acima.
* `OUTBOX_ENABLED=true`.
* `DEFAULT_TENANT_ID` como UUID válido, no modo single-tenant.

## Próximos passos

***

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

<Card title="Configuração e implantação" icon="sliders" href="/pt/lender/configuration-and-deploy" horizontal>
  A forma completa do contêiner, a superfície de ambiente mais ampla e o caminho do posting até o ledger.
</Card>