Integra Cardápio

Como funciona

O cardápio tem dois modos de operação, configurados por loja. Os dois reaproveitam o caminho que MultiPedidos, OlaClick e Amana já usam: o pedido entra no lic-server como evento pendente, o app-client busca, grava no Linx e confirma. O pagamento online é feito pela Pagar.me.

Os dois modos

Onde cada peça mora

Modo Comanda

sequenceDiagram
    autonumber
    participant C as Cliente (QR da mesa)
    participant L as lic-server
    participant G as Pagar.me
    participant A as app-client
    participant P as PDV Linx
    C->>L: POST /c/{slug}/pedidos (mesa 12)
    L->>L: soma na conta da mesa + evento order PENDING
    A->>L: GET /integration/cardapio777/pending
    A->>P: abre orçamento da mesa ou acrescenta linhas
    A->>L: ack
    Note over C,P: o cliente repete quantas vezes quiser
    C->>L: GET /c/{slug}/mesas/12/conta
    C->>L: POST /c/{slug}/mesas/12/pagamentos (valor, PIX ou card_token)
    L->>G: POST /core/v5/orders
    G-->>L: webhook charge.paid
    L->>L: abate da conta + evento table_payment PENDING
    A->>P: INSERT orcamento_pagamento
    alt conta zerada
        L->>L: evento table_closed (taxa de serviço)
        A->>P: linha 9001 TAXA DE SERVICO
        Note over P: caixa emite a NFC-e e libera a mesa
    end

Modo Pedido

sequenceDiagram
    autonumber
    participant C as Cliente
    participant L as lic-server
    participant G as Pagar.me
    participant A as app-client
    participant P as PDV Linx
    C->>L: POST /c/{slug}/pedidos (itens + PIX ou card_token)
    L->>G: POST /core/v5/orders
    G-->>C: QR do PIX (ou resultado do cartão)
    G-->>L: webhook charge.paid
    L->>L: só agora cria o evento order PENDING
    A->>L: GET /integration/cardapio777/pending
    A->>P: orçamento + itens + pagamento "PIX - PAGO"
    A->>L: ack
    Note over C,L: PIX expirado ou cartão recusado: o pedido nunca chega ao PDV

Fila de espera

Não passa pelo PDV. É estado do lic-server (fila por loja) com SMS nos momentos que importam para o cliente. Quando o grupo senta, a mesa fica ocupada no mapa e a comanda abre no primeiro pedido pelo QR da mesa.

stateDiagram-v2
    direction LR
    [*] --> Esperando: QR da porta ou recepção · SMS de entrada
    Esperando --> Esperando: virou o 1º · SMS "você é o próximo"
    Esperando --> Chamado: recepção escolhe mesa livre · SMS "mesa pronta"
    Esperando --> Saiu: cliente sai ou recepção remove
    Chamado --> Sentou: chegou na recepção · mesa ocupada
    Chamado --> NaoVeio: passou de 10 min · SMS "vez expirou"
    Sentou --> [*]
    Saiu --> [*]
    NaoVeio --> [*]

• Posição e espera estimada vêm da ordem de chegada e do giro médio de mesas do dia. Grupos grandes podem esperar mais, porque dependem de mesa grande ou de juntar mesas.
• A página do cliente é a fonte da verdade; o SMS só avisa e leva o link. Quem não quer SMS acompanha pela página.
• Prazo de chamada configurável (10 min no mockup). Depois disso a recepção marca "não veio" e a mesa volta a ficar livre.

Delivery

sequenceDiagram
    autonumber
    participant C as Cliente (link da loja)
    participant L as lic-server
    participant G as Pagar.me
    participant S as Provedor SMS
    participant A as app-client
    participant P as PDV Linx
    C->>L: POST /c/{slug}/delivery (itens, CEP, endereço, pagamento)
    L->>L: valida área, taxa e pedido mínimo
    opt pagamento online
        L->>G: POST /core/v5/orders
        G-->>L: webhook charge.paid
    end
    L->>S: SMS "pedido recebido"
    L->>L: evento order (channel=delivery) PENDING
    A->>L: GET /integration/cardapio777/pending
    A->>P: orçamento de entrega com endereço, frete e pagamento
    A->>L: ack
    Note over L,S: loja muda o status no painel: em preparo, saiu, entregue · cada um vira SMS

• O PDV já sabe gravar delivery. O pdv_integrator usa deliveryAddress e deliveryFee do pedido, como no MultiPedidos. Pago online entra como "PIX - PAGO"; na entrega, como "DINHEIRO - A COBRAR" ou "CARTAO - A COBRAR", com o troco na observação.
• O status da entrega é do painel, não do PDV: a loja avança o pedido no quadro e cada etapa gera um SMS. Cancelar gera estorno na Pagar.me (se pago) e um evento de cancelamento para o app-client.
• Área de entrega: CEP → endereço → distância ou polígono, com taxa e prazo por faixa. Fora da área, o cliente vê antes de montar o pedido inteiro.

SMS

• Textos sem acento e com até 160 caracteres. Um acento troca a codificação para UCS-2 e o limite cai para 70, o que dobra ou triplica o custo. O mockup mostra a contagem de cada mensagem.
• Só SMS transacional, com opt-in na própria tela e "Responda SAIR" na primeira mensagem (LGPD). O número fica só no pedido ou na fila e é mascarado no painel.
• Envio assíncrono: o lic-server grava o SMS como pendente e um worker envia. O webhook de status do provedor marca enviado, entregue ou falhou, e o painel mostra.
• Limites: no máximo um SMS por etapa e por pedido ou entrada na fila; reenvio só manual pela recepção. Custo por loja aparece no portal.
• WhatsApp fica para depois, pela mesma interface de envio.

Regras

• Código PDV é obrigatório para o item entrar no orçamento. Código inexistente cai no mesmo ProductLookupError de hoje e o pedido fica na fila com erro até o lojista corrigir.
• O cartão nunca passa pelo nosso servidor. O navegador gera um card_token com a chave pública da loja; o lic-server só recebe o token. A chave secreta fica no lic-server, cifrada, uma por loja.
• Webhook não é prova sozinho. O lic-server valida a autenticação do webhook e consulta a cobrança na API antes de dar baixa.
• Valores em centavos e calculados no servidor. O cliente escolhe quanto pagar, mas o servidor limita ao que falta na mesa. Um PIX pendente reserva o valor por 15 minutos para duas pessoas não pagarem a mesma parte.
• Idempotência em tudo: chave por carrinho no pedido, chave por cobrança na Pagar.me e o evento só sai da fila com ack.
• Pedido pago com erro no PDV (modo Pedido) já tem o dinheiro capturado. O painel destaca e o lojista corrige e reprocessa, ou estorna pela Pagar.me.
• Taxa de serviço é opcional e configurável. Vai como linha 9001 no fechamento da comanda.
• O QR tem token assinado por mesa. Ninguém pede para a mesa 12 trocando o número na URL.

Contratos novos

Fases

Decisões em aberto