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.

39 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 sete unidades com "por item" na última coluna são as de embalagem — KIT, JG, CX, PT, FD, SC, RL. As três de calendário sem conversão global — DIA, MES, ANO — dependem de contrato e também só convertem por item. A resma (RS) tem fator canônico de 500 folhas por convenção de mercado. 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. ItemSupplierUom.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
44.092 lb pelo fator exato                = 19.999,79 kg
erro                                      = +17,97 kg
a R$ 8,50/kg                              = R$ 152,77 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.
• Fator usado nunca é reescrito (RN-UOM-09): o ItemUomConversion versiona com vigência e a ItemSupplierUom troca de linha; registro nunca usado corrige-se no lugar.
• SPED. O registro 0220 da EFD não aceita o mesmo código de unidade com dois fatores para o mesmo item: quem declara precisa de código distinto quando o fator muda. O Nexio não emite a EFD. A integração entrega ao ERP, por linha de documento, o código da unidade, o fator congelado e a linha de embalagem (itemSupplierUomId), e sinaliza quando o mesmo código já teve outro fator para o item; o código declarado no 0190 e no 0220 é do ERP. Cadastrar código distinto no Nexio (CX10) é escolha do tenant, nunca exigência.

Casas decimais

Onde arredondar

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

Com 84 UN as quatro casas ainda acertam o total, mas é coincidência de arredondamento: com 13 caixas o total derivado já diverge em um centavo. No pior caso, quatro casas passam da tolerância da SEFAZ acima 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(orderedQty × convNum × priceConvNum × priceAmount ÷ (convDen × priceConvDen × priceQty), minorUnits) — todos os fatores multiplicados antes da única divisão, em decimal exato, e um só arredondamento no fim. No exemplo: 7 × 12 × 1 × 37,00 ÷ (1 × 12 × 1) = 259,00. 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.

A regra lê a classe da unidade base do item, não o tipo: item cuja base é da classe Service aceita apenas unidades dessa classe e não admite nenhuma linha de conversão; item de serviço com base em HR ou M2 converte dentro da classe normalmente. É 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 e em fardo de 240; o C, em milheiro. É o mesmo item. E um mesmo fornecedor vende em mais de uma unidade — por isso a unidade de compra é uma filha da relação, ItemSupplierUom, com N linhas por relação.

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.

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
itemSupplierUomId                SNAPSHOT da linha          →  (id da CX de 12)
convNum, convDen bigint          SNAPSHOT do fator          →  12, 1
priceAmount      numeric(21,10)                             →  37,0000000000
priceUomId                                                  →  CX
priceQty         numeric(19,6)                              →  1
priceConvNum,                    SNAPSHOT do fator          →  1, 12
priceConvDen     bigint          base → unidade de preço

Por que dois pares. convNum/convDen é o fator da unidade pedida para a base; ele não serve quando o preço é cobrado em outra unidade — ItemSupplierUom.uomId = SC com priceUom = TN, que esta especificação trata como caso de primeira classe. Sem o segundo par, calcular qtyInPriceUom obrigava a resolver a conversão no cadastro, no momento do cálculo, e aí uma conversão nova, ou uma linha nova de unidade de compra, mudava o total de uma linha antiga — a divergência de centavos que produz as rejeições 629 e 630. O par vem congelado da versão de preço (RN-ITM-38). Quando a unidade de preço é a base, ele é 1/1; quando é a própria unidade pedida, é o inverso de convNum/convDen — e grava assim mesmo: snapshot não tem exceção. Ver RN-ITM-29.

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 de preço e o piso absoluto do three-way match são da spec da Nota; esta página garante a base comum da comparação — unidade base e snapshot da linha — e a resolução da unidade da nota. A unidade da nota é texto do emitente (uCom, e uTrib no grupo tributário) e resolve em dois passos, nunca por semelhança nem por classe genérica: código exato de unidade do Nexio, depois apelido da relação (ItemSupplierUomAlias, RN-ITM-35). O apelido diz qual unidade é; o fator vem do snapshot da linha do pedido quando a unidade é a pedida, e da hierarquia de conversão (RN-UOM-06) quando não é — nunca do apelido. Texto que não resolve, ou unidade resolvida sem fator, levanta exceção de conferência e pede ao comprador o apelido ou a linha de unidade de compra — é 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, D parece o mais barato — R$ 3,05 é o menor número da coluna — e, entre as caixas, A parece mais barata que B, porque R$ 37 é menos que R$ 68. Normalizado, B ganha (R$ 2,83), C é o segundo (R$ 2,90), D o terceiro (R$ 3,05) e A o último (R$ 3,08). Os dois primeiros seriam os dois descartados 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.

O objeto receiptTolerance

Um objeto só, com o mesmo formato nos três níveis em que pode aparecer. Esta página é a dona: o Cadastro de Fornecedor e o Cadastro de Item citam daqui, não repetem.

Data adiantada é parâmetro; data atrasada é medida. Atraso nunca impede receber — recusar mercadoria que chegou tarde não desfaz o atraso, só cria um problema novo —, então lateDays existe para dizer o que conta como on time no OTIF, e nada mais. Antecipação é o caso em que recusar faz sentido para parte dos tenants e não faz para a maioria, e por isso é o único que tem política: o padrão recebe, e quem quiser travar liga o Block no nível que quiser.

Três níveis, resolvidos campo a campo

A precedência é estabelecimento do fornecedor no documento → ItemSupplier (a relação) → linha do pedido, e a mais específica vence. A resolução é campo a campo, não objeto a objeto: cada campo é lido no nível mais específico em que estiver preenchido, e campo nulo herda do nível acima. 0 é valor, não ausência — overTolerancePct = 0 na linha significa "esta linha é exata" e não é sobrescrito por nada.

Com objeto a objeto, o 10% da relação apagaria o underTolerancePct do estabelecimento e uma entrega de 80 das 84 unidades seria recusada por um campo que ninguém decidiu. É a mesma base de dados dando dois resultados opostos, e é por isso que a regra está escrita (RN-UOM-20).

Quando nenhum nível preenche o campo, o sistema não inventa faixa: overTolerancePct = 0, underTolerancePct = 0, earlyDays = 0, lateDays = 0 e earlyReceiptPolicy = Warn. Ou seja, quantidade exata, e qualquer dia fora da data prometida conta no OTIF — que é a definição do indicador, não uma punição.

Avaliação em unidade base

• 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}/uoms — estão especificadas nos respectivos documentos.