Dicionário de Campos Base — Tipos de Contrato

1. Propósito

Este documento consolida, por tipo base de contrato, os campos das camadas 1 (comuns) e 2 (específicos do tipo) que compõem o ContractFieldDictionary da plataforma (ver 4. Template de Contratos.md, seção 5). Também define quais campos retornam na listagem resumida de contratos (ver 3. Contratos.md).

Este dicionário é gerido pela plataforma (Nagro) e capturado como snapshot no momento da criação do template. Empresas configuram apenas a camada 3 (campos customizados) — não alteram o que está listado aqui.

2. Tipos de contrato suportados

Código	Nome	Marco regulatório
`CPR_PHYSICAL`	CPR Física	Lei 8.929/1994
`CPR_FINANCIAL`	CPR Financeira	Lei 8.929/1994 (com alterações Lei 10.200/2001 e Lei 13.986/2020)
`INVOICE`	Duplicata (Mercantil ou de Serviço)	Lei 5.474/1968 + Lei 13.775/2018 (forma escritural)
`CCB`	Cédula de Crédito Bancário	Lei 10.931/2004 (arts. 26 a 44)
`PROMISSORY_NOTE`	Nota Promissória	Decreto 57.663/1966 (Lei Uniforme de Genebra)
`PURCHASE_SALE_CONTRACT`	Contrato de Compra e Venda	Código Civil (arts. 481-532)
`OTHER`	Outro	Empresa define 100% dos campos

3. Campos comuns (camada 1) — aplicáveis a todos os tipos

A camada 1 é o conjunto de campos universais que todo contrato carrega, independente do tipo. A visibilidade de alguns campos varia conforme o tipo (ex.: interestRate é HIDDEN em CPR_PHYSICAL).

Campo	Tipo	Descrição
`code`	STRING	Código identificador do contrato (ex.: `CT-2024-001`).
`description`	STRING	Descrição comercial.
`totalAmount`	DECIMAL	Valor total da operação em BRL.
`currency`	ENUM	`BRL`, `USD`, `COMMODITY_LINKED`.
`startDate`	DATE	Data de início de vigência.
`endDate`	DATE	Data de fim de vigência.
`paymentPeriodicity`	ENUM	`MONTHLY`, `BIMONTHLY`, `QUARTERLY`, `SEMIANNUAL`, `ANNUAL`, `SINGLE`, `HARVEST`, `CUSTOM`.
`interestRate`	DECIMAL	Taxa de juros (visibilidade depende do tipo).
`interestRateType`	ENUM	`MONTHLY`, `ANNUAL`.
`interestCalculationMethod`	ENUM	`SIMPLE`, `COMPOUND`.
`correctionIndex`	ENUM	`IGPM`, `IPCA`, `CDI`, `SELIC`, `INPC`, `NONE`.
`correctionIndexSpread`	DECIMAL	Spread sobre o índice.
`finePercentage`	DECIMAL	Percentual de multa por atraso.
`dailyInterestPercentage`	DECIMAL	Juros de mora diários.
`daysToDefault`	INTEGER	Prazo em dias para inadimplência formal automática.
`typeDescription`	STRING	Descrição livre quando `type = OTHER` (obrigatório nesse caso).
`notes`	STRING	Observações livres.

4. Campos do tipo base (camada 2) — por tipo

4.1. CPR_PHYSICAL — CPR Física

Cédula de Produto Rural com obrigação de entrega física do produto agrícola. Regulada pela Lei 8.929/1994, arts. 1º a 4º. A CPR Física é título líquido, certo e exigível, transferível por endosso.

Campos da camada 1 com visibilidade ajustada para este tipo:

Campo	Visibilidade	Justificativa
`interestRate`, `interestRateType`, `interestCalculationMethod`	`HIDDEN`	CPR Física não comporta juros — obrigação é entrega de produto.
`currency`	`OPTIONAL` (default: `COMMODITY_LINKED`)	Valor referenciado em commodity, não dinheiro.
`paymentPeriodicity`	`OPTIONAL` (default: `HARVEST`)	Geralmente liquidação única na colheita.

Campos específicos (baseTypeFields):

Campo	Tipo	Obrigatório	Descrição
`crop`	ENUM	Sim	Cultura. Valores: `SOYBEAN`, `CORN`, `COTTON`, `COFFEE`, `SUGARCANE`, `WHEAT`, `RICE`, `OTHER`.
`harvestSeason`	STRING	Sim	Safra (ex.: `2024/2025`).
`expectedQuantity`	DECIMAL	Sim	Quantidade do produto a ser entregue.
`quantityUnit`	ENUM	Sim	Unidade. Valores: `TONS`, `BAGS_60KG`, `BAGS_50KG`, `ARROBAS`, `LITERS`, `OTHER`.
`productSpecification`	STRING	Sim	Especificação de qualidade do produto (ex.: "Tipo 1, exportação"). Exigido pela Lei 8.929/94, art. 3º, IV.
`deliveryLocation`	STRING	Sim	Local de entrega.
`deliveryDeadline`	DATE	Sim	Data limite de entrega.
`productPriceAtContract`	DECIMAL	Opcional	Preço unitário de referência na emissão.
`priceUnit`	ENUM	Opcional	Valores: `PER_TON`, `PER_BAG_60KG`, `PER_ARROBA`.
`registrationNumber`	STRING	Opcional (obrigatório para valores > R$ 50 mil desde 01/2023)	Número de registro em cartório ou entidade autorizada (B3, CERC).
`registryName`	STRING	Opcional	Nome do cartório/entidade registradora.
`farmName`	STRING	Opcional	Nome da fazenda/imóvel rural origem do produto.
`farmAddress`	STRING	Opcional	Endereço do imóvel rural.
`farmMatricula`	STRING	Opcional	Matrícula do imóvel no CRI.

4.2. CPR_FINANCIAL — CPR Financeira

Cédula de Produto Rural com liquidação financeira (não há entrega física do produto — paga-se o equivalente em dinheiro). Lei 8.929/1994 com inclusão da modalidade financeira pela Lei 10.200/2001. Atualizada pela Lei 13.986/2020 (Marco do Agro).

Campos da camada 1 com visibilidade ajustada:

Campo	Visibilidade	Justificativa
`interestRate`, `interestRateType`, `interestCalculationMethod`	`OPTIONAL`	Pode ter ou não juros, depende da operação.
`currency`	`OPTIONAL` (default: `BRL`)	Liquidação em moeda.
`correctionIndex`	`OPTIONAL`	Pode usar índice para corrigir o valor.

Campos específicos (baseTypeFields):

Campo	Tipo	Obrigatório	Descrição
`crop`	ENUM	Sim	Cultura subjacente à operação. Mesmos valores de CPR_PHYSICAL.
`harvestSeason`	STRING	Sim	Safra de referência.
`referenceQuantity`	DECIMAL	Sim	Quantidade de referência usada para o cálculo do valor financeiro.
`quantityUnit`	ENUM	Sim	Unidade da quantidade de referência.
`referencePrice`	DECIMAL	Sim	Preço unitário utilizado para cálculo.
`priceUnit`	ENUM	Sim	Unidade do preço.
`priceIndexOrSource`	STRING	Opcional	Índice ou fonte do preço (ex.: "CEPEA/ESALQ Soja Paranaguá", "BM&F").
`settlementFormula`	STRING	Opcional	Fórmula de liquidação (referenciada ao preço de mercado).
`settlementDate`	DATE	Sim	Data de liquidação financeira.
`registrationNumber`	STRING	Opcional (obrigatório para > R$ 50 mil)	Registro em entidade autorizada.
`registryName`	STRING	Opcional	B3, CERC ou cartório.

4.3. INVOICE — Duplicata

Título de crédito vinculado a uma fatura mercantil ou de prestação de serviço, regulado pela Lei 5.474/1968. A Lei 13.775/2018 admite a emissão sob forma escritural (eletrônica).

Campos da camada 1 com visibilidade ajustada:

Campo	Visibilidade	Justificativa
`interestRate`, `interestRateType`, `interestCalculationMethod`	`HIDDEN` ou `OPTIONAL`	Duplicata é título de venda mercantil — geralmente sem juros embutidos, mas pode ter encargos por atraso.
`currency`	`REQUIRED` (default: `BRL`)	Sempre em moeda nacional.
`paymentPeriodicity`	`OPTIONAL` (default: `SINGLE`)	Geralmente quitação única no vencimento.

Campos específicos (baseTypeFields):

Campo	Tipo	Obrigatório	Descrição
`invoiceNumber`	STRING	Sim	Número da duplicata. Deve corresponder ao número da fatura. Exigido pelo art. 2º, §1º, IV da Lei 5.474/68.
`invoiceSeries`	STRING	Opcional	Série da fatura/duplicata.
`invoiceDate`	DATE	Sim	Data de emissão da duplicata.
`invoiceTotalAmount`	DECIMAL	Sim	Importância a pagar — em algarismos (art. 2º, §1º, VI).
`merchandiseDescription`	STRING	Opcional	Discriminação das mercadorias ou descrição do serviço prestado.
`placeOfPayment`	STRING	Sim	Local de pagamento (art. 2º, §1º, V).
`cfopCode`	STRING	Opcional	Código fiscal de operação (CFOP) — usado em integrações fiscais.
`nfeKey`	STRING	Opcional	Chave da NF-e vinculada (44 dígitos). Quando aplicável (duplicata mercantil).
`acceptanceDate`	DATE	Opcional	Data do aceite pelo sacado, quando ocorre.
`registrationNumber`	STRING	Opcional	Número de registro escritural (Lei 13.775/2018) — entidades autorizadas pelo BCB (CIP, CERC, etc.).

4.4. CCB — Cédula de Crédito Bancário

Título de crédito emitido em favor de instituição financeira (ou equiparada), representando promessa de pagamento decorrente de operação de crédito. Lei 10.931/2004, arts. 26 a 44. É título líquido, certo e exigível com eficácia executiva.

Campos da camada 1 com visibilidade ajustada:

Campo	Visibilidade	Justificativa
`interestRate`, `interestRateType`, `interestCalculationMethod`	`REQUIRED`	Exigido pelo art. 28, II — critério de cálculo de encargos.
`currency`	`REQUIRED` (default: `BRL`)	Pagamento em dinheiro, certo e líquido.
`correctionIndex`	`OPTIONAL`	Exigido pelo art. 28, II quando houver atualização monetária.

Campos específicos (baseTypeFields):

Campo	Tipo	Obrigatório	Descrição
`ccbNumber`	STRING	Sim	Número/identificação da CCB.
`creditType`	ENUM	Sim	Espécie do crédito. Valores sugeridos: `WORKING_CAPITAL`, `INVESTMENT`, `RURAL_FINANCING`, `INFRASTRUCTURE`, `OTHER` (art. 28, I).
`bankIspb`	STRING	Sim	ISPB da instituição credora (8 dígitos).
`bankName`	STRING	Sim	Nome da instituição credora.
`bankAgency`	STRING	Opcional	Agência.
`bankAccount`	STRING	Opcional	Conta.
`cetPercentage`	DECIMAL	Sim	CET — Custo Efetivo Total da operação (exigência do BCB, Resolução 3.517/2007).
`placeOfPayment`	STRING	Sim	Praça de pagamento (art. 28, III).
`iofAmount`	DECIMAL	Opcional	Valor de IOF retido na emissão.
`chargesDetails`	STRING	Opcional	Detalhamento de comissões e despesas (exigência art. 28, II).
`guaranteesDescription`	STRING	Opcional	Descrição das garantias (geralmente em colaterais — ver `10. Colaterais.md`).
`disbursementDate`	DATE	Opcional	Data efetiva de liberação dos recursos.
`disbursementAmount`	DECIMAL	Opcional	Valor líquido desembolsado (após descontos de IOF e tarifas).

4.5. PROMISSORY_NOTE — Nota Promissória

Título de crédito que contém promessa pura e simples de pagamento de quantia determinada. Regida pelo Decreto 57.663/1966 (Lei Uniforme de Genebra sobre letras de câmbio e notas promissórias), arts. 75 a 78.

Campos da camada 1 com visibilidade ajustada:

Campo	Visibilidade	Justificativa
`currency`	`REQUIRED` (default: `BRL`)	Quantia determinada em moeda.
`paymentPeriodicity`	`OPTIONAL` (default: `SINGLE`)	Geralmente pagamento único na data de vencimento.

Campos específicos (baseTypeFields):

Campo	Tipo	Obrigatório	Descrição
`noteNumber`	STRING	Sim	Número de identificação da nota promissória.
`beneficiaryName`	STRING	Sim	Nome da pessoa a quem ou à ordem de quem deve ser paga (art. 75, V).
`beneficiaryTaxId`	STRING	Opcional	CPF/CNPJ do beneficiário.
`issuePlace`	STRING	Sim	Lugar onde a nota é emitida (art. 75, VI).
`placeOfPayment`	STRING	Sim	Lugar do pagamento (art. 75, IV).
`signaturePlace`	STRING	Opcional	Local da assinatura (quando diferente do issuePlace).
`acceptanceType`	ENUM	Opcional	`À_VISTA`, `DATA_CERTA`, `DIA_CERTO`.

4.6. PURCHASE_SALE_CONTRACT — Contrato de Compra e Venda

Contrato bilateral em que uma parte (vendedor) se obriga a transferir o domínio de coisa certa, e a outra (comprador) a pagar-lhe certo preço. Código Civil, arts. 481 a 532. Não é título de crédito propriamente — é instrumento contratual representando obrigação financeira futura.

Campos da camada 1 com visibilidade ajustada:

Campo	Visibilidade	Justificativa
`interestRate`, `interestRateType`, `interestCalculationMethod`	`OPTIONAL`	Pode ter juros ou financiamento embutido.
`currency`	`REQUIRED` (default: `BRL`)	Preço em moeda.
`paymentPeriodicity`	`OPTIONAL`	Varia conforme acordo.

Campos específicos (baseTypeFields):

Campo	Tipo	Obrigatório	Descrição
`productOrServiceDescription`	STRING	Sim	Descrição do objeto da venda.
`productCategory`	ENUM	Opcional	Categoria. Sugestão: `AGRICULTURAL_INPUTS`, `MACHINERY`, `LIVESTOCK`, `SERVICES`, `OTHER`.
`quantity`	DECIMAL	Opcional	Quantidade objeto da venda.
`quantityUnit`	STRING	Opcional	Unidade da quantidade.
`unitPrice`	DECIMAL	Opcional	Preço unitário.
`deliveryLocation`	STRING	Opcional	Local de entrega do produto/serviço.
`deliveryDate`	DATE	Opcional	Data prevista de entrega.
`propertyRetentionClause`	BOOLEAN	Opcional	Se há cláusula de reserva de domínio (art. 521 CC).
`warranties`	STRING	Opcional	Garantias contratuais oferecidas (não confundir com colaterais financeiros — ver `10. Colaterais.md`).

4.7. OTHER — Outro

Tipo flexível para instrumentos não contemplados pelos tipos pré-definidos. Toda a especificidade vem da camada 3 (campos customizados configurados pela empresa).

Campos da camada 1 com visibilidade ajustada:

Todos OPTIONAL ou REQUIRED conforme padrão, sem ajustes específicos.

Campo da camada 1	Visibilidade adicional para OTHER
`typeDescription`	`REQUIRED` — empresa deve informar o nome/tipo do instrumento.

Campos específicos (baseTypeFields):

[] (vazio). Toda a estrutura vem da camada 3.

5. Campos resumidos por tipo (para listagem)

Quando o endpoint GET /portfolios/:portfolioId/contracts retorna a listagem, o typeSpecificFields traz apenas campos identificadores naturais do tipo (não o objeto completo). Esses campos devem permitir ao usuário reconhecer o contrato sem abrir o detalhe.

Tipo base	Campos resumidos retornados
`CPR_PHYSICAL`	`crop`, `harvestSeason`, `expectedQuantity`, `quantityUnit`
`CPR_FINANCIAL`	`crop`, `harvestSeason`, `settlementDate`
`INVOICE`	`invoiceNumber`, `invoiceDate`
`CCB`	`ccbNumber`, `creditType`, `bankName`
`PROMISSORY_NOTE`	`noteNumber`, `beneficiaryName`
`PURCHASE_SALE_CONTRACT`	`productOrServiceDescription`, `productCategory`
`OTHER`	(nenhum — só `typeDescription` da camada 1)

Critério de seleção:

Campos que respondem "qual contrato é este?" (identificadores).

Campos de uso frequente em filtros e relatórios.

Limitado a 2-4 campos por tipo para manter o payload enxuto.

Excluídos campos longos (descrições, garantias, observações) e campos sensíveis (dados bancários, valores de IOF).

6. Marco regulatório consolidado

Tipo	Referência principal	Complementares
`CPR_PHYSICAL` / `CPR_FINANCIAL`	Lei 8.929/1994	Lei 10.200/2001 (CPR Financeira), Lei 13.986/2020 (Marco do Agro), Decreto 10.828/2021 (registro). Obrigatório registro em entidade autorizada para CPRs acima de R$ 50 mil desde 01/01/2023.
`INVOICE`	Lei 5.474/1968	Lei 13.775/2018 — duplicata escritural; Resoluções do BCB sobre escrituração eletrônica.
`CCB`	Lei 10.931/2004, arts. 26-44	Resolução BCB 3.517/2007 (CET); Súmula 541 STJ (juros).
`PROMISSORY_NOTE`	Decreto 57.663/1966 (Lei Uniforme de Genebra), arts. 75-78	Código Civil (subsidiário).
`PURCHASE_SALE_CONTRACT`	Código Civil, arts. 481-532	Lei 8.078/1990 (CDC) quando aplicável a relações de consumo.
`OTHER`	—	A empresa documenta no `typeDescription` o instrumento usado e sua base legal.

Dicionário de campos base (Necessário validar)

Dicionário de Campos Base — Tipos de Contrato#

1. Propósito#

2. Tipos de contrato suportados#

3. Campos comuns (camada 1) — aplicáveis a todos os tipos#

4. Campos do tipo base (camada 2) — por tipo#

4.1. CPR_PHYSICAL — CPR Física#

4.2. CPR_FINANCIAL — CPR Financeira#

4.3. INVOICE — Duplicata#

4.4. CCB — Cédula de Crédito Bancário#

4.5. PROMISSORY_NOTE — Nota Promissória#

4.6. PURCHASE_SALE_CONTRACT — Contrato de Compra e Venda#

4.7. OTHER — Outro#

5. Campos resumidos por tipo (para listagem)#

6. Marco regulatório consolidado#

Dicionário de Campos Base — Tipos de Contrato

1. Propósito

2. Tipos de contrato suportados

3. Campos comuns (camada 1) — aplicáveis a todos os tipos

4. Campos do tipo base (camada 2) — por tipo

4.1. CPR_PHYSICAL — CPR Física

4.2. CPR_FINANCIAL — CPR Financeira

4.3. INVOICE — Duplicata

4.4. CCB — Cédula de Crédito Bancário

4.5. PROMISSORY_NOTE — Nota Promissória

4.6. PURCHASE_SALE_CONTRACT — Contrato de Compra e Venda

4.7. OTHER — Outro

5. Campos resumidos por tipo (para listagem)

6. Marco regulatório consolidado