Sale (Venda)

A Sale (Venda) e a entidade central do PDV, representando uma transacao comercial entre o petshop e o cliente.

Descricao

Uma venda pode conter produtos, servicos e pacotes. Ela passa por um ciclo de vida bem definido, desde a abertura ate a finalizacao ou cancelamento. Vendas podem ser do tipo "sale" (venda efetiva) ou "budget" (orcamento).

Dados

Identificacao

Campo	Tipo	Obrigatorio	Descricao
sale_number	Numero	Auto	Numero sequencial unico por conta
name	Texto	Auto	Formato: "No [sale_number]"
full_name	Texto	Auto	Formato: "No [sale_number] - [cliente]"
type	Selecao	Sim	"sale" (venda) ou "budget" (orcamento)
status	Selecao	Sim	Estado atual da venda
date_time	DataHora	Auto	Data/hora de finalizacao
date	Data	Auto	Data da venda

Valores

Campo	Tipo	Obrigatorio	Descricao
total	Monetario	Calculado	Soma dos totais dos itens
discount	Decimal	Nao	Desconto aplicado (0-100%)
applied_discount	Selecao	Nao	Modo de desconto aplicado
obs	Texto	Nao	Observacoes da venda

Cancelamento

Campo	Tipo	Descricao
canceled_type	Selecao	"total" ou "partial"
last_canceled_at	DataHora	Ultima data de cancelamento
total_canceled_value	Monetario	Valor total cancelado
canceled_quantity	Numero	Quantidade de itens cancelados
last_canceled_obs	Texto	Observacao do cancelamento

Relacionamentos

Pertence a

Entidade	Obrigatorio	Descricao
Account	Sim	Conta do petshop
Store	Sim	Filial onde ocorreu
User	Sim	Operador que criou
Customer	Condicional	Cliente (obrigatorio se tiver servicos)
Seller	Nao	Vendedor/Profissional
Address	Nao	Endereco de entrega
KnowledgeChannel	Nao	Canal de conhecimento
BenefitClub	Nao	Clube de beneficios do cliente

Possui

Entidade	Descricao
CartItems	Itens do carrinho (produtos, servicos, pacotes)
Checkout	Processo de pagamento
Payments	Pagamentos realizados
Deliveries	Entregas vinculadas
BeautyServices	Servicos de estetica criados
SaleCancellations	Registros de cancelamento
Pets	Pets vinculados aos itens

Ciclo de Vida (Status)

Estados

Status	Descricao	Acoes Permitidas
open	Venda em construcao	Adicionar itens, definir cliente, aplicar desconto
pending	Finalizada, aguardando pagamento	Ir para checkout, voltar para edicao
paid	Totalmente paga	Cancelar (total ou parcial), imprimir
canceled	Completamente cancelada	Nenhuma
partially_canceled	Alguns itens cancelados	Cancelar restante

Regras de Transicao

De	Para	Condicoes
open	pending	Minimo 1 item; Cliente obrigatorio se tiver servicos; Validacao de estoque; Pets atribuidos aos itens que exigem
pending	open	Sempre permitido
pending	paid	Soma dos pagamentos maior ou igual ao total
paid	canceled	Sempre permitido (com registro de motivo)
paid	partially_canceled	Ao cancelar alguns itens
partially_canceled	canceled	Ao cancelar todos os itens restantes

Modos de Desconto

Modo	Descricao
default	Usa desconto padrao das configuracoes do PDV
no	Sem desconto (0%)
min	Desconto minimo das configuracoes
max	Desconto maximo das configuracoes (100%)

Regras de Desconto

1. Desconto so pode ser alterado quando status = "open"
2. Desconto nao pode exceder pdv_settings.max_discount
3. Itens com ignore_pdv_discounts = true nao sao afetados
4. Ao alterar modo, todos os itens sao atualizados

Validacoes

Antes de Finalizar (open para pending)

1. Itens obrigatorios: Minimo 1 cart_item
2. Cliente condicional: Obrigatorio se venda contem SaleService ou SalePackage
3. Estoque: Se pdv_settings.forbid_with_negative_stock = true, valida disponibilidade
4. Pets: Itens com request_pet = true devem ter pet atribuido
5. Desconto: Nao pode exceder maximo permitido

Mensagens de Erro

• "Voce precisa vincular um pet aos itens [X] antes de finalizar a venda"
• "Estoque insuficiente para os itens: X (disponivel: Y, solicitado: Z)"

Automacoes

Ao Criar

1. Define user como usuario atual
2. Define sale_number auto-incrementado
3. Define date_time e date atuais
4. Define seller se usuario atual for profissional vendedor

Ao Finalizar (status para pending)

1. Atualiza date_time e date
2. Herda knowledge_channel do cliente se nao definido
3. Herda seller do usuario atual se nao definido
4. Gera Checkout automaticamente (se type = "sale")
5. Atualiza status de todos os cart_items

Ao Pagar (status para paid)

1. Processa nota fiscal (se configurado)
2. Extrai e armazena impostos nos cart_items (ICMS, PIS, COFINS)
3. Cria BeautyServices para servicos/pacotes vendidos
4. Cria Deliveries conforme regras de prepago/pospago
5. Gera transacoes financeiras
6. Recalcula valores do cliente (pendente, cashback, credito)
7. Agenda notificacoes WhatsApp de recompra
8. Recalcula estrelas do cliente

Ao Cancelar

1. Registra motivo em SaleCancellation
2. Recalcula valores do cliente
3. Recalcula estrelas do cliente

Calculo de Impostos

Quando Calculado

Impostos sao calculados ao mudar status para "paid", apos geracao da nota fiscal.

Impostos Armazenados por Item

Imposto	Campos Armazenados
ICMS	Base (vBC), CST, Aliquota (pICMS), Valor (vICMS)
PIS	Base (vBC), CST, Aliquota (pPIS), Valor (vPIS), Aliquota unitaria
COFINS	Base (vBC), CST, Aliquota (pCOFINS), Valor (vCOFINS), Aliquota unitaria

ICMS por Estado

Checkout Automatico

Geracao

• Criado automaticamente ao mudar status para "pending" e type = "sale"
• Destruido ao voltar status para "open"

Condicao para Pagamento

valid_to_pay = soma(payments.value) >= total

Integracao com Beauty Center

Quando status muda para "paid":

1. Para cada SaleService: cria BeautyService com status "available"
2. Para cada SalePackage: cria um servico para cada item do pacote
3. Quantidade de servicos = quantidade vendida

Integracao com Delivery

Regras de Criacao

Configuracao	Quando Cria Delivery
prepaid_payment	Ao mudar para "paid"
postpaid_payment	Ao mudar para "pending"

Ao Trocar Cliente

• Remove todos os itens de delivery
• Limpa atribuicoes de pet

Notificacoes de Recompra

Ao mudar para "paid", para cada item com repurchase_days > 0:

• Agenda WhatsApp para X dias no futuro
• Mensagem: "Ola, [cliente]! Sentimos sua falta aqui na [loja]. Percebemos que o [produto] esta acabando. Estamos te aguardando"

Sale vs Budget

Caracteristica	Sale (Venda)	Budget (Orcamento)
Gera Checkout	Sim	Nao
Gera Nota Fiscal	Sim	Nao
Pode virar Sale	N/A	Sim
Fluxo de pagamento	Completo	Simplificado

Escopos de Busca

Escopo	Descricao
sale	Apenas vendas (type = "sale")
budget	Apenas orcamentos (type = "budget")
paid	Status = "paid"
pending	Status = "pending"
canceled	Status = "canceled"
not_paid	Status in ["pending", "open"]
valid_to_calculate	Status in ["paid", "partially_canceled"]
valid_to_delivery	Vendas com cliente, prontas para entrega

Filtros Disponiveis

• search: Por nome ou numero da venda
• date: Intervalo de datas
• user: Por operador
• seller: Por vendedor
• customer: Por cliente
• pet_ids: Por pet (dependente do cliente)
• status: Por status
• knowledge_channel: Por canal de conhecimento

Permissoes

Acao	Condicao
Editar	Status = "pending" na view show
Pagar	Type = "sale" e status = "pending" e valid_to_pay
Cancelar	Status = "paid" ou "partially_canceled"
Finalizar	Status = "open" e tem itens
Converter para Venda	Type = "budget"
Imprimir Comprovante	Status = "paid" ou "partially_canceled"
Emitir NFCe/NFSe	Type = "sale" e status = "paid"