Para ter o histórico comercial que os Comércios concretizaram ao longo de seu relacionamento com o cliente, são gerenciadas suas Transações.
O que é uma transação? Uma Transação na YOM representa um evento comercial associado a um Comércio: pode corresponder a um pedido, uma fatura, um recibo, uma nota de crédito ou uma nota de débito. Cada linha do arquivo representa uma linha de produto dentro de um documento.
Granularidade de uma transação
O grão de uma transação é uma linha por combinação de documentCode + orderId + documentType + productId. Um mesmo produto não pode se repetir dentro de um mesmo pedido (orderId).
Sim, permitido: um mesmo produto na mesma fatura (documentCode) mas em pedidos distintos (orderId diferente). É o caso de uma fatura consolidada: cada pedido é registrado separadamente e as quantidades são preservadas.
Não suportado: o mesmo produto em duas ou mais linhas sob o mesmo orderId. Nesse caso a YOM mantém apenas uma linha por produto (a última processada) e descarta as demais, perdendo quantidade e venda.
Ação necessária: se na origem um produto aparece em várias linhas do mesmo pedido (por exemplo, picking ou entrega parcial), elas devem ser consolidadas em uma única linha antes de enviar o arquivo, somando a quantity e deixando um único preço unitário.
O endpoint de Transações permite à YOM acessar informações detalhadas sobre cada pedido concluído.
GET /api/transactions
ARQUIVO <fecha>_<hora>_transaction.csv
O endpoint deve suportar filtro sobre o campo date, data do pedido ou fatura.
date_from → Data e hora a partir da qual se deseja obter os registros criados.
date_to → Data e hora até a qual se deseja obter os registros criados.
GET /api/transactions?date_from=2024-01-01T00:00:00Z&date_to=2024-12-31T23:59:59Z
| Campo | Tipo | Obrigatoriedade | Descrição | Exemplos |
|---|---|---|---|---|
orderId |
📝 Texto | 🟢 Obrigatório | Identificador único do pedido (independente do tipo de documento). | "TR12345" |
internalOrderId |
📝 Texto | ⚪ Opcional | Identificador do pedido feito na YOM. (O que enviamos na injeção para o ERP) | "YOM12345" |
productId |
📝 Texto | 🟢 Obrigatório | Identificador externo do produto | "PROD5678" |
commerceId |
📝 Texto | 🟢 Obrigatório | Identificador externo do comércio | "COM987" |
sellerId |
📝 Texto | 🟢 Obrigatório | Identificador externo do vendedor | "SEL987" |
sellerRouteId |
📝 Texto | ⚪ Opcional | Identificador externo da rota do vendedor | "ROUSEL987" |
date |
📅 Data | 🟢 Obrigatório | Data do pedido ou fatura. A data deve estar no formato ISO 8601. | "2018-10-22T00:00:00.000Z" |
documentType |
📝 Texto | 🟢 Obrigatório | Tipo de documento. | |
"order" → pedido |
||||
"invoice" → fatura |
||||
"bill" → recibo |
||||
"credit note" → nota de crédito |
||||
”debit note” → nota de débito |
T**odos os valores devem ser valor absoluto (positivo)** | "order"
"invoice"
"credit note"
"debit note" |
| documentCode | 📝 Texto | ⚪ Opcional | Código do documento; caso seja um pedido, o orderId se repete neste campo. | "12345" |
| quantity | #️⃣ Número | 🟢 Obrigatório | Quantidade de unidades pedidas do produto. | 10 |
| netPricePerUnit | #️⃣ Número flutuante | 🟢 Obrigatório | Preço unitário sem desconto e sem imposto do Produto. | 900 |
| discountedNetPricePerUnit | #️⃣ Número flutuante | 🟢 Obrigatório | Preço sem imposto e com desconto do produto | 850 |
| taxPerUnit | #️⃣ Número flutuante | 🟢 Obrigatório | Valor do imposto aplicado a cada unidade do Produto. | 190 |
| discountedTaxPerUnit | #️⃣ Número flutuante | ⚪ Opcional | Valor do imposto com desconto aplicado a cada unidade do Produto. | 170 |
| discountPerUnit | #️⃣ Número flutuante | 🟢 Obrigatório | Desconto unitário sem imposto aplicado ao Produto. | 50 |
| grossPricePerUnit | #️⃣ Número flutuante | ⚪ Opcional | Preço com imposto e sem desconto do produto | 1100 |
| discountedGrossPricePerUnit | #️⃣ Número flutuante | ⚪ Opcional | Preço com imposto e com desconto do produto | 950 |
| currency | 📝 Texto | 🟢 Obrigatório | Moeda em que a venda é realizada.
"clp" | "clp" |
| origin | 📝 Texto | 🟢 Obrigatório | Origem da Transação. Esta é uma definição própria do cliente | "carga inicial",
”ventas_yom” |
| sourceChannel | 📝 Texto | 🟢 Obrigatório | Canal de venda contato | "app movil”,
”ecommerce |
| deliveryDate | 📅 Data | ⚪ Opcional | Data em que o pedido foi entregue.
A data deve estar no formato ISO 8601. | "2018-10-22T00:00:00.000Z" |
| referenceCode | 📝 Texto | ⚪ Opcional | Código do documento de referência caso documentType seja "credit note" ou ”debit note”. Normalmente o código faz referência a uma “invoice”. | "REF123" |
| couponCode | 📝 Texto | ⚪ Opcional | Código de cupom | "CUPON123" |
| isDeleted | 🔘 Bool | ⚪ Opcional | A Transação foi excluída? | true |
A resposta do endpoint de Transações devolve um JSON que contém as informações detalhadas de cada pedido registrado no cliente (são os pedidos da YOM mais os pedidos que o cliente pode criar a partir de algum sistema próprio), incluindo dados do cliente, produtos, preços e mais.
{
"orderId": "TR12345",
"internalOrderId": "YOM12345",
"productId": "PROD5678",
"commerceId": "COM987",
"customerId": "CUS987",
"sellerId": "SEL987",
"sellerRouteId": "ROUSEL987",
"date": "2018-10-22T00:00:00.000Z",
"documentType": "order",
"documentCode": "12345",
"quantity": 10,
"netPricePerUnit": 900,
"discountedNetPricePerUnit": 850,
"taxPerUnit": 190,
"discountedTaxPerUnit": 170,
"discountPerUnit": 50,
"grossPricePerUnit": 1100,
"discountedGrossPricePerUnit": 950,
"currency": "clp",
"origin": "carga inicial",
"sourceChannel": "app movil",
"deliveryDate": "2018-10-22T00:00:00.000Z",
"referenceCode": "REF123",
"couponCode": "CUPON123",
"isDeleted": true,
"dispatchPricePerUnit": 1500
}