Filiais
Visão Geral
Gerencie as filiais do restaurante. Cada filial é um terminal PDV com seu próprio modo de serviço, PIN de acesso, usuários atribuídos e informações de endereço.
Localização
frontend-react/src/views/admin/PdvManagementView.tsx
Funcionalidades
- CRUD de Filiais: Criar, editar, excluir filiais
- PIN de acesso: Cada filial pode ter um PIN de 4–6 dígitos para login rápido
- Usuários atribuídos: Restringe quais funcionários podem usar o terminal
- Filial padrão: Uma filial pode ser marcada como padrão (
isDefault)
Modos de Serviço
| Modo | Descrição |
|---|---|
mesa | Atendimento no local com abertura de comanda por mesa |
balcao | Atendimento rápido no balcão, sem mesa |
auto_atendimento | Quiosque de autoatendimento |
Campos
| Campo | Tipo | Descrição |
|---|---|---|
name | string | Nome da filial |
description | string | Descrição |
slug | string? | Identificador legível para URLs do cliente |
serviceMode | string | Modo de operação (ver acima) |
active | boolean | Se a filial está ativa |
isDefault | boolean | Se é a filial padrão do tenant |
pin | string? | PIN de 4–6 dígitos (armazenado com hash) |
assignedUsers | ObjectId[] | Usuários autorizados a usar este terminal |
address | string? | Endereço da filial |
city | string? | Cidade |
phone | string? | Telefone de contato |
cnpj | string? | CNPJ da filial |
cep | string? | CEP |
stoneTerminalSerial | string? | Serial da maquininha Stone (ex: T-001ABC). Quando preenchido, ativa o fluxo automático do gateway Stone — veja abaixo |
Índices:
{ name, tenant }— unique{ slug, tenant }— unique sparse (permite null)
Pagamento com Cartão via Gateway
O campo stoneTerminalSerial controla o roteamento automático de pagamentos com cartão no terminal PDV:
| Situação | Comportamento no PaymentModal |
|---|---|
stoneTerminalSerial preenchido | Fluxo Stone: cria Payment Intent na API Stone, envia cobrança para a maquininha física, aguarda webhook → WebSocket (paymentUpdate) até 60 segundos |
stoneTerminalSerial vazio | Fluxo manual: atendente usa a maquininha fisicamente sem integração; confirma manualmente no sistema |
O serial é impresso na etiqueta traseira da maquininha Stone (formato T-XXXXXXX). Não há distinção de gateway para débito vs. crédito — o mesmo serial é usado para ambos os métodos.
Pré-requisito: as variáveis de ambiente
STONE_CLIENT_IDeSTONE_CLIENT_SECRETprecisam estar configuradas no backend. Sem elas, mesmo com serial preenchido, o pagamento falhará. Veja Gateways de Pagamento.
Nota sobre o Slug
O slug é usado para URLs voltadas ao cliente (ex: /t/demo/balcao-principal). É opcional — filiais sem slug não ficam acessíveis por URL amigável.