API para voltar o status da comanda para consumo após abortar operação. 📌 API – Cancelar Faturamento de Comandas Endpoint: POST /api/v1/mesas-comandas/cancelar-faturamento 🎯 Para que serve Esta API é usada quando o PDV iniciou o faturamento de uma ou mais comandas (elas ficaram em conferencia ) mas o atendimento NÃO foi concluído . Ao chamar esta API, o Servidor de Comandas: remove a trava de faturamento; altera o status da comanda de conferencia → consumo ; registra auditoria do cancelamento. ✅ Use quando: o operador cancelou a venda no PDV; houve erro antes de concluir o atendimento (ex.: falha de cadastro de item); o cliente desistiu antes de finalizar. 🚫 Não use quando: a venda foi concluída e você quer liberar a comanda para novo cliente → use confirmar-faturamento . 🔁 Onde entra no fluxo do PDV Fluxo típico: PDV chama iniciar-faturamento → recebe comandasParaFaturar (essas entram em conferencia ) PDV tenta concluir a venda (pagamento/emissão fiscal são do PDV) Se desistiu/cancelou → chama cancelar-faturamento enviando somente as mesas que entraram em conferência ⚠️ Boa prática obrigatória: Envie para cancelar-faturamento somente as comandas que retornaram em comandasParaFaturar no iniciar-faturamento . 🔐 Autenticação Segue o padrão de autenticação do Servidor de Comandas (definido pelo projeto). Se houver falha, o servidor retornará HTTP 401/403. 📥 Request Body (JSON) Campo Tipo Obrigatório Descrição numeroMesas number[] ✅ IDs das comandas a cancelar (em lote) numeroPdv string ✅ Número/identificação do PDV solicitante operador_id string ✅ Identificação do operador solicitante Exemplo { "numeroMesas": [4069, 4070, 4075], "numeroPdv": "12", "operador_id": "1275" } ✅ O que o servidor faz (regras por comanda) O servidor avalia cada idMesa individualmente e pode cancelar algumas e bloquear outras (retorno parcial). Quando a comanda é cancelada com sucesso Se status = conferencia e (se existir) numeroPdvEmConferencia == numeroPdv do request → servidor altera status para consumo e retorna em comandasCanceladasParaFaturar . Quando a comanda é bloqueada A comanda entra em comandasBloqueadasParaCancelar nos casos: Situação Motivo Campo extra Comanda não existe NAO_ENCONTRADA — status = conferencia por outro PDV EM_CONFERENCIA_OUTRO_PDV numeroPdvEmConferencia status = consumo NAO_ESTA_EM_CONFERENCIA — status = livre STATUS_LIVRE — status = transferencia EM_TRANSFERENCIA — status = consumo com lançamento em andamento EM_LANCAMENTO_ITENS pos_lancando qualquer outro status STATUS_INVALIDO — 📤 Response ✅ 200 – Cancelamento total ou parcial Retorna 200 quando pelo menos 1 comanda foi cancelada com sucesso. Estrutura { "comandasCanceladasParaFaturar": [], "comandasBloqueadasParaCancelar": [] } comandasCanceladasParaFaturar[] (sucesso) Lista de comandas que foram efetivamente destravadas: Campo Descrição idMesa ID da comanda codigoComanda Código/identificador da comanda statusAlteradoPara Sempre "consumo" mensagem Mensagem para exibição/log comandasBloqueadasParaCancelar[] (bloqueios) Lista de comandas que não puderam ser canceladas: Campo Descrição idMesa ID da comanda (quando existir) codigoComanda Código da comanda (quando existir) statusAtual Status atual (quando existir) motivo Código do bloqueio mensagem Mensagem explicativa numeroPdvEmConferencia Apenas quando EM_CONFERENCIA_OUTRO_PDV pos_lancando Apenas quando EM_LANCAMENTO_ITENS ✅ Exemplo — 200 (cancelamento completo) { "comandasCanceladasParaFaturar": [ { "idMesa": 4069, "codigoComanda": "21", "statusAlteradoPara": "consumo", "mensagem": "Faturamento cancelado com sucesso. Comanda retornou para consumo." }, { "idMesa": 4070, "codigoComanda": "22", "statusAlteradoPara": "consumo", "mensagem": "Faturamento cancelado com sucesso. Comanda retornou para consumo." } ], "comandasBloqueadasParaCancelar": [] } ✅ Exemplo — 200 (parcial) { "comandasCanceladasParaFaturar": [ { "idMesa": 4069, "codigoComanda": "21", "statusAlteradoPara": "consumo", "mensagem": "Faturamento cancelado com sucesso. Comanda retornou para consumo." } ], "comandasBloqueadasParaCancelar": [ { "idMesa": 4070, "codigoComanda": "22", "statusAtual": "conferencia", "motivo": "EM_CONFERENCIA_OUTRO_PDV", "numeroPdvEmConferencia": "15", "mensagem": "Comanda está em conferência por outro PDV." }, { "idMesa": 4072, "codigoComanda": "24", "statusAtual": "transferencia", "motivo": "EM_TRANSFERENCIA", "mensagem": "Comanda está em transferência de itens e não pode ser cancelada." } ] } 200 — nenhuma comanda cancelável Retorna erro quando 0 comandas puderam ser canceladas. Exemplo — 200 { "comandasCanceladasParaFaturar": [], "comandasBloqueadasParaCancelar": [ { "idMesa": 4070, "codigoComanda": "22", "statusAtual": "livre", "motivo": "STATUS_LIVRE", "mensagem": "Comanda está livre e não possui faturamento para cancelar." }, { "idMesa": 4073, "codigoComanda": "26", "statusAtual": "consumo", "motivo": "NAO_ESTA_EM_CONFERENCIA", "mensagem": "Comanda não está em conferência." }, { "codigoComanda": "9999", "motivo": "NAO_ENCONTRADA", "mensagem": "Comanda não encontrada." } ] } 🧾 Enum motivo (mínimo) NAO_ENCONTRADA NAO_ESTA_EM_CONFERENCIA STATUS_LIVRE EM_TRANSFERENCIA EM_LANCAMENTO_ITENS EM_CONFERENCIA_OUTRO_PDV STATUS_INVALIDO ✅ Boas práticas para integradores (PDV) Sempre trate retorno parcial . Envie apenas as comandas que você recebeu em comandasParaFaturar no iniciar-faturamento . Se vier EM_CONFERENCIA_OUTRO_PDV , isso é tratativa gerencial/manual (não tente “resolver” pelo PDV). Após cancelar, o PDV deve: limpar o contexto da venda local; permitir que a comanda seja faturada novamente.