Como acessar

A cobrança é feita na tela Caixa, no momento de receber uma comanda. A chave PIX da empresa é cadastrada uma única vez em Configurações › PIX (/dashboard/configuracoes/pix).

A aba PIX aparece para o dono e para o gerente. O profissional não a vê, nem abrindo o endereço direto.

O que muda no balcão

Antes, o PIX era só um rótulo. Na prática, o dono abria o app do banco, gerava o QR lá, virava o celular para o cliente, esperava o “caiu” — e só então voltava ao sistema para digitar “pix”. Dois sistemas, conferência de cabeça, e o caixa sabendo apenas o que alguém teve o cuidado de digitar.

Agora o QR Code sai na própria tela do caixa, já com o valor da comanda dentro. O celular do cliente lê e paga. Ninguém sai do sistema, e o recebimento fica registrado com histórico de quem confirmou e quando.

Antes da primeira cobrança: cadastrar a chave

Em Configurações › PIX (/dashboard/configuracoes/pix) você informa para onde o dinheiro vai:

Ao salvar, a tela mostra de volta o tipo que reconheceu na chave — “reconhecemos como CPF”. Isso não é enfeite: onze dígitos podem ser um CPF ou um telefone sem o código do país, e chave lida errado manda o dinheiro do cliente para outra conta. É um erro barato de pegar aqui, no cadastro, e caríssimo de descobrir depois.

Em quais telas o QR aparece, e quando

O QR Code do PIX aparece em toda tela que recebe dinheiro, e sempre a partir da forma de pagamento: é escolher PIX que faz o código aparecer. Não existe mais um botão separado que precise ser descoberto.

• Caixa e fechamento de comanda — escolher PIX na forma de pagamento mostra o QR na hora, já com o saldo da comanda. A comanda já existe, então nada é criado: se você trocar para dinheiro e voltar para PIX, é o mesmo QR que reaparece.
• Venda Rápida (o PDV de balcão) e Nota Avulsa — ao escolher PIX, o botão de fechar muda de nome para “Cobrar R$ X por PIX”. É esse clique que registra a venda e mostra o QR, tudo de uma vez. Aqui o QR não pode nascer no toque da forma de pagamento porque, nessas telas, a venda ainda não existe — e registrar a venda dá baixa no estoque. Se o QR nascesse a cada toque em “PIX”, cada cliente que mudasse de ideia deixaria mercadoria a menos na prateleira.
• Pagamento parcial por item — escolhendo PIX, o QR aparece com o valor da parcela selecionada.

Depois que o QR está na tela: o cliente lê pela câmera ou usa o código copia e cola. Quando o dinheiro aparecer no extrato, clique em “Confirmar que caiu”.

Se a conta mudar depois de o QR aparecer

Por isso o sistema faz isso sozinho: assim que o valor da conta muda, o QR antigo some da tela na mesma hora, aparece o aviso “O valor mudou — gerando um QR Code novo”, e em seguida entra o código novo, com o valor certo. A cobrança anterior é cancelada automaticamente.

O que você precisa fazer: nada além de esperar o código novo aparecer. Só não mostre ao cliente um QR que você tirou de foto ou de print antes da mudança.

Como você sabe que o cliente pagou

O QR aparecer não é o dinheiro entrar. Enquanto ninguém confirmar, a tela fica amarela e diz, com essas palavras, que o recebimento ainda não foi confirmado. Não há verde, não há “sucesso”.

A confirmação chega por um de dois caminhos, e os dois deixam a tela verde e fecham a venda:

1. Você confere no app do banco e clica em “Confirmar que caiu”. É o caminho de hoje, porque a cobrança sai da sua própria chave PIX e o banco não tem como avisar o sistema.
2. O banco avisa sozinho, quando um provedor de PIX estiver ligado (veja a seção sobre isso, mais abaixo). Nesse caso a tela atualiza sem ninguém clicar: ela consulta o recebimento a cada poucos segundos enquanto o QR está aberto.

Como cobrar

1. Na tela do Caixa, abra a comanda que vai receber.
2. Escolha cobrar por PIX.
3. O sistema mostra o QR Code e o código copia e cola. O cliente lê o QR pela câmera ou cola o código no app do banco.
4. Quando o dinheiro aparecer no extrato, clique em “Confirmar que caiu”.

O valor já vai dentro do QR. O cliente não digita valor nenhum, o que acaba com o erro mais comum do balcão: digitar R$ 79,00 em vez de R$ 79,90. Ninguém confere noventa centavos com fila no caixa — e, somados, esses centavos são o descasamento do fechamento do dia.

Cobrança gerada não é cobrança paga

Por que a confirmação não é automática hoje

É limitação do PIX estático, que é o que uma chave PIX comum permite. A chave é a mesma em toda cobrança, e o identificador que vai dentro do QR estático não volta no extrato de forma confiável — vários bancos simplesmente ignoram esse campo.

O que o extrato entrega é “entrou R$ 79,90 de Fulano às 14h32”. Com duas comandas de R$ 79,90 no mesmo minuto, não existe informação que diga qual das duas foi paga. Não é algo que o sistema deixou de ler: a informação não é emitida por ninguém. Por isso quem concilia é a pessoa que está com o extrato aberto.

A confirmação automática exige PIX Cobrança, o dinâmico — outro produto, em que cada cobrança nasce com identificador próprio registrado na API do banco, e é esse identificador que volta no aviso de pagamento. Isso pede uma conta com API habilitada no banco ou num provedor de pagamento, o que é decisão comercial, não técnica. O sistema já está preparado para receber esse aviso (veja a última seção).

Os estados da cobrança

• aguardando — o QR existe e ninguém confirmou nada. É o estado em que a tela nunca sugere que o dinheiro entrou.
• recebido — alguém confirmou. É o único estado que gera pagamento na comanda.
• cancelada — desistiu-se da cobrança: o cliente vai pagar em dinheiro, a comanda mudou.
• expirada — passou do prazo sem confirmação (padrão de 30 minutos, configurável). Não é erro, é limpeza.

Os três últimos são finais: uma cobrança recebida, cancelada ou expirada não volta para aguardando.

A expiração acontece enquanto alguém usa o sistema: ao gerar uma cobrança nova e ao abrir a lista de cobranças de uma comanda, o que já venceu é marcado como expirado. Foi feito assim de propósito — depender de um agendamento significaria que numa instalação sem agendador configurado a tela ficaria travada, com o número da comanda ocupado por uma cobrança morta.

Além disso, o trabalho diário de cobrança (POST /api/cron/cobrancas, o mesmo que lança as mensalidades) faz uma varredura em lote. Ele não substitui a limpeza na leitura, soma-se a ela: serve para a loja que ficou fechada uma semana e, ao abrir, já encontra a lista limpa em vez de limpá-la na primeira consulta do dia.

O que acontece quando você confirma

O pagamento é registrado na comanda como forma PIX, pelo mesmo caminho de qualquer outro recebimento do sistema. Não existe um segundo caminho para dinheiro entrar — e é por isso que a cobrança aparece sozinha no Fluxo de Caixa do dia, no fechamento da comanda e nos relatórios, sem que nada disso precise ser ajustado.

O operador não digita “pix” em lugar nenhum. É o ganho inteiro do módulo.

Confirmar duas vezes não gera dois pagamentos

Se a tela demorar a responder e o operador clicar de novo — o que acontece —, o sistema reconhece a segunda confirmação como repetição da primeira e não duplica o pagamento. A resposta é honesta sobre isso: avisa que a confirmação já havia sido registrada, em vez de fingir que fez algo novo.

Cancelar uma cobrança

Cobrança em aguardando pode ser cancelada — o cliente mudou de ideia, vai pagar em dinheiro, a comanda mudou. Cobrança já recebida não é cancelada: para desfazer um recebimento, o caminho é o estorno do pagamento, que é outra operação e tem trilha própria.

Para quem for ligar o banco ou um provedor depois

Esta seção é técnica, e existe para deixar claro o tamanho do trabalho que sobra.

A cobrança já é uma máquina de estados gravada no banco, com histórico de eventos e rota de webhook de pé: POST /api/pix/webhook, autenticada por bearer em PIX_WEBHOOK_SECRET — e que fecha (responde 503 e não processa nada) se o segredo não estiver configurado, porque falhar aberto num endpoint que dá baixa em pagamento seria publicar um botão de “marcar como pago” para a internet.

Ligar um provedor real é, na prática, quatro passos:

1. escrever o adaptador em src/lib/pix-provedor-<nome>.ts;
2. registrá-lo em uma linha na lista de adaptadores conhecidos;
3. definir PIX_PROVEDOR no ambiente;
4. apontar a URL do webhook e o PIX_WEBHOOK_SECRET.

Nada além disso. Modelo de dados, estados, histórico, tela, a integração com o caixa e a rota de webhook já estão de pé e não mudam — a tela passa a aguardar o webhook em vez de pedir atestado porque lê do provedor ativo se ele exige confirmação do operador.

A API Pix é padronizada pelo Banco Central (github.com/bacen/pix-api), então um mesmo adaptador serve os bancos que fazem “Pix direto” — BB, Itaú, Sicredi, Bradesco: escreve-se uma vez contra a especificação oficial, e o que muda por banco depois é só a autenticação. Provedores de pagamento (Mercado Pago, Stone, Efí, Asaas) têm API própria, sem especificação comum, e em troca dispensam certificado.

A confirmação manual também não é andaime que se joga fora. Depois do provedor, ela continua existindo como caminho de exceção — transferência combinada por fora acontece —, só deixa de ser o caminho principal.