Documentacao Campanhas Vendor APP
v1.0.0
Campanhas e Ofertas — Vendor App
## O que é
O motor de Campanhas e Ofertas do Vendor App replica, dentro do pedido, as mesmas regras de negócio já usadas no ERP Delphi (Quantidade, Cruzada, Progressiva, Bonificação, Fixo e Percentual, combinadas com os benefícios Desconto no Ativador, Desconto no Beneficiado, Cortesia e Desconto por Condição de Pagamento).
> As regras de cada combinação Tipo + Benefício não são tratadas aqui — já estão especificadas pela equipe Delphi. Este documento cobre **como usar** a funcionalidade no app: de onde vêm as campanhas, como habilitar e configurar, e como o vendedor interage com elas ao montar um pedido.
---
## 1. Importação das campanhas
Campanhas **não são criadas nem editadas no Vendor App**. Todo o cadastro (tipo, benefício, item ativador/alvo, percentuais, valores, vigência, clientes elegíveis) é feito no ERP Delphi e chega ao app pela sincronização normal, junto com o restante dos dados (igual itens, clientes, condições de pagamento etc.).
- Uma campanha só aparece disponível pro vendedor se estiver **dentro da vigência** (data início/fim), **ativa** e **elegível** pra empresa/cliente do pedido em questão — essa filtragem é automática, feita pelo próprio app.
- Se uma campanha cadastrada no Delphi não aparecer no app, o motivo normalmente é sincronização (campanha ainda não chegou) ou vigência/elegibilidade (fora da data) .
---
## 2. Permissão por usuário — quem pode usar campanhas
Antes de qualquer configuração de comportamento, existe um interruptor geral por usuário: **`can_use_campaign`** ("Pode usar campanhas").
- Configurado no **Multipanel**, na tela de cadastro/edição do usuário, junto com as demais permissões .
- **Default: desligado.** Precisa ser habilitado manualmente pra cada usuário que for trabalhar com campanhas.
- Com a permissão **desligada**: o card "Campanhas do Pedido" **não aparece** no formulário de pedido, e nenhuma validação de campanha roda ao finalizar — é como se a funcionalidade não existisse pra esse usuário, independente de haver campanhas sincronizadas ou do valor do parâmetro `require_campaign` (seção 3).
- Com a permissão **ligada**: o card aparece sempre que houver ao menos uma campanha sincronizada, e as validações de finalização passam a valer conforme `require_campaign`.
---
## 3. Obrigatoriedade de aplicar campanhas — parâmetro `require_campaign`
Parâmetro de pedido (não de usuário), configurado no **Multipanel**, na tela de Parâmetros do Vendor. Define o que acontece se o pedido atingir a condição de uma campanha e ela **não** for aplicada antes de finalizar.
| Valor | Comportamento ao finalizar |
| --- | --- |
| none (default) | Nenhuma validação — o pedido finaliza normalmente mesmo com campanha pendente de aplicação |
| warn | Mostra um aviso, mas permite continuar e finalizar mesmo assim |
| require | Bloqueia a finalização até a campanha ser aplicada (ou até deixar de se enquadrar) |
> `require_campaign` só tem efeito pra usuários com **`can_use_campaign` ligado** (seção 2). Um usuário sem a permissão nunca vê a validação, mesmo com o parâmetro em `require`.
---
## 4. Card "Campanhas do Pedido"
Aparece no formulário de pedido (mobile e web/desktop), abaixo dos dados do pedido, sempre que houver campanhas sincronizadas e o usuário tiver permissão. Mostra um contador com a quantidade de campanhas disponíveis. Toque/clique para abrir a tela de campanhas.
---
## 5. Aba "Simulação"
Primeira aba da tela de campanhas. Mostra, **linha por item do pedido atual**, se alguma campanha se aplicaria a ele:
| Coluna | Descrição |
| --- | --- |
| Status | APLICARIA, PENDENTE ou NÃO APLICA |
| Item | Referência do item |
| Descrição | Descrição do item |
| Ação | Tipo de benefício que seria aplicado (ex. "Desconto") |
| Desc Original | Desconto manual já lançado no item, se houver |
| Desc Simulado | Valor do desconto que a campanha aplicaria |
| Falta (un.) | Ver abaixo |
| Qtd Máxima | Teto de quantidade da campanha (MAX_QTY), se houver |
| Campanha | Nome da campanha |
**Status:**
- **APLICARIA** — a condição já foi atingida; o item receberia o benefício se você tocar em "Aplicar Agora"
- **PENDENTE** — a campanha ainda não foi atingida por esse item. A coluna "Falta (un.)" explica o motivo:
- Quantidade insuficiente no ativador: mostra quantas unidades ainda faltam (ex. `3`)
- Falta o item alvo no pedido (campanhas Cruzada): mostra `Incluir <referência do item alvo>`
- **NÃO APLICA** — o item não participa de nenhuma campanha no momento
---
## 6. Aba "Campanhas Ativas"
Lista todas as campanhas sincronizadas e disponíveis pra esse pedido (independente de terem sido atingidas ou não):
| Coluna | Descrição |
| --- | --- |
| Nome | Nome da campanha |
| Tipo | Quantidade, Cruzada, Progressiva, Bonificação, Fixo ou Percentual |
| Benefício | Desconto no Ativador, Desconto no Beneficiado, Cortesia ou Desconto por Condição de Pagamento |
| Item Alvo | Item que recebe o benefício (campanhas Cruzada) |
| Qtd Mín | Quantidade mínima do ativador |
| Desconto | Percentual ou valor fixo configurado |
| Início / Fim | Vigência da campanha |
| Cond. Pgto | Condição de pagamento associada (campanhas por condição de pagamento) |
Ao selecionar uma linha, abre um painel abaixo mostrando os itens da campanha como chips, marcados com as etiquetas **Ativador** e/ou **Alvo** conforme o papel de cada item naquela campanha.
---
## 7. Aplicar e desfazer campanhas
No rodapé da tela de campanhas:
- **Aplicar Agora** — varre **todos os itens do pedido de uma vez** (não item a item) e aplica o benefício de toda campanha atingida. Um aviso confirma quantos itens receberam desconto, ou avisa se nenhuma campanha foi atingida.
- **Desfazer Campanhas** — remove **só** os descontos que vieram de campanha (preserva qualquer desconto manual lançado à parte no item).
- **Fechar** — fecha a tela sem alterar nada.
---
## 8. Bloqueios enquanto há campanha aplicada
Pra evitar que o pedido fique com desconto de campanha desatualizado:
- **Editar ou remover um item com campanha aplicada** é bloqueado. O app avisa: *"Este item está com campanha aplicada. Use o botão 'Desfazer Campanhas' antes de alterar ou remover o item."*
- **Trocar cliente ou condição de pagamento** com qualquer campanha aplicada no pedido também é bloqueado — ambos podem mudar a elegibilidade da campanha. Aviso: *"O pedido está com campanha aplicada. Use o botão 'Desfazer Campanhas' antes de trocar cliente ou condição de pagamento."*
Em ambos os casos, a solução é a mesma: usar **Desfazer Campanhas** antes de fazer a alteração desejada, e reaplicar depois se ainda fizer sentido.
---
## 9. Validação ao finalizar o pedido
Só roda se o usuário tiver `can_use_campaign` ligado **e** `require_campaign` for `require` ou `warn` (seção 2 e 3). Se o pedido tiver alguma campanha atingida e ainda não aplicada:
- **`require`** — janela informativa "Campanha Pendente": *"Este pedido atingiu a condição de uma ou mais campanhas que ainda não foram aplicadas. Aplique as campanhas antes de finalizar o pedido."* Só tem o botão **Ok**; é preciso voltar, aplicar (ou desfazer a elegibilidade) e tentar finalizar de novo.
- **`warn`** — janela de confirmação "Campanha Pendente": *"Este pedido atingiu a condição de uma ou mais campanhas que ainda não foram aplicadas. Deseja continuar mesmo assim?"* Com **Sim** o pedido finaliza normalmente sem a campanha; **Não** cancela e volta pro formulário.
Uma campanha **já aplicada** não dispara mais esse aviso, mesmo que a condição continue valendo.
---
## Fluxo típico de uso
1. Monte o pedido normalmente (cliente, condição de pagamento, itens)
2. Abra o card **Campanhas do Pedido**, se aparecer
3. Veja na aba **Simulação** quais itens já atingiram (`APLICARIA`) ou estão perto de atingir (`PENDENTE`) alguma campanha
4. Se estiver `PENDENTE` por quantidade, ajuste a quantidade do item ativador; se for por item alvo faltando, inclua o item indicado
5. Toque em **Aplicar Agora** para aplicar todos os benefícios atingidos de uma vez
6. Confira na aba **Campanhas Ativas** o detalhe de qualquer campanha, se precisar
7. Finalize o pedido — se `require_campaign` estiver como `require` ou `warn` e ainda houver campanha pendente, o app vai avisar antes de deixar continuar.
8. Pedido criado deve chegar ao Delphi com o campo "ID*OFFERS" preenchido no vendas*dt.