Skip to main content

Nova Página

📌 API – Iniciar Faturamento de Comandas

Endpoint:
POST /api/v1/mesas-comandas/iniciar-faturamento

🎯 Objetivo da API

Esta API permite que um PDV solicite ao Servidor de Comandas o início do faturamento de uma ou mais comandas, possibilitando que elas sejam pagas juntas em uma única venda.

O Servidor de Comandas:

  • valida cada comanda solicitada;

  • trava (coloca em conferencia) apenas as comandas que podem ser faturadas;

  • retorna os itens da comanda para o PDV montar a venda;

  • retorna também as comandas que não puderam ser faturadas, com o motivo.

⚠️ Importante:
A API permite sucesso parcial.
Se 3 comandas forem enviadas e apenas 2 puderem ser faturadas, essas 2 serão liberadas para faturamento e a outra será retornada como bloqueada.

🧠 Conceitos importantes (antes de integrar)

Status da comanda

Status Significado
consumo Comanda em uso, com itens lançados
conferencia Comanda travada para faturamento em um PDV
livre Comanda sem itens ou já finalizada
transferencia Comanda em processo de transferência

Regras gerais

  • Nunca existe faturamento parcial de itens: ou a comanda entra inteira ou não entra.

  • Itens cancelados sempre são retornados, mas não entram no total.

  • O PDV não recalcula valores: deve confiar nos valores retornados pela API.

🔐 Autenticação

Segue o padrão de autenticação do Servidor de Comandas (definido pelo projeto).

Caso a autenticação falhe, a API retornará erro HTTP (401/403).

📥 Request

Body (JSON)

Campo Tipo Obrigatório Descrição
numeroMesas number[] ✅ IDs das comandas que o PDV deseja faturar
numeroPdv string ✅ Identificação do PDV solicitante
operador_id string ✅ Identificação do operador

Exemplo de requisição


{ "numeroMesas": [4069, 4070, 4075], "numeroPdv": "12", "operador_id": "1275" } 
{
  "numeroMesas": [4069, 4070, 4075],
  "numeroPdv": "12",
  "operador_id": "1275"
}

⚙️ O que o servidor faz ao receber a requisição

Para cada comanda enviada, o servidor avalia:

Situação da comanda Resultado
Não existe Bloqueada (NAO_ENCONTRADA)
Já está em conferência Bloqueada (EM_CONFERENCIA)
Está livre Bloqueada (STATUS_LIVRE)
Está em consumo e há PDVs lançando itens Bloqueada (EM_LANCAMENTO_ITENS)
Está em transferência Bloqueada (EM_TRANSFERENCIA)
Está em consumo (sem bloqueios) ✅ Elegível → status muda para conferencia

📤 Response – Sucesso (200)

Quando acontece?

Quando pelo menos uma comanda pôde ser colocada em conferencia.

Estrutura do retorno


{ "comandasParaFaturar": [], "comandasBloqueadasParaFaturar": [] } 
{
  "comandasParaFaturar": [],
  "comandasBloqueadasParaFaturar": []
}

✅ comandasParaFaturar

Lista das comandas que foram liberadas para faturamento.

Campos

Campo Descrição
idMesa ID da comanda
codigoComanda Código exibido ao operador
statusAlteradoPara Sempre conferencia
totalComanda Soma dos itens não cancelados
itens Lista de itens da comanda

Regras do total

  • totalComanda = soma de preco_total somente dos itens com cancelado = false

Estrutura de um item


{
  "id": 34,34,
  "usuario_lancamento": "1275895",
  "produto_id": 9381649,9381649,
  "ean": "00000000100700",
  "descricao_resumida": "PROD TESTE 01",
  "quantidade": 1,1,
  "valorTotalAcrescimo": 10,10,
  "valorTotalDesconto": 0,0,
  "cancelado": false,false,
  "cancelado_por": null,null,
  "preco_unitario": 15,15,
  "preco_total": 25,25,
  "data_hora": "27/01/2026, 11:03:12"
}

⚠️ Itens cancelados

  • cancelado = true

  • Não entram no total

  • Servem apenas para auditoria/relatórios

  • preco_total é apenas informativo

🚫 comandasBloqueadasParaFaturar

Lista das comandas que não puderam ser faturadas.

Campos

Campo Descrição
idMesa ID da comanda (quando existir)
codigoComanda Código da comanda
statusAtual Status atual da comanda
motivo Código do bloqueio
mensagem Texto explicativo
numeroPdvEmConferencia PDV que está usando a comanda (quando aplicável)
pos_lancando PDVs lançando itens (quando aplicável)

🧾 Enum motivo

Motivo Significado
EM_CONFERENCIA Comanda já está sendo faturada
STATUS_LIVRE Comanda está livre/sem itens
NAO_ENCONTRADA Comanda inexistente
EM_LANCAMENTO_ITENS Existem PDVs lançando itens
EM_TRANSFERENCIA Comanda em transferência
STATUS_INVALIDO Status não permitido
SEM_ITENS Comanda sem itens (quando aplicável)

❌ Response – Erro (422 ou 409)422)

Quando acontece?

Quando nenhuma comanda enviada pode ser faturada.

Comportamento esperado do PDV

  • Não montar a venda

  • Exibir os motivos ao operador

  • Encerrar o fluxo

Exemplo


{
  "comandasParaFaturar": [],
  "comandasBloqueadasParaFaturar": [
    {
      "idMesa": 4070,
      "codigoComanda": "22",
      "statusAtual": "conferencia",
      "motivo": "EM_CONFERENCIA",
      "numeroPdvEmConferencia": "12",
      "mensagem": "Comanda já está em conferência."
    }
  ]
}

✅ Boas práticas para quem integra (PDV)

  • Sempre trate sucesso parcial

  • Nunca recalcular valores

  • Não tente faturar comandas bloqueadas

  • Guarde localmente as comandas que entraram em conferencia

  • Use essa lista depois para:

    • confirmar-faturamento

    • cancelar-faturamento

Back to top