Para tener el historial comercial que han concretado los Comercios a lo largo de su relación con el cliente, se manejan sus Transacciones.
¿Qué es una transacción? Una Transacción en YOM representa un evento comercial asociado a un Comercio: puede corresponder a un pedido, una factura, una boleta, una nota de crédito o una nota de débito. Cada fila del archivo representa una línea de producto dentro de un documento.
Granulidad de una transacción
El grano de una transacción es una fila por combinación de documentCode + orderId + documentType + productId. Un mismo producto no puede repetirse dentro de una misma orden (orderId).
Sí permitido: un mismo producto en la misma factura (documentCode) pero en órdenes distintas (orderId distinto). Es el caso de una factura consolidada: cada orden se registra por separado y las cantidades se conservan.
No soportado: el mismo producto en dos o más líneas bajo el mismo orderId. En ese caso YOM conserva una sola línea por producto (la última procesada) y descarta las demás, perdiendo cantidad y venta.
Acción requerida: si en el origen un producto aparece en varias líneas de la misma orden (por ejemplo, picking o despacho parcial), deben consolidarse en una sola línea antes de enviar el archivo, sumando la quantity y dejando un único precio unitario.
Entidad → transaction
/integrations
/<customer_id>
/commerce
/product
/seller
/transaction
/20251228
20251228_180000_transaction.csv
...
| Campo | Tipo | Carácter | Descripción | Ejemplos | Validación |
|---|---|---|---|---|---|
orderId |
📝 Texto | 🟢 Requerido | Identificador del pedido en el sistema de origen. Puede repetirse en todas las líneas de producto que pertenecen al mismo pedido. | "TR12345" | not null |
productId |
📝 Texto | 🟢 Requerido | Identificador del producto incluido en la línea. | "PROD5678" | not null |
commerceId |
📝 Texto | 🟢 Requerido | Identificador del comercio asociado a la transacción. | "COM987" | not null |
customerId |
📝 Texto | ⚪ Opcional | Identificador adicional del cliente o comprador cuando el sistema de origen distingue este concepto del comercio. | "CLI456" | nullable |
sellerId |
📝 Texto | 🟢 Requerido | Identificador del vendedor asociado a la transacción. | "SEL987" | not null |
sellerRouteId |
📝 Texto | ⚪ Opcional | Identificador de la ruta del vendedor asociada a la transacción. | "RUTA01" | nullable |
date |
📅 Fecha | 🟢 Requerido | Fecha del pedido o documento, en formato ISO 8601. | "2018-10-22T00:00:00.000Z" | not null, ISO 8601 |
documentType |
📝 Texto | 🟢 Requerido | Tipo de documento asociado a la transacción. Los valores deben enviarse exactamente en minúsculas. | ||
"order" → pedido |
|||||
"invoice" → factura |
|||||
"bill" → boleta |
|||||
"credit note" → nota de crédito |
|||||
"debit note" → nota de débito |
"order" | ||||
| "invoice" | |||||
| "credit note" | |||||
| "debit note" | not null |
||||
documentCode |
📝 Texto | 🟡 Condicional | Código del documento comercial o tributario. Es requerido para facturas, boletas, notas de crédito y notas de débito. Para pedidos puede omitirse o coincidir con orderId. |
"F12345" | nullable para "order" |
not null para los demás tipos |
|||||
quantity |
#️⃣ Número | 🟢 Requerido | Cantidad de unidades del producto incluidas en la línea. Debe enviarse como valor absoluto positivo; documentType determina si la operación suma o revierte unidades. |
10 | > 0 |
netPricePerUnit |
#️⃣ Número flotante | 🟢 Requerido | Precio neto por unidad, antes de descuentos y sin impuestos. | 1000 | not null, ≥ 0 |
discountedNetPricePerUnit |
#️⃣ Número flotante | 🟢 Requerido | Precio neto por unidad después de aplicar el descuento y antes de impuestos. | 900 | not null, ≥ 0 |
taxPerUnit |
#️⃣ Número flotante | 🟢 Requerido | Monto del impuesto por unidad calculado sobre el precio neto sin descuento. | 190 | not null, ≥ 0 |
discountedTaxPerUnit |
#️⃣ Número flotante | 🟢 Requerido | Monto del impuesto por unidad calculado después de aplicar el descuento neto. | 171 | not null, ≥ 0 |
discountPerUnit |
#️⃣ Número flotante | 🟢 Requerido | Descuento neto aplicado por unidad, sin incluir la disminución del impuesto. | 100 | not null, ≥ 0 |
grossPricePerUnit |
#️⃣ Número flotante | 🟢 Requerido | Precio bruto por unidad, antes del descuento e incluyendo impuestos. | 1190 | not null, ≥ 0 |
discountedGrossPricePerUnit |
#️⃣ Número flotante | 🟢 Requerido | Precio bruto por unidad después de aplicar el descuento e incluyendo el impuesto correspondiente. | 1071 | not null, ≥ 0 |
currency |
📝 Texto | 🟢 Requerido | Código ISO 4217 de la moneda de la transacción, expresado en minúsculas. | "clp" | |
| "ars" | |||||
| "cop" | not null |
||||
origin |
📝 Texto | 🟢 Requerido | Origen funcional de la transacción definido por el cliente. | "carga inicial" | |
| "ventas_erp" | not null |
||||
sourceChannel |
📝 Texto | ⚪ Opcional | Canal en el que se originó la transacción. | "app movil" | |
| "ecommerce" | nullable |
||||
deliveryDate |
📅 Fecha | ⚪ Opcional | Fecha programada o efectiva de entrega, en formato ISO 8601. | "2018-10-23" | aaaa-mm-dd |
referenceCode |
📝 Texto | 🟡 Condicional | Código del documento de referencia para una nota de crédito o débito. Normalmente corresponde al código de la factura o documento original. | "REF123" | nullable para pedidos y facturas; requerido cuando corresponde una referencia |
couponCode |
📝 Texto | ⚪ Opcional | Código del cupón aplicado a la transacción. | "CUPON123" | nullable |
isDeleted |
🔘 Booleano | ⚪ Opcional | Indica si la línea fue eliminada en el sistema de origen. Cuando es true, la línea se excluye de la ingesta actual. Si no se informa, se considera que la línea no está eliminada. |
true | |
| false | nullable |
||||
dispatchPricePerUnit |
#️⃣ Número flotante | ⚪ Opcional | Costo o precio de despacho asignado a cada unidad de producto. | 0 | nullable, ≥ 0 |
orderId;internalOrderId;productId;commerceId;customerId;sellerId;sellerRouteId;date;documentType;documentCode;quantity;netPricePerUnit;discountedNetPricePerUnit;taxPerUnit;discountedTaxPerUnit;discountPerUnit;grossPricePerUnit;discountedGrossPricePerUnit;currency;origin;sourceChannel;deliveryDate;referenceCode;couponCode;isDeleted;dispatchPricePerUnit
"TR12345";"YOM12345";"PROD5678";"COM987";"";"SEL987";"RUTA01";"2018-10-22T00:00:00.000Z";"invoice";"F12345";10;1000;900;190;171;100;1190;1071;"clp";"ventas_erp";"ecommerce";"2018-10-23T00:00:00.000Z";"";"CUPON123";false;0
| Columna | Valor |
|---|---|
| orderId | TR12345 |
| internalOrderId | YOM12345 |
| productId | PROD5678 |
| commerceId | COM987 |
| customerId | |
| sellerId | SEL987 |
| sellerRouteId | RUTA01 |
| date | 2018-10-22T00:00:00.000Z |
| documentType | invoice |
| documentCode | F12345 |
| quantity | 10 |
| netPricePerUnit | 1000 |
| discountedNetPricePerUnit | 900 |
| taxPerUnit | 190 |
| discountedTaxPerUnit | 171 |
| discountPerUnit | 100 |
| grossPricePerUnit | 1190 |
| discountedGrossPricePerUnit | 1071 |
| currency | clp |
| origin | ventas_erp |
| sourceChannel | ecommerce |
| deliveryDate | 2018-10-23T00:00:00.000Z |
| referenceCode | |
| couponCode | CUPON123 |
| isDeleted | false |
| dispatchPricePerUnit | 0 |
Con esta estructura puedes gestionar y consultar la información de las transacciones y sus documentos comerciales en YOM de manera eficiente.
Pasos anteriores
<aside> <img src="/icons/arrow-left_gray.svg" alt="/icons/arrow-left_gray.svg" width="40px" />
</aside>
Las siguientes relaciones deben cumplirse en cada línea:
discountedNetPricePerUnit = netPricePerUnit - discountPerUnitgrossPricePerUnit = netPricePerUnit + taxPerUnitdiscountedGrossPricePerUnit = discountedNetPricePerUnit + discountedTaxPerUnitdiscountPerUnit representa exclusivamente el descuento neto.discountPerUnit.Cuando no existen descuentos:
discountPerUnit = 0discountedNetPricePerUnit = netPricePerUnitdiscountedTaxPerUnit = taxPerUnitdiscountedGrossPricePerUnit = grossPricePerUnitAlgunos campos opcionales son aceptados por el contrato, pero su persistencia y uso analítico dependen de lo configurado para cada cliente.