Developer Center
Pesquisar K

Appearance

Sale vs SaleGroup: Diferenças e Como Funcionam ​

Introdução ​

Ao integrar a plataforma de pagamentos da Layers, você encontrará dois conceitos fundamentais: Sale e SaleGroup. Entender a diferença entre eles é essencial para implementar corretamente sua integração.

  • Sale: Representa uma venda individual com todos os seus detalhes (cliente, itens, pagamento, envio)
  • SaleGroup: Representa um agrupamento de múltiplas vendas em uma única entidade

Diferenças Principais ​

AspectoSaleSaleGroup
PropósitoRepresenta apenas uma vendaAgrupador de múltiplas vendas
Identificaçãocode e token únicocode e token único
PagamentoStatus individual do pagamento dessa vendaStatus agregado do grupo de vendas
MarketplaceSuporta marketplace individualVinculada a um marketplace específico
IndependênciaPode existir sem SaleGroupNão existe sem ao menos 1 Sale
RastreamentoURL de rastreamento individualURL única de rastreamento para todas as vendas
Refund/CancelamentoIndividualAfeta múltiplas vendas

Estrutura de Dados ​

Sale (Venda Individual) ​

Veja os campos principais de uma venda:

typescript
{
  // Identificação
  code: "LP1-LK3JC-FHM9F",           // Código único da venda
  token: "uuid-v4",               // Token público para rastreamento
  saleGroupId: "ObjectId",        // Referência para o grupo (opcional)
  saleGroupCode: "LM-LK3JC-FHMCC", // Código do grupo (se existir)

  // Cliente
  customer: {
    name: "João Silva",
    email: "joao@example.com",
    phone: "+55 11 99999-9999",
    birth: "1990-05-15",
    address: { /* endereço completo */ },
    document: { kind: "cpf", value: "12345678900" }
  },

  // Produtos
  items: [
    {
      quantity: 2,
      name: "Produto A",
      subtotal: { amount: 10000 }, // em centavos
      // ... outros campos
    }
  ],

  // Pagamento
  payment: {
    status: "open",                // open, pending, paid, refunded, etc
    method: {
      method: "credit_card",       // credit_card, pix, bank_slip, etc
      installments: 3,             // número de parcelas
      // ... dados do método
    }
  },

  // Envio
  shipping: {
    required: true,
    address: { /* endereço de envio */ },
    method: { /* método de envio */ }
  },

  // Totalizações
  owned: {
    total: { amount: 30000 }       // Total incluindo tudo
  },

  // Tipo de venda
  kind: "order",                   // order, recurrence, subscription, gift, voucher

  // Metadata
  createdAt: "2024-01-15T10:30:00Z",
  updatedAt: "2024-01-15T10:30:00Z"
}

Características principais:

  • Contém todos os detalhes de uma venda
  • Suporta múltiplos tipos (order, recurrence, subscription, gift, voucher)
  • Possui todos os dados do cliente inline
  • Cada Sale gera múltiplas parcelas (payables)
  • Pode existir independentemente ou ser parte de um SaleGroup

SaleGroup (Grupo de Vendas) ​

Um SaleGroup é um contenedor para múltiplas vendas relacionadas:

typescript
{
  // Identificação
  code: "LM-LK3JC-FHMCC",           // Código único do grupo
  token: "uuid-v4",                // Token público para rastreamento

  // Marketplace
  marketplaceSlug: "loja-abc",     // Slug do marketplace
  marketplaceId: "ObjectId",       // ID do marketplace

  // Vendas agrupadas
  saleIds: [
    "ObjectId-1",                  // Referência para Sale 1
    "ObjectId-2",                  // Referência para Sale 2
    "ObjectId-3"                   // Referência para Sale 3
  ],

  // Cliente (sincronizado)
  customer: {
    name: "João Silva",
    email: "joao@example.com",
    // ... dados básicos do cliente
  },

  // Totalizações do grupo
  price: {
    amount: 90000                  // Soma de todas as Sales
  },
  currency: "BRL",

  // Status agregado
  status: "open",                  // open, pending, paid, refunded, etc

  // Rastreamento unificado
  trackingUrl: "https://marketplace.com/account/order/uuid-v4",

  // Metadata
  createdAt: "2024-01-15T10:30:00Z",
  updatedAt: "2024-01-15T10:30:00Z"
}

Características principais:

  • Funciona como um contenedor lógico para múltiplas vendas
  • Referencia múltiplas Sales via array saleIds
  • Possui status agregado que reflete o estado do grupo
  • Cada Sale no grupo é independente, mas compartilha alguns dados
  • Permite rastreamento unificado de múltiplas compras
  • Sincroniza dados do cliente com todas as Sales vinculadas

Fluxo de Dados ​

Quando você cria um SaleGroup:

  1. SaleGroup é criado com um código único e token
  2. Múltiplas Sales são vinculadas ao SaleGroup via saleGroupId
  3. Dados do cliente no SaleGroup são sincronizados para todas as Sales
  4. Cada Sale gera suas próprias parcelas (Payables)
  5. Status do SaleGroup reflete o estado agregado de todas as Sales
  6. URL de rastreamento única para acesso a todas as vendas agrupadas

Casos de Uso Comuns ​

Caso 1: Venda Única (Sale sem SaleGroup) ​

Cenário: Um cliente compra produtos de um único vendedor

Características:

  • Uma única venda
  • Cliente com um único endereço
  • Pagamento único
  • SaleGroup não é necessário

Exemplo JSON:

json
{
  "code": "LP1-LK3JC-FHM9F",
  "saleGroupId": null,
  "customer": {
    "name": "João Silva",
    "email": "joao@example.com"
  },
  "items": [
    { "name": "Produto A", "quantity": 2, "subtotal": { "amount": 10000 } }
  ],
  "payment": {
    "status": "open",
    "method": "credit_card"
  }
}

Caso 2: Múltiplas Vendas Agrupadas (Marketplace) ​

Cenário: Um cliente compra de múltiplos vendedores em um marketplace em uma única venda.

Características:

  • Cliente realiza compra única
  • Múltiplas Sales (uma por vendedor)
  • Todas vinculadas a um SaleGroup
  • Pagamento pode ser único ou múltiplo
  • Cliente vê um número de venda único (SaleGroup)

Exemplo JSON:

json
{
  "saleGroup": {
    "code": "LM-LK3JC-FHMCC",
    "token": "abc-def-ghi",
    "saleIds": ["id-sale-1", "id-sale-2", "id-sale-3"],
    "price": { "amount": 90000 },
    "status": "open"
  },
  "sales": [
    {
      "code": "LP1-LK3JC-FHM9F",
      "saleGroupId": "id-salegroup",
      "saleGroupCode": "LM-LK3JC-FHMCC",
      "customer": { "name": "João Silva", "email": "joao@example.com" },
      "items": [{ "name": "Produto do Vendedor A", "quantity": 1, "subtotal": { "amount": 30000 } }],
      "owned": { "total": { "amount": 30000 } }
    },
    {
      "code": "SAL-2024-002",
      "saleGroupId": "id-salegroup",
      "saleGroupCode": "LM-LK3JC-FHMCC",
      "customer": { "name": "João Silva", "email": "joao@example.com" },
      "items": [{ "name": "Produto do Vendedor B", "quantity": 2, "subtotal": { "amount": 30000 } }],
      "owned": { "total": { "amount": 30000 } }
    },
    {
      "code": "SAL-2024-003",
      "saleGroupId": "id-salegroup",
      "saleGroupCode": "LM-LK3JC-FHMCC",
      "customer": { "name": "João Silva", "email": "joao@example.com" },
      "items": [{ "name": "Produto do Vendedor C", "quantity": 3, "subtotal": { "amount": 30000 } }],
      "owned": { "total": { "amount": 30000 } }
    }
  ]
}

Ciclo de Vida e Estados ​

Estados de uma Sale ​

Estados principais de uma Sale:

  • open: Pagamento aberto, aguardando processamento
  • pending: Pagamento em processamento
  • paid: Pagamento confirmado pelo gateway
  • released: Pagamento liberado/liquidado
  • failed: Pagamento falhou
  • expired: Pagamento expirou
  • canceled: Pagamento cancelado
  • refunded: Pagamento reembolsado
  • chargeback: Disputa/chargeback iniciado
  • in_protest: Em protesto (boleto)
  • late: Pagamento em atraso
  • up_to_date: Pagamento em dia
  • waiting_approval: Aguardando aprovação manual
  • gifted: Presente/cupom (sem cobrança)
  • voucher: Voucher/vale (sem cobrança)
  • partially_paid: Pagamento foi parcialmente pago
  • partially_refunded: Pagamento foi parcialmente reembolsado

Estados de um SaleGroup ​

Estados principais de um SaleGroup:

  • open: Recém criado
  • pending: Em processamento de pagamento
  • partially_paid: Algumas Sales foram pagas
  • paid: Todas as Sales foram pagas
  • released: Todos os valores foram liberados
  • failed: Falha em um ou mais pagamentos
  • canceled: Agrupamento cancelado
  • refunded: Reembolso processado

Perguntas Frequentes ​

Como saber se devo usar SaleGroup? ​

Use SaleGroup quando:

  • Você tem um marketplace ou sistema com múltiplos vendedores
  • Um cliente faz uma compra que envolve produtos de vendedores diferentes
  • O cliente deve ter uma URL de rastreamento única para todas as compras

Use apenas Sale quando:

  • É uma venda simples de um vendedor para um cliente
  • Um cliente compra apenas de uma loja/vendedor
  • Você não precisa de agrupamento lógico

Quando o SaleGroup é criado? ​

O SaleGroup é criado durante o checkout, quando o sistema detecta que o cliente está comprando de múltiplos vendedores em um marketplace.

Os dados do cliente no SaleGroup e nas Sales precisam ser iguais? ​

Sim. Quando você modifica os dados do cliente no SaleGroup, a plataforma sincroniza automaticamente essas mudanças para todas as Sales vinculadas.

typescript
// Modificar cliente no SaleGroup
saleGroup.customer.name = "Novo Nome"
await saleGroup.save()  // Todas as Sales também são atualizadas

Posso remover uma Sale de um SaleGroup? ​

Não diretamente. A relação é criada no momento do checkout e é considerada imutável para manter a integridade dos dados. Se necessário, você deve cancelar a Sale e criar uma nova.

Se um pagamento falha em uma Sale dentro de um SaleGroup, o resto das Sales é afetado? ​

Não. Cada Sale é processada independentemente. Uma falha em um pagamento não afeta as outras Sales do grupo. O status do SaleGroup refletirá partially_paid ou failed para indicar o estado geral.

Qual é a diferença entre price (SaleGroup) e owned.total (Sale)? ​

  • price (SaleGroup): Soma agregada de todas as Sales dentro do grupo
  • owned.total (Sale): Total específico daquela venda individual

Preciso fazer integração diferente para Sale e SaleGroup? ​

Parcialmente. A integração base é a mesma, mas:

  • Para Sales simples: Você trabalha com o objeto Sale diretamente
  • Para SaleGroups: Você recebe um SaleGroup que contém referências a múltiplas Sales

Como rastrear uma venda que faz parte de um SaleGroup? ​

Use o trackingUrl do SaleGroup. Ele fornece uma URL única que permite ao cliente visualizar todas as compras do grupo:

json
{
  "saleGroup": {
    "trackingUrl": "https://marketplace.com/account/order/abc-def-ghi"
  }
}

Próximos Passos ​

Agora que você entende a diferença entre Sale e SaleGroup, continue explorando: