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.

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. ItemSupplier.purchaseNum / purchaseDen     item × fornecedor   ← vence
2. ItemUomConversion.num / den               item
3. StandardConversion (só intraclasse)       global
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

• num e den 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.

Casas decimais

Onde arredondar

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

Quatro casas quebram a partir de 200 unidades: o erro máximo de arredondamento é 5×10⁻⁵, e a divergência é qty × 5×10⁻⁵. Com 10 casas o mesmo limite só seria atingido acima de duzentos milhões de unidades — é exatamente por isso que a NF-e dá 10 casas ao vUnCom.

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(qtyInPriceUom ÷ priceQty × priceAmount, 2). 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.

A unidade de compra é do fornecedor, não do item. O fornecedor A vende em caixa de 12; o B, em caixa de 24; o C, em milheiro. É o mesmo item.

Quando o fornecedor muda a embalagem

Cenário: a caixa de luva da ACME passa de 12 para 10 sem aviso. Chega nota de "7 CX" que na verdade são 70 UN, não 84.

O que não funciona: editar o registro para num = 10. Isso reescreve retroativamente todos os pedidos históricos — um pedido de 7 CX do ano passado passa a valer 70 UN, o estoque histórico fica errado e o custo médio é recalculado sobre uma mentira.

A alternativa mais conservadora — e a que a legislação do SPED já exige para efeito fiscal — é criar um novo código de unidade (CX10) em vez de mudar o fator de CX. Vale considerar como comportamento padrão, não só como opção.

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

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 o ItemSupplier 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.