~~NOTOC~~
====== Indexação de Títulos por Índice Financeiro / Commodities ======

Este recurso permite vincular parcelas do **Contas a Receber** a um índice de preço (commodity ou moeda estrangeira), substituindo o valor monetário fixo por uma **quantidade de unidades do índice**. O valor a pagar é recalculado automaticamente pela cotação vigente no momento da baixa.

Exemplos de aplicação:
  * Pecuária: títulos expressos em arrobas de boi (@ = R$ 277,00)
  * Cafeicultura: financiamentos expressos em sacas de café (60 kg)
  * Contratos dolarizados: recebíveis em USD convertidos ao câmbio do dia

\\
===== Conceitos Fundamentais =====

==== Índice Financeiro ====

Um índice é a unidade de referência que serve de base para a correção do título. Cada índice possui:

^ Campo       ^ Descrição                                      ^
| Nome        | Identificação do índice (ex.: "ARROBA BOI")    |
| Unidade     | Símbolo da unidade (ex.: "@B", "SC60", "USD")  |
| Descrição   | Descrição livre (ex.: "Boi Gordo - arroba")   |

Tabela de banco de dados: **TFinIndice**

==== Cotação ====

Cada índice mantém um histórico de cotações por data. Cada entrada registra o preço em R$ naquela data. O sistema sempre busca a cotação **mais recente anterior ou igual** à data consultada (sem interpolação).

  * Exemplo: cotação da arroba em 15/05/2026 = R$ 285,40

Tabela de banco de dados: **TFinIndiceCotacao**

==== Preço de Referência ====

Quando um documento é vinculado a um índice, registra-se o **preço de referência**: o valor do índice na data da negociação. Esse preço define a quantidade de unidades de cada parcela:

<code>
Qtd. índice = Valor da parcela / Preço de referência
</code>

Exemplo: parcela de R$ 5.000,00 com arroba a R$ 250,00 → **20 arrobas**.

==== Ajuste pelo Índice ====

Na data da baixa, o valor a receber é recalculado pela cotação atual:

<code>
Valor atual da parcela = Qtd. índice pendente × Cotação do dia
</code>

A diferença em relação ao valor pendente original é o **AjustePeloIndice**, que pode ser positivo (valorização) ou negativo (desvalorização).

\\
===== Configuração Inicial =====

==== Parâmetro do Sistema ====

Acesse **Parâmetros da Empresa → Financeiro / Receber** e habilite:

  * **RecUtilizaIndice** – "Define se utiliza índice financeiro/commodity para correção de valores de títulos"

Enquanto este parâmetro estiver desabilitado, as telas de vinculação ficam ocultas no menu.

==== Autonomias ====

Configure as permissões por usuário/grupo em **Autonomias do Sistema**:

^ Código ^ Descrição                                              ^ Padrão ^
| 9100   | Permite vincular documento ao índice de correção       | Não    |
| 9101   | Permite desvincular documento do índice de correção    | Não    |

\\
===== Cadastro de Índices =====

Menu: **Financeiro → Receber → Índices Financeiros**

Esta tela lista todos os índices cadastrados. Operações disponíveis:

^ Tecla         ^ Ação                                    ^
| F5 / Insert   | Cadastrar novo índice                   |
| F6 / Espaço   | Editar índice selecionado               |
| F9 / Cotações | Abrir histórico de cotações do índice   |
| F8 / Delete   | Excluir índice (não permitido se houver documentos vinculados) |

==== Regra de Exclusão ====

Um índice só pode ser excluído se **nenhum** documento de Contas a Receber estiver vinculado a ele. Isso inclui documentos cancelados.

\\
===== Histórico de Cotações =====

Acessível pelo botão **Cotações** na tela de índices (F9).

Exibe um painel de cards com a **última cotação registrada** de cada índice cadastrado, e abaixo uma grade com todo o histórico cronológico. Cada linha registra:

^ Campo   ^ Descrição               ^
| Índice  | Nome do índice          |
| Data    | Data da cotação         |
| Valor   | Preço em R$             |
| Usuário | Quem registrou          |

==== Incluindo uma Cotação ====

  - Pressione **F5 / Insert** para adicionar.
  - Selecione o índice na lista suspensa.
  - Informe a data e o valor (R$).
  - Confirme.

> **Atenção:** Ao incluir a cotação de uma data já existente, o valor é sobrescrito.

\\
===== Vinculação de Documentos =====

Menu: **Financeiro → Receber → Aplicar Índice a Documentos**

Esta tela permite selecionar um cliente e vincular (ou desvincular) seus documentos a um índice de correção.

==== Fluxo de Vinculação ====

  - Selecione o **índice** no combo superior.
  - Informe a **data de referência** (data da negociação original).
  - O campo **Cotação** é preenchido automaticamente com o valor do índice nessa data (pode ser ajustado manualmente).
  - A grade exibe as parcelas do cliente com as colunas:

^ Coluna           ^ Descrição                              ^
| Situação         | A Vencer / Vencido / Pago              |
| Parcela          | Número da parcela                      |
| Vencimento       | Data de vencimento                     |
| Valor original   | Valor monetário original               |
| Qtd. índice      | Quantidade de unidades do índice       |
| Qtd. pago        | Quantidade já liquidada                |
| Qtd. pendente    | Quantidade ainda a receber             |
| Cotação origem   | Preço na data de referência            |
| Cotação atual    | Última cotação registrada              |

  - Clique em **Aplicar** para vincular os documentos selecionados.
  - Clique em **Desvincular** para remover o vínculo (requer autonomia 9101).

\\
===== Baixa de Parcela Indexada =====

Quando uma parcela vinculada a um índice é aberta na tela de recebimento (**FREC601AA**), o sistema abre automaticamente a tela **FREC605AB** (ao invés da FREC605AC padrão).

==== Campos da Tela ====

**Painel de dados da parcela:**

^ Campo                  ^ Descrição                                  ^
| Documento / Parcela    | Identificação                              |
| Emissão / Vencimento   | Datas                                      |
| Valor original         | Valor monetário original da parcela        |
| Valor baixado          | Montante já recebido anteriormente         |
| Valor pendente         | Saldo devedor em R$                        |

**Painel de indexação:**

^ Campo                  ^ Descrição                                  ^
| Cotação em (emissão)   | Preço do índice na data de referência      |
| Qtde total [unidade]   | Total de unidades da parcela               |
| Qtde pago              | Unidades já recebidas                      |
| Qtde pendente          | Unidades ainda a receber                   |
| Cotação atual          | Última cotação registrada                  |
| Ajuste                 | Diferença entre valor atual e pendente     |
| Valor atual            | Valor recalculado pela cotação atual       |

**Painel de recebimento:**

^ Campo                  ^ Descrição                                             ^
| Data                   | Data do recebimento                                   |
| Cotação (editável)     | Cotação a usar na baixa (padrão = cotação mais atual) |
| A baixar (R$)          | Valor monetário a receber nesta operação              |
| Acrésc./Desconto       | Acréscimo (positivo) ou desconto (negativo)           |
| A receber (R$)         | Valor efetivamente a receber = A baixar + Desconto    |
| Restante (R$)          | Valor atual − A baixar                                |

Os campos de **Qtde** (em unidades do índice) são calculados automaticamente ao alterar os valores em R$ ou a cotação.

==== Modelo de Cálculo na Baixa ====

<code>
QtdIndiceBaixado  = ValorRecebido / PrecoCotacao
VlrBaixadoIndice  = QtdIndiceBaixado × PrecoReferencia
ValorRestante     = ValorPendente − VlrBaixadoIndice
</code>

  * O valor **salvo na baixa** (`TRecBaixaParcela.VALORBAIXADO`) é expresso nas **unidades do índice na data de referência**, garantindo comparabilidade histórica.
  * A **cotação** gravada na baixa é o preço usado no dia do recebimento.
  * **Juros e multa são desativados** para parcelas indexadas; o ajuste pelo índice substitui essa correção.

==== Tolerância de Centavos ====

Para evitar resíduos de centavos em parcelas em fase de quitação, há uma tolerância de **R$ 0,50**: se o valor restante calculado for menor que esse limite, ele é automaticamente zerado e a parcela é quitada integralmente.

\\
===== Comportamento na Tela de Recebimento =====

  * **Total Atual** passa a incluir o `TTAjusteIndice` (soma dos ajustes por índice de todas as parcelas marcadas).
  * Os campos **Juros** e **Multa** na tela de confirmação (FREC601AF) ficam **desabilitados** quando há parcelas indexadas no lote.
  * Parcelas a vencer exibem-se em **azul**; parcelas vencidas em **vermelho** (independente da seleção).
  * Ao desmarcar uma parcela, os campos de valor, data e desconto são zerados corretamente no dataset.

\\
===== Exemplo Prático =====

==== Cenário ====

Um fazendeiro vende gado e negocia um título de **R$ 50.000,00** indexado à **arroba do boi**, com cotação de referência de **R$ 250,00/@** em 01/01/2026.

  * Qtde total = 50.000 / 250 = **200 arrobas**
  * Na data do recebimento (30/05/2026), a cotação está em **R$ 285,00/@**
  * Valor atual da parcela = 200 × 285,00 = **R$ 57.000,00**
  * Ajuste pelo índice = 57.000 − 50.000 = **+R$ 7.000,00**

O cliente paga R$ 57.000,00. O sistema registra:
  * `QTDINDICE = 200`
  * `PRECOCOTACAO = 285,00`
  * `VALORBAIXADO` calculado pela cotação de referência (R$ 250,00)

==== Baixa Parcial ====

Se o cliente pagar apenas **R$ 28.500,00** (metade):
  * QtdIndiceBaixado = 28.500 / 285 = **100 arrobas**
  * VlrBaixadoIndice = 100 × 250 = R$ 25.000,00 (valor baixado do pendente original)
  * Restante = 50.000 − 25.000 = **R$ 25.000,00 (100 arrobas)**

Na próxima baixa, as **100 arrobas restantes** serão recalculadas pela cotação vigente.