API - Pedidos

Endpoints

GET /t/:slug/orders

Lista pedidos (staff/admin). Filtrado automaticamente pelo BranchScopeGuard com base nos PDVs atribuídos ao usuário.

Auth: Staff ou Admin

Query params:

• status — Filtrar por status (pending, confirmed, preparing, ready, delivered, cancelled)
• pdvIds[] — Array de IDs de PDV para escopo de filial (aplicado automaticamente pelo guard)

Response:

[
  {
    "_id": "...",
    "orderNumber": "20260227-0001",
    "items": [
      { "menuItem": "...", "name": "X-Burguer", "price": 2500, "quantity": 2, "notes": "Sem cebola" }
    ],
    "customerName": "João",
    "customerPhone": "11999999999",
    "status": "preparing",
    "type": "dine_in",
    "table": "...",
    "pdv": "...",
    "paymentMethod": null,
    "isSplitBill": false,
    "splitBillReference": null,
    "total": 5000,
    "createdAt": "..."
  }
]

POST /t/:slug/orders

Cria um novo pedido (público — sem autenticação).

Body:

{
  "items": [
    { "menuItem": "...", "quantity": 2, "notes": "Sem cebola" }
  ],
  "customerName": "João Silva",
  "customerPhone": "11999999999",
  "orderType": "dine_in",
  "table": "..."
}

GET /t/:slug/orders/open-tab/:tableId

Retorna o pedido ativo (não entregue e não cancelado) de uma mesa. Usado pelo PDV no Modo Mesa para detectar comanda aberta.

Auth: Staff ou Admin

Response: Objeto Order ou null

PATCH /t/:slug/orders/:id/add-items

Adiciona itens a uma comanda aberta existente (Modo Mesa). Incrementa a quantidade se o item já existe; adiciona como novo item caso contrário. Recalcula o total e emite evento WebSocket para a cozinha.

Auth: Staff ou Admin + BranchScopeGuard

Body:

{
  "items": [
    { "menuItem": "...", "quantity": 1, "notes": "Bem passado" }
  ]
}

Response: Objeto Order atualizado

POST /t/:slug/orders/:id/close-tab

Fecha uma comanda aberta: marca o pedido como delivered e emite evento WebSocket.

Auth: Staff ou Admin + BranchScopeGuard

Body (opcional):

{ "paymentMethod": "credit_card" }

Response: Objeto Order atualizado

POST /t/:slug/orders/:id/process-payment

Processa o pagamento de um pedido via gateway externo.

Auth: Staff ou Admin

Body:

{
  "method": "credit_card",
  "gateway": "stone",
  "stoneTerminalSerial": "T-001ABC"
}

Response (mock/gateway desativado):

{ "status": "approved", "transactionId": "mock-txn-abc123" }

Response (Stone ativo):

{
  "status": "processing",
  "intentId": "stone-intent-xyz",
  "message": "Aguardando pagamento na maquininha..."
}

A resolução final chega assincronamente via WebSocket paymentUpdate quando o webhook Stone é processado.

---

POST /api/stone/webhook

Recebe notificações de resultado de pagamento da Stone. Rota global (sem prefixo /t/:slug).

Auth: HMAC-SHA256 via header X-Stone-Signature (segredo: variável de ambiente STONE_WEBHOOK_SECRET). Requisições com assinatura inválida retornam 401.

Body (Stone):

{
  "event": "payment_intent.approved",
  "data": {
    "id": "stone-intent-xyz",
    "status": "approved"
  }
}

Ao receber o webhook, o StoneController atualiza paymentStatus no pedido e emite paymentUpdate via KitchenGateway.

PUT /t/:slug/orders/:id/status

Atualiza status do pedido.

Auth: Staff ou Admin

Body:

{
  "status": "preparing"
}

Status Disponíveis

Status	Descrição
pending	Pendente
confirmed	Confirmado
preparing	Em preparo
ready	Pronto
delivered	Entregue
cancelled	Cancelado

Campos Adicionais no Modelo

Campo	Tipo	Descrição
pdv	ObjectId?	Referência à filial que criou o pedido
paymentMethod	string?	cash | credit_card | debit_card | pix | voucher | mixed
isSplitBill	boolean	Se é parte de uma conta dividida
splitBillReference	string?	Número do pedido pai na divisão
pixPayload	string?	Payload PIX para geração do QR code
pixQrCodeBase64	string?	QR code PIX em base64
paymentGateway	string?	Gateway utilizado: mock ou stone
paymentTransactionId	string?	ID da transação no gateway externo
paymentStatus	string?	processing | approved | declined
paymentAttempts	number	Contador de tentativas de pagamento (inicia em 0)
receiptToken	string?	Token único para acesso ao comprovante (expiração: 10 min)