Unidade de Medida

Convenção de nomes. O documento é em português; os identificadores são em inglês — entidades, atributos, valores de enum, rotas, permissões e códigos de erro. A exceção são os dados de negócio brasileiros, que ficam como são no mundo real: identificadores fiscais (cnpj, cpf, primaryCnae), nomes de regime tributário (SimplesNacional, LucroReal), siglas de unidade (UN, CX, KG), tipos de certidão e os exemplos de taxonomia — esses são conteúdo, não código.

Lista fechada. O tenant escolhe a classe ao criar uma unidade própria, mas não cria classe nova — porque a classe é o que autoriza ou proíbe uma conversão.

Cerca de 40 unidades globais, mapeadas manualmente para códigos verificados como ativos na Rec 20 (revisão 17) e na Rec 21 para embalagens. Os 1.755 códigos ativos entram numa tabela de referência de leitura — não se expõem 1.755 opções ao comprador.

As dez unidades com "por item" na última coluna são as de embalagem — KIT, JG, CX, PT, FD, SC, RL — mais as que dependem de convenção (RS) ou de contrato (MES, ANO). As de embalagem nascem com isPackaging verdadeiro e sem fator canônico: a semente não inventa um, e o cadastro não aceita um (RN-UOM-19). Os mapeamentos menos óbvios e mais úteis: LS (lump sum) cobre exatamente "verba", E48 cobre "serviço", e ACT, E51, LH e 3C cobrem a família de serviço sem inventar código. Marcar unece20Code como nulo é legítimo e precisa ser suportado.

Hierarquia com fallback explícito

1. ItemSupplierOffer.numerator / denominator      item × fornecedor   ← vence
2. ItemUomConversion.numerator / denominator item
3. StandardConversion (só intraclasse, e só  global
   entre unidades com fator canônico)
4. → erro explícito. Nunca fator implícito 1:1.

O nível 4 é o mais importante do desenho inteiro. Nenhum sistema deve assumir fator 1 quando não encontra conversão — é assim que nasce o pedido de 84 caixas para quem queria 84 unidades.

Por que inteiros e não decimal

Um fator de conversão é uma razão, não uma medida, e razões de embalagem quase sempre têm denominador pequeno: 6, 10, 12, 24, 100, 1000.

O caso que dói de verdade é o de fatores irracionais aproximados. A documentação da Oracle traz pound → gram = 454; o valor exato é 453,59237, um erro relativo de 0,09%.

20 toneladas compradas em libras          = 44.092 lb
convertido com fator 454                  = 20.017.768 g = 20.017,77 kg
erro                                      = +17,77 kg
a R$ 8,50/kg                              = R$ 151,05 de divergência pedido × nota

com num/den = 45359237 / 100000           → erro zero

Note que esse par não caberia nos campos de conversão da SAP, limitados a 5 dígitos. Dimensione os inteiros como bigint, não int.

Regras de implementação

• numerator e denominator são bigint, ambos maiores que zero, normalizados por MDC na gravação.
• Aritmética em decimal exato, nunca em ponto flutuante.
• Ordem obrigatória: qty × num ÷ den — multiplicar antes de dividir. Inverter para qty × (num ÷ den) reintroduz exatamente o erro que se acabou de eliminar.
• Conversão entre classes diferentes existe apenas por item e nunca é herdada da conversão padrão.
• ItemUomConversion é append-only com vigência. Editar o fator de uma conversão em uso é proibido — é literalmente a regra do registro 0220 do SPED, que exige criar um novo código de unidade quando a embalagem muda de conteúdo, em vez de alterar o fator do código existente.

Validar a precisão da quantidade informada contra a unidade; qualquer ajuste deve ser apresentado antes da confirmação. Para planejamento de unidade indivisível, arredondar a sugestão para cima e mostrar o acréscimo, mínimo e múltiplo comercial. Nunca alterar silenciosamente quantidade recebida ou evidência da nota.

Dinheiro é calculado da quantidade original e fatores, sem usar a quantidade base já arredondada. Total do documento soma linhas; rateio fecha na moeda original e o total funcional soma fatias convertidas, conforme Moeda. Exportação fiscal pode exigir precisão distinta: o adaptador conserva valores originais e registra a transformação exigida pelo leiaute.

O erro que produz divergência contra a nota é derivar preço unitário por divisão e depois multiplicar.

No exemplo, preço unitário reduzido a quatro casas gera R$ 259,00 após arredondar 84 × 3,0833 = 258,9972; com duas casas, gera R$ 258,72. A divergência depende da quantidade e do ponto de arredondamento. O contrato evita acumular aproximações preservando o preço acordado.

As três regras

1. Guarde o preço na unidade em que foi acordado, com a unidade junto: priceAmount + priceUomId + priceQty. Não normalize preço para a unidade base do item.
2. Calcule o total na unidade de precificação: lineTotal = ROUND(orderedQty × convNum × priceConvNum × priceAmount ÷ (convDen × priceConvDen × priceQty), Currency.minorUnits). Converta a quantidade, nunca o preço.
3. priceQty resolve item barato. Uma lâmpada a R$ 0,36263 cadastra-se como priceQty = 1000 e priceAmount = 362,63. Um parafuso a R$ 0,0037 vira priceQty = 1000, priceAmount = 3,70. É o PEINH da SAP e o price quantity do D365, e elimina inteiramente a questão de casas decimais de preço.

Item de tipo com classe Service aceita apenas unidades dessa classe e não admite nenhuma linha de conversão. É validação de domínio, não de tela.

O nível mais específico de conversão é a versão de ItemSupplierOffer selecionada; depois a conversão do item e, por último, o fator global intraclasse. Embalagem sem fator canônico não usa conversão global implícita. ItemSupplier continua sendo a relação; preço referencia a oferta.

A oferta contém purchaseUomId, numerator/denominator, código comercial, supplierUomLabel, MOQ, múltiplo, prazo e tolerâncias. Reajustar preço não altera fator; mudar embalagem ou condição relevante cria revisão de oferta. A caixa de 12 e a caixa de 24 podem coexistir para o mesmo fornecedor e item, com identidades distintas.

Ao receber 70 UN contra 7 CX de 12, registrar a contagem real e divergência de −14 UN; não reescrever o pedido para 7 CX de 10. Confirmar mudança de embalagem permite cadastrar a apresentação CX10 e revisar pedidos ainda abertos pelo processo de alteração. O recebimento ocorrido permanece registrado com pendência.

O que toda linha de documento carrega

orderedQty       numeric(19,6)   na unidade escolhida      →  7
orderedUomId                                               →  CX
orderedQtyBase   numeric(19,6)   na unidade base do item   →  84
baseUomId                                                  →  UN
convNum, convDen bigint          SNAPSHOT do fator          →  12, 1
priceAmount      numeric(19,10)                             →  37,0000000000
priceUomId                                                  →  CX
priceQty         numeric(19,6)                              →  1
priceConvNum,                    SNAPSHOT do fator          →  1, 12
priceConvDen     bigint          base → unidade de preço

convNum/convDen converte pedido → base; priceConvNum/priceConvDen converte base → preço. No exemplo, 7 CX × 12/1 × 1/12 × R$ 37 = R$ 259. Se o preço for por UN, só o segundo fator será 1/1. Ambos os fatores são congelados na linha.

O saldo em aberto da linha é calculado em unidade base, nunca na unidade do pedido — só assim é possível representar "sobraram 4 UN de uma linha de 7 CX".

Conferência a três (pedido × recebimento × nota)

Os três lados comparam na unidade base, usando o snapshot da linha e não o cadastro atual. A tolerância precisa ser percentual e absoluta ao mesmo tempo, passando se qualquer uma acomodar — o inverso do default de alguns ERPs, e é deliberado: divergências de arredondamento são absolutas e pequenas, divergências de preço são percentuais e grandes. Um piso absoluto de poucos centavos por linha elimina quase todo o ruído sem afrouxar controle real. E quando a nota vem em unidade que a versão de ItemSupplierOffer não conhece, não converta por classe genérica: levante exceção e peça o fator ao comprador — é exatamente o momento em que a embalagem mudou e alguém precisa saber.

O erro clássico é comparar preço por unidade cotada.

Sem normalizar, A parece o mais barato — R$ 37 é menos que R$ 68. Normalizado, B ganha e C é o segundo. Nenhum dos dois seria escolhido por leitura ingênua.

Avaliar tolerância na unidade de compra ou na unidade base dá o mesmo resultado quando a conversão é linear — o que não é o caso quando há arredondamento no meio.

• Avalie sempre na unidade base, com quantidades não arredondadas. É o único ponto de comparação estável entre requisição, pedido e recebimento.
• Não arredonde o limite. Compare receivedQtyBase ≤ orderedQtyBase × (1 + tol) diretamente em decimal.
• Exponha o limite também na unidade de compra, marcando quando ele cai entre dois múltiplos indivisíveis: "+10% de 7 CX = 7,7 CX — a próxima caixa inteira excede a tolerância".
• Tolerância de entrega a menor e "recebimento concluído" são coisas diferentes: a primeira aceita fechar a linha com menos; a segunda encerra o saldo em aberto e ainda assim admite recebimento dentro da tolerância a maior.

Desativar unidade em uso

A mensagem de erro precisa nomear os documentos, não dizer "unidade em uso". A diferença entre um sistema usável e um irritante costuma ser essa lista.

Matriz de imutabilidade

O princípio geral, que vale registrar como decisão de arquitetura: campos que alteram o significado numérico de dados já gravados são imutáveis; campos que alteram apresentação são editáveis. Toda a matriz acima decorre disso.

As conversões por item vivem nos endpoints do catálogo (PUT /catalog/items/{id}/uom-conversions) e as do fornecedor em PUT /catalog/items/{id}/suppliers/{supplierItemId} — estão especificadas nos respectivos documentos.