Gestão de Contratos Dhara Barter - Manual de Ajuda do Add-on

Gestão de Contratos Barter — Manual de Ajuda do Add-on

Módulo Gestão GCB — Plataforma Sankhya. Dhara Tecnologia. Documento de ajuda • Uso do sistema e referência técnica.

SUMÁRIO:

1. Visão Geral do Módulo

2. Estrutura de Menu

3. Cadastros

4. Contratos Barter (Rotina)

5. Conceitos e Regras de Cálculo

6. Apêndice Técnico — Dicionário de Dados

1. VISÃO GERAL DO MÓDULO:

O add-on Gestão de Contratos Barter (Gestão GCB) permite o controle integrado de operações de troca comercial lastreadas em produto agrícola, de forma integrada ao ERP Sankhya Om. Em uma operação Barter, o produtor rural recebe insumos (adubo, defensivos, sementes — uma venda de insumos no ERP) e paga com grãos/produção (soja, milho — entradas de grãos). O valor das duas pontas é convertido para uma moeda/indexador de produto agrícola (por exemplo, SOJA ESALQ/BMF), permitindo comparar e liquidar tudo em "sacas".

O módulo acompanha o contrato nas dimensões contratual, operacional, financeira e gerencial: registra o contrato e suas partes, vincula automaticamente as vendas de insumos e as entradas de grãos, calcula os saldos em sacas e o acerto financeiro, e disponibiliza a visão das compensações financeiras. A liquidação em si ocorre pela rotina nativa de compensação financeira do Sankhya — o módulo não executa a compensação, apenas a integra, valida e exibe.

1.1 Principais recursos

Cadastro e gestão de contratos Barter (partes, safra, produto de referência, indexador/moeda, valor da saca).

Vinculação automática das vendas de insumos (saídas) e das entradas de grãos ao contrato.

Cálculo dinâmico dos saldos em sacas (negociadas, recebidas, saldo) e do acerto financeiro.

Geração de pedido de insumo a partir do contrato.

Propagação do contrato e do vencimento para os títulos financeiros gerados.

Visão das compensações financeiras nativas vinculadas ao contrato.

Integração com o contrato de grãos (origem do valor da saca e do vencimento).

1.2 Conceitos-chave (glossário)

Contrato Barter — Define a troca de insumos por produto agrícola (moeda/indexador).

Moeda / Indexador — Cadastro nativo Sankhya usado para precificar e liquidar em "produto" (ex.: SOJA ESALQ/BMF).

Valor da Saca Fixado (VLR_SACA_FIX) — Preço de referência da saca; vem do contrato de grãos ou é informado manualmente.

Sacas Negociadas — Total de sacas equivalentes geradas pelas vendas (saídas) vinculadas ao contrato.

Sacas Recebidas / Alocadas — Sacas provenientes das entradas de grãos vinculadas ao contrato.

Saldo (Sacas) — Sacas negociadas menos sacas recebidas.

Acerto Financeiro (VLR_DIF_LIQ) — Diferença entre o valor das entradas (grãos) e o das saídas (insumos).

Compensação financeira — Rotina nativa que compensa títulos a pagar (grãos) e a receber (insumos) na mesma moeda.

1.3 Como este manual está organizado

O manual descreve a única tela operacional do módulo (Contratos Barter) com seus campos, abas e botões, acompanhados das regras de negócio aplicadas pelo sistema. Uma seção dedicada explica os conceitos e cálculos (sacas, saldo, acerto financeiro). Ao final, o Apêndice Técnico consolida o dicionário de dados completo, a view de compensações e as extensões feitas em entidades padrão do Sankhya.

2. ESTRUTURA DE MENU:

O add-on é acessado pelo menu Gestão GCB, com um grupo de Cadastros:

Cadastros (Gestão GCB » Cadastros)

Contratos Barter — Tela — gestão e consulta dos contratos Barter.

Safras Barter — Formulário — cadastro de safras do módulo.

3. CADASTROS:

3.1 Safras Barter

Formulário padrão para cadastro das safras utilizadas no módulo, com período (início e fim) e data prevista de colheita. A abreviação é usada em código de barras.

ID_SAFRA — Inteiro, PK (automático). Código da safra.

DESCRSAFRA — Texto. Descrição da safra (apresentação).

DTINICIO / DTFIM — Data. Início e fim da safra.

DTPREVINICIO — Data. Data prevista de colheita.

ABREVIACAO — Inteiro. Abreviação (código de barras).

4. CONTRATOS BARTER (ROTINA):

Contratos Barter é a tela central do módulo, construída em HTML5 sobre a plataforma Sankhya. Ela serve para consultar e gerir os contratos e para executar, em lote, duas ações de processamento. As abas de Itens de Saída e Entradas de Grãos são somente de leitura: seus registros e todos os valores agregados são preenchidos automaticamente quando notas com o contrato vinculado (campo ID Contrato Barter) são salvas — nunca digitados na tela.

4.1 Campos do cabeçalho

IDBARTER — Inteiro, PK (automático). Identificador do contrato.

CODEMP — Inteiro (FK Empresa), Obrigatório. Empresa.

CODPARC_PRODUTOR — Inteiro (FK Parceiro), Obrigatório. Produtor (parceiro).

RAZAOSOCIAL — Texto, Calculado. Razão social do produtor.

STATUS — Lista. A=Ativo, L=Liquidado, C=Cancelado, N=Em Negociação.

ID_DHSAFRA / ID_SAFRA — Inteiro (FK). Safra do add-on e safra nativa (armazém).

DTCONTRATO — Data, Obrigatório. Data do contrato.

DTVENC / DTPREV_LIQ — Data. Vencimento (do contrato de grãos) e previsão de liquidação.

CODPROD — Inteiro (FK Produto), Obrigatório. Produto de referência.

CODMOEDA — Inteiro (FK Moeda), Obrigatório. Indexador/moeda.

VLR_SACA_FIX — Decimal. Valor da saca fixado (do contrato de grãos ou manual).

SPREAD / DT_FIXACAO — Decimal/Data. Spread e data da fixação.

NUMCONTRATOGRAO — Inteiro. Número do contrato de grãos vinculado.

CODNAT / CODCENCUS — Inteiro (FK). Natureza e centro de resultado (para o pedido de insumo).

CODTIPOPER / CODTIPVENDA — Inteiro (FK). Tipo de operação e tipo de negociação (para o pedido).

SACAS_NEGOCIADAS — Decimal, Calculado. Sacas equivalentes das saídas ÷ valor da saca.

SACAS_RECEBIDAS — Decimal, Calculado. Soma das sacas alocadas das entradas.

SACAS_SALDO — Decimal, Calculado. Negociadas − recebidas.

VLR_TOTAL_SACAS — Decimal, Calculado. Valor total das saídas (R$).

VLR_DIF_LIQ — Decimal, Calculado. Acerto financeiro (entradas − saídas).

OBSERVACAO — Texto. Observação.

4.2 Abas

Itens de Saída (DhBarterSaida): itens das notas de venda de insumos vinculadas ao contrato — nota de saída, produto, quantidade, valor total do item, sacas equivalentes, vendedor e pedido. Somente leitura.

Entradas de Grãos / Liquidação (DhBarterEntrada): itens das notas de entrada de grãos — nota de entrada, produto, local, sacas de entrada, sacas alocadas, valor da saca e valor total alocado. Somente leitura.

Compensações Financeiras (VwDhBarterComp): view com as compensações financeiras nativas ligadas ao contrato — data, número, títulos a pagar (grãos) e a receber (insumos), valor compensado e moeda.

4.3 Botões e regras de negócio

As ações operam sobre os contratos selecionados na grade; se nenhum estiver marcado, o sistema avisa "Selecione pelo menos um contrato na grade.".

Recalcular Contrato — Reconstrói, a partir das notas vinculadas, as abas de Entradas e Saídas e todos os agregados do contrato (rotina de consistência/suporte). Após confirmação ("Deseja recalcular N contrato(s)?"), para cada contrato: limpa as linhas de entrada e saída, reatualiza o valor da saca fixado, relê todas as notas vinculadas (por tipo de movimento: venda ou entrada) e recalcula os saldos e o acerto financeiro. Sucesso: "Contrato(s) recalculado(s) com sucesso!".

Gerar Pedido Insumo — Gera um pedido de venda de insumos para o contrato. Após confirmação ("Deseja gerar pedido para N contrato(s)?"), valida os dados obrigatórios e cria o pedido no ERP já vinculado ao contrato Barter e ao contrato de grãos. Ao final, oferece abrir a Central de Notas no pedido gerado ("Movimento gerado com sucesso! Deseja abrir a Central?").

IMPORTANTE:

Validações do Gerar Pedido Insumo: o contrato deve ter parceiro ("Informe um parceiro para gerar o pedido."), natureza ("Informe uma natureza..."), centro de resultado ("Informe um centro de resultado..."), tipo de negociação ("Informe um tipo de negociação...") e tipo de operação ("Informe um tipo de operação..."). A TOP informada precisa ter um tipo de movimento válido ("TOP informada não possui TIPMOV válido.").

5. CONCEITOS E REGRAS DE CÁLCULO:

Esta seção reúne as regras automáticas que o módulo aplica ao salvar notas vinculadas a um contrato e ao recalculá-lo. Todo o preenchimento das abas e dos agregados é feito por eventos do servidor (sincronização), sem digitação manual.

5.1 Valor da saca fixado

O valor da saca de referência (VLR_SACA_FIX) tem como prioridade o valor negociado no contrato de grãos vinculado (campo VALNEGSC do contrato TCSCON, informado em Número do Contrato de Grão). Quando o contrato de grãos possui esse valor, ele é gravado no contrato Barter (e ressincronizado sempre que muda); quando não possui, o valor informado manualmente é preservado. O vencimento (DTVENC) também é trazido do contrato de grãos.

5.2 Sacas na venda (saídas)

Para cada item de nota de venda de insumos vinculada ao contrato, o sistema calcula as sacas equivalentes dividindo o valor total do item pelo valor da saca fixado:

Sacas Equivalentes = Valor Total do Item (R$) ÷ Valor da Saca Fixado

5.3 Sacas na entrada (grãos)

Para cada item de nota de entrada de grãos, o sistema calcula as sacas de entrada convertendo a quantidade para a unidade "SC" (saca): se a unidade do item já é SC, usa a quantidade direta; caso contrário, busca a unidade alternativa SC do produto e divide a quantidade pela quantidade de conversão (por exemplo, 60.000 kg ÷ 60 = 1.000 sacas). Na Fase 1, as sacas alocadas são iguais às sacas de entrada (alocação total ao contrato). O valor da saca vem do contrato de grãos.

5.4 Saldos e acerto financeiro

Sacas Negociadas — Soma do valor das saídas ÷ valor da saca fixado.

Sacas Recebidas — Soma das sacas alocadas das entradas.

Saldo (Sacas) — Sacas Negociadas − Sacas Recebidas.

Valor Total Sacas (R$) — Soma do valor total dos itens de saída.

Acerto Financeiro (R$) — (Valor da saca × Σ sacas alocadas das entradas) − Σ valor das saídas.

Quando a última nota do contrato é removida, o acerto financeiro é zerado automaticamente.

5.5 Validação do valor unitário na entrada

A validação do valor unitário do grão na entrada é controlada por TOP, pelo parâmetro "Valida Vlr. Unitário Barter" (campo DH_VALVLRBARTER, S/N). Na implementação atual a entrada não é bloqueada por divergência de preço unitário — a referência de preço é sempre tratada pelo valor da saca vindo do contrato de grãos — mas a flag permite ativar a validação por tipo de operação.

5.6 Vínculo com o financeiro e compensação

Ao gerar os títulos financeiros das notas vinculadas, o módulo propaga o contrato Barter (ID Contrato Barter) e o vencimento do contrato para cada título. A liquidação é feita pela rotina nativa de compensação financeira do Sankhya, que compensa os títulos a pagar (grãos) e a receber (insumos) na mesma moeda/indexador; o módulo apenas exibe essas compensações na aba correspondente, por meio de uma view.

6. APÊNDICE TÉCNICO — DICIONÁRIO DE DADOS:

Consolida a estrutura de dados do add-on: tabelas, view de compensações, extensões em entidades nativas e os componentes de servidor que aplicam as regras.

6.1 DH_BARTER — Contrato Barter (DhBarter)

IDBARTER — Inteiro, PK. Identificador do contrato.

CODEMP / CODPARC_PRODUTOR — Inteiro (FK), Obrigatório. Empresa e produtor.

RAZAOSOCIAL — Texto, Calculado. Razão social do produtor.

STATUS — Lista. A=Ativo, L=Liquidado, C=Cancelado, N=Em Negociação.

ID_SAFRA / ID_DHSAFRA — Inteiro (FK). Safra nativa (armazém) e safra do add-on.

DTCONTRATO / DTVENC / DTPREV_LIQ / DT_FIXACAO — Data. Datas do contrato, vencimento, previsão e fixação.

CODPROD / CODMOEDA — Inteiro (FK), Obrigatório. Produto de referência e indexador/moeda.

VLR_SACA_FIX / SPREAD — Decimal. Valor da saca fixado e spread.

NUMCONTRATOGRAO — Inteiro. Contrato de grãos vinculado (TCSCON).

CODNAT / CODCENCUS / CODTIPVENDA / CODTIPOPER — Inteiro (FK). Parâmetros do pedido de insumo.

SACAS_NEGOCIADAS / SACAS_RECEBIDAS / SACAS_SALDO — Decimal, Calculado. Saldos em sacas.

VLR_TOTAL_SACAS / VLR_DIF_LIQ — Decimal, Calculado. Valor total das saídas e acerto financeiro.

OBSERVACAO / DH_DTINS / DH_DTALT — Texto/Data. Observação e datas de inclusão/alteração.

6.2 DH_BARTERSAI — Itens de Saída (DhBarterSaida)

Itens das notas de venda de insumos vinculadas ao contrato. PK composta IDBARTER + IDBARTERSAI. Todos os campos são somente leitura (preenchidos pela sincronização).

NUSAIDA / SEQITE — Inteiro (FK Nota). Nota de saída e sequência do item.

CODPROD / QTD — Inteiro/Decimal. Produto e quantidade.

VLR_TOTAL_ITEM — Decimal. Valor total do item.

SACAS_EQUIV — Decimal. Sacas equivalentes.

CODVEND / NUPEDIDO — Inteiro (FK). Vendedor e pedido de venda.

6.3 DH_BARTERENT — Entradas de Grãos (DhBarterEntrada)

Itens das notas de entrada de grãos vinculadas. PK composta IDBARTER + IDBARTERENT. Somente leitura.

NUENTRADA / SEQITE — Inteiro (FK Nota). Nota de entrada e sequência do item.

DTENTRADA / CODPROD — Data/Inteiro. Data de entrada e produto.

CODLOCAL / ARMAZENAGEM — Inteiro (FK). Local de estoque e contrato de armazenagem.

SACAS_ENTRADA / SACAS_ALOCADAS — Decimal. Sacas de entrada e alocadas ao contrato.

VLR_SACA / VLR_TOTAL_ALOCADO — Decimal. Valor da saca e valor total alocado.

6.4 VW_DH_BARTERCOMP — Compensações Financeiras (VwDhBarterComp)

View das compensações financeiras nativas vinculadas ao contrato. PK IDBARTER + IDBARTERCOMP; somente leitura.

DT_COMPENSACAO / NRO_COMPENSACAO — Data/Inteiro. Data e número da compensação.

FIN_RECEBER / FIN_PAGAR — Inteiro (FK Fin.). Título a receber (insumos) e a pagar (grãos).

VLR_COMPENSADO / MOEDA — Decimal/Inteiro. Valor compensado e moeda.

USUARIO — Inteiro (FK). Usuário.

6.5 Extensões em entidades padrão do Sankhya

CabecalhoNota (TGFCAB) — DH_IDBARTER (contrato vinculado à nota); DH_IDCONTRATOCALC (rótulo B{id} - G{contrato grão}).

Financeiro (TGFFIN) — DH_IDBARTER; DH_DTVENCBARTER (vencimento do contrato); DH_IDCONTRATOCALC (rótulo).

TipoOperacao (TGFTOP) — DH_VALVLRBARTER (Valida Vlr. Unitário Barter? S/N).

6.6 Componentes de servidor e regras de integridade

CalcularContratoServiceSP — Ação Recalcular: reconstrói entradas/saídas e agregados a partir das notas.

GerarPedidoInsumoServiceSP — Ação Gerar Pedido Insumo: valida dados e cria o pedido vinculado ao contrato.

BarterListener / DhBarterListener — Preenchem valor da saca e vencimento a partir do contrato de grãos e recalculam o acerto financeiro.

CabecalhoNotaListener — Valida o vínculo do contrato na nota e dispara a sincronização (venda/entrada); limpa vínculos ao alterar/excluir.

ItemNotaListener — Sem validação de valor unitário (a referência é tratada pelo valor da saca do contrato de grãos).

FinanceiroListener — Propaga o contrato Barter e o vencimento para os títulos financeiros.

BarterSincronizador — Motor de sincronização: calcula sacas, saldos e acerto, e mantém as abas e o financeiro consistentes.

6.7 Observações técnicas

As abas de Entradas e Saídas e os valores agregados do contrato são preenchidos automaticamente pelos eventos ao salvar notas com o contrato vinculado — não são digitados na tela.

O elo com o contrato de grãos (campo Número do Contrato de Grão → tabela TCSCON) é a fonte do valor da saca (VALNEGSC) e do vencimento (AD_DTVENC).

A compensação financeira é 100% nativa do Sankhya; o módulo apenas a exibe pela view de compensações.

A visão de negócio deste manual foi baseada no Documento de Requisitos do projeto (Gestão Barter 0.2); o documento do Google Drive não pôde ser incorporado automaticamente por exigir autenticação.