# 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)
CampoTipoObrigatórioDescriçã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
```json { "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çãoMotivoCampo 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
```json { "comandasCanceladasParaFaturar": [], "comandasBloqueadasParaCancelar": [] } ``` --- ### `comandasCanceladasParaFaturar[]` (sucesso) Lista de comandas que foram efetivamente destravadas:
CampoDescriçã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:
CampoDescriçã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) ```json { "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)
```json { "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
```json { "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.