Unitats comptades, pes per peces i substitució per canvi d'unitat base

15 d'octubre de 2026 — Un producte mesurat en quilos, litres o metres ara es pot vendre en unitats comptades com paquets, caixes o peces, i un producte que ja té historial pot canviar d'unitat base substituint-lo per un de nou. Tot és additiu: cap camp existent canvia de significat.

Unitats comptades

Hi ha 22 codis d'unitat en total: 9 unitats de mesura i 13 unitats comptades.

base_unit només admet les 9 unitats de mesura; les unitats comptades són unitats comercials.

• Presentacions i ofertes de proveïdor. Una presentació fixa en una unitat comptada pot recolzar-se en una base mesurada si declara la seva equivalència (conversion_factor o nominal_base_quantity): «1 paquet = 0,5 kg». Una unitat de mesura ha de pertànyer a la mateixa família que la base. Una presentació o una oferta la unitat de la qual no es pot expressar sobre la unitat base del producte es rebutja amb 422 unit_not_expressible.
• Pes per peces. Una presentació de pes variable la unitat de la qual és una unitat comptada accepta a counted_quantity les peces que va demanar el client. La línia es continua cobrant, i l'estoc es continua descomptant, per quantity, el pes real en la unitat base; les peces són informatives.
• Documents. Les línies de factura, pressupost, proforma, albarà i factura recurrent porten counted_quantity i counted_unit, tots dos null quan la línia no té peces comptades. L'editor, el PDF, el tiquet i l'enllaç públic mostren «4 paquets = 2 kg» o «3 peces · 1,520 kg × 4,55 €/kg».
• FacturaE i UBL. FacturaE declara el UnitOfMeasure real de cada línia i UBL envia el seu unitCode UN/ECE real.

Substitució per canvi d'unitat base

La unitat base d'un producte amb historial (estoc, moviments, presentacions, ofertes de proveïdor o variants amb estoc) no s'edita al lloc. El producte ho indica ara a base_unit_change, i el canvi es fa substituint el producte per un de nou.

• Vista prèvia de la substitució per canvi d'unitat base calcula, sense escriure res, el pla i un impact_token que confirma aquest pla exacte. Envies la unitat base nova (target_base_unit, una de les 9 unitats de mesura), l'equivalence entre ambdues unitats, un base_price opcional i una decisió keep o retire per presentació.
• Substituir un producte canviant la seva unitat base l'executa i respon 201 amb el producte nou. És irreversible, així que Idempotency-Key és obligatòria. L'estoc, les presentacions que conserves, les variants, les ofertes de proveïdor, les entrades de tarifa i els components de pack passen al producte nou, convertits a la seva unitat. El producte anterior es desactiva, conserva tot el seu historial i no es pot reactivar mai. No consumeix quota del pla.
• Si la conversió perd precisió o no hi ha equivalència, cal confirmar base_price (422 base_unit_replacement_price_confirmation_required). Si el catàleg, les tarifes o els packs canvien després de la vista prèvia, la confirmació es rebutja amb 422 base_unit_replacement_preview_stale i es demana una vista prèvia nova.
• Els altres rebuigs de la substitució són 422 business_rule_violation amb subcodi product_already_replaced, base_unit_replacement_conversion_unavailable o base_unit_replacement_blocked_by_packs, i 422 parameter_invalid_value amb subcodi base_unit_replacement_same_unit (el destí ja és la unitat base del producte), base_unit_replacement_equivalence_invalid o base_unit_replacement_decision_invalid.
• L'equivalence és el nombre d'unitats de la base actual que equivalen a una unitat de la nova. És obligatòria entre una unitat de recompte i una de mesura, en qualsevol sentit; dins de la mateixa família de mesura es calcula sola, i entre dues famílies de mesura diferents no existeix.
• Un producte que participa en una substitució, com a producte anterior o com a nou, no es pot eliminar: Elimina un producte i Elimina diversos productes de forma massiva responen 422 amb subcodi product_in_base_unit_replacement, i a l'operació en bloc el producte figura a failed[] amb aquest motiu. Les tools MCP delete_product i bulk_delete_products apliquen la mateixa regla.
• Editar base_unit en un producte el base_unit_change.mode del qual és replacement respon 422 business_rule_violation amb subcodi product_base_unit_locked.

Camps, esdeveniments i MCP

• Producte. base_unit_change (mode i els blockers quantificats), replaces i replaced_by (id, name, base_unit, replaced_at, equivalence i stock_transferred). Es retornen en les lectures d'un sol producte i s'ometen als llistats.
• Esdeveniment. product.replaced es publica amb el producte nou com a objecte. Consulta Esdeveniments.
• Moviments d'estoc. Els motius base_unit_replacement_out i base_unit_replacement_in i l'origen base_unit_replacement registren el traspàs entre ambdós productes.
• Tarifes. El motiu de retirada product_replaced identifica les entrades del producte substituït.
• MCP. Dues tools noves, preview_product_base_unit_replacement i replace_product_base_unit, totes dues amb l'scope products:write; la segona és irreversible i accepta idempotency_key. Consulta el catàleg de tools.

Els components d'un pack no admeten peces: components.*.counted_quantity respon 422 si arriba amb valor, perquè les peces pertanyen a les línies dels documents de venda.

Les operacions que llegeixen o escriuen productes, presentacions, ofertes de proveïdor, tarifes i documents de venda conserven els seus scopes, i les seves respostes i cossos incorporen els camps i codis d'unitat descrits.