PDV (frente de caixa)

O aplicativo de balcão. Roda em tela cheia no endereço /pdv, fora do menu lateral, e usa a mesma engine de preços da loja online — o valor cobrado no balcão é idêntico ao do site.

Quem pode acessar

pos.operate — operar o PDV.
pos.manage_cash — abrir e fechar o caixa.
pos.discount, pos.cancel, pos.refund, pos.courtesy sensíveis — ações que também podem ser liberadas por PIN de supervisor.

As duas permissões andam juntas

O caixa é obrigatório para operar. Um operador com pos.operate mas sem pos.manage_cash não consegue abrir o caixa e, portanto, não consegue vender.

Antes de vender: os dois portões

O PDV só libera a tela de venda quando as duas condições são atendidas:

Maquininha selecionada. O operador escolhe o equipamento e pode trocá-lo durante o expediente.
Caixa aberto. Informa-se o fundo de troco e o caixa começa.

Enquanto isso não acontece, a tela inicial conduz esses dois passos.

Montando a venda

O operador escolhe a data e vê os ingressos disponíveis, com os mesmos valores do site.
Datas futuras exibem o preço antecipado destacado em relação ao cheio, com selo indicativo.
É possível identificar o cliente buscando um contato existente ou criando um novo.
Cupom de desconto pode ser aplicado; desconto manual exige permissão ou PIN.

Formas de recebimento

Uma venda pode ter vários pagamentos — por exemplo, parte em dinheiro e parte no cartão.

Forma	Exige	Observações
Dinheiro	Caixa aberto	O sistema calcula o troco (recebido menos valor). É a única forma que entra no caixa.
Cartão	Maquininha e identificador da transação	Distingue crédito de débito; só o crédito parcela.
Pix	Maquininha e identificador da transação	Processado pela maquininha.
Contingência manual	Identificador da transação obrigatório	Usada quando a maquininha processou fora do sistema.

Por que o identificador da transação é exigido

Pagamentos digitais não podem ser marcados como aprovados sem o identificador da operadora. É o que impede alguém de “aprovar” manualmente uma cobrança que não aconteceu — e o que permite a conciliação depois. O sistema também barra o mesmo identificador em duas linhas diferentes.

Em pagamento misto ou com falha, os valores já aprovados são preservados: o operador pode tentar de novo ou trocar de forma até cobrir o total. Quando a soma dos aprovados alcança o total, os vouchers são gerados.

Sessão de caixa

Detalhes completos em fluxo do caixa. Em resumo:

A sessão é por operador; só pode haver uma aberta por vez para a mesma pessoa.
Abre com o fundo de troco.
O valor esperado é o fundo mais todo o dinheiro aprovado recebido naquela sessão.
No fechamento, compara-se esperado × contado. A divergência não bloqueia, mas exige aceite explícito.
Só dinheiro é conciliado; cartão e Pix vão direto para a adquirente.
Estorno em dinheiro reduz o esperado automaticamente.
Sair com o caixa aberto força o fechamento antes.

Nesta fase não há sangria nem suprimento de caixa.

Autorização por PIN de supervisor

Quando o operador não tem a permissão de uma ação sensível e a empresa habilitou a liberação por PIN, um supervisor digita o PIN dele na própria tela — sem trocar de sessão e sem refazer o carrinho.

A autorização vale para um único uso e expira em 20 minutos.
Fica registrado quem operava, quem autorizou, qual ação, o valor e o motivo.
Após várias tentativas erradas, o PIN é bloqueado por um período configurável.
Cada usuário cadastra o próprio PIN (4 a 6 dígitos) em Minha conta → PIN de supervisor.

Entrega do voucher

Após a venda, o voucher pode ser entregue por WhatsApp, e-mail ou impressão (o QR sai em qualquer impressora acessível). Pulseiras são entrega física e não ficam vinculadas ao voucher. Venda para data futura recebe apenas o voucher.

Cancelamento e estorno no balcão

Cancelamento marca a venda como cancelada e cancela os vouchers, liberando a capacidade. Exige permissão ou PIN.
Estorno é por parcela de pagamento, pelo meio original: dinheiro sai do caixa; cartão e Pix voltam pela operadora; contingência manual deve ser estornada na mesma máquina.
Quando todas as parcelas aprovadas são estornadas, a venda passa a Reembolsado e os vouchers são cancelados.
Voucher já usado bloqueia as duas ações.

Check-in no balcão

O operador pode dar check-in do voucher direto no PDV (na tela de sucesso da venda e no painel de vendas), reaproveitando o mesmo motor do portão. Isso exige a permissão checkin.operate — quem opera o balcão e também valida entrada precisa das duas permissões.

Regras de negócio

O servidor recalcula o preço de cada item e ignora o valor enviado pela tela.
Sem preço calculável, a venda falha (price_unavailable).
Mesmo corte de preço antecipado do site, usando o fuso do parque.
Desconto manual registra quem aplicou, o valor e o motivo.
O PDV não grava promotor — atribuição de promotor é exclusiva da loja online.
A maquininha usada fica gravada em cada pagamento digital, para conciliação e estorno.
O PDV é web e on-line: não há modo off-line.

Erros e dúvidas comuns

Mensagem / situação	Motivo	Solução
`cash_session_required`	Recebimento em dinheiro sem caixa aberto	Abrir o caixa
`manual_requires_transaction_id`	Contingência manual sem identificador	Informar o identificador da transação
`digital_approved_requires_transaction_id`	Pagamento digital sem identificador	Aguardar o retorno da maquininha
Identificador duplicado	A mesma transação foi lançada duas vezes	Conferir os pagamentos já registrados
`divergence_requires_accept`	Fechamento com diferença de caixa	Conferir a contagem e aceitar a divergência
Não abre a tela de venda	Falta maquininha ou caixa	Concluir os dois passos iniciais
Ação pede PIN	Operador sem a permissão	Chamar um supervisor

Boas práticas

Feche o caixa no fim do turno, ainda com o time presente para conferir divergências.
Registre o motivo do desconto manual com clareza — ele é lido em auditoria.
Use contingência manual apenas quando a maquininha realmente processou fora do sistema, e anote o comprovante.
Confira as datas incluídas ao vender um pacote pelo balcão.
Prefira liberar ações sensíveis por PIN a conceder a permissão de forma permanente.