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:

1. PDV chama iniciar-faturamento → recebe comandasParaFaturar (essas entram em conferencia)

2. PDV tenta concluir a venda (pagamento/emissão fiscal são do PDV)

3. 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)

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:

---

📤 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:

---

comandasBloqueadasParaCancelar[] (bloqueios)

Lista de comandas que não puderam ser canceladas:

---

✅ 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.