# API para liberar as comandas após finalizar a venda. # 📌 API – Confirmar Faturamento (Liberar/Resetar Comandas) **Endpoint:** `POST /api/v1/mesas-comandas/confirmar-faturamento` --- ## 🎯 Objetivo da API Esta API é utilizada pelo **PDV** ao final do atendimento para **liberar (resetar)** uma ou mais comandas que estavam em **`conferencia`**, tornando-as **`livre`** novamente para um novo cliente. ✅ O que essa API faz no Servidor de Comandas (para cada comanda liberada): - apaga **itens** associados à comanda; - apaga **pagamentos** associados (se existirem); - limpa/zera informações associadas à mesa/comanda (mesma lógica do `liberar-mesa`); - altera o status para **`livre`**. 🚫 O que essa API **NÃO faz**: - não recebe dados fiscais; - não recebe pagamentos; - não valida NFC-e/NF-e; - não emite documento fiscal. > Pagamento e emissão fiscal são responsabilidades do PDV e não são enviados ao Servidor de Comandas. --- ## 🧠 Quando usar (fluxo do integrador) Use esta API **apenas após** o PDV ter: 1. chamado `POST /api/v1/mesas-comandas/iniciar-faturamento` (e recebido comandas em `conferencia`), e 2. finalizado o atendimento no PDV. 📌 **Recomendação prática**: Envie em `confirmar-faturamento` **somente as comandas que o servidor retornou em `comandasParaFaturar`** (ou seja, as que realmente entraram em `conferencia`). --- ## 🔐 Autenticação Segue o **padrão de autenticação do Servidor de Comandas** (não detalhado no cartão). > Quando você definir/passar o padrão, incluo aqui (JWT, x-api-key, etc.). --- ## 📥 Request ### Body (JSON)
CampoTipoObrigatórioDescrição
`numeroMesas``number[]`✅Lista de mesas/comandas a serem liberadas/resetadas
`numeroPdv``string`✅Identificação do PDV solicitante
`operador_id``string`✅Identificação do operador solicitante
### Exemplo
```json { "numeroMesas": [4069, 4070, 4075], "numeroPdv": "12", "operador_id": "1275" } ``` --- ## ⚙️ Regras de validação (por comanda) Para cada `idMesa` em `numeroMesas`: ### 1) Comanda não existe - Vai para `comandasBloqueadasParaConfirmar` - `motivo = NAO_ENCONTRADA` ### 2) Comanda está em `conferencia` - Pode liberar, **desde que**: - se existir `numeroPdvEmConferencia` e ele for **diferente** do `numeroPdv` do request → bloquear: - `motivo = EM_CONFERENCIA_OUTRO_PDV` - retornar `numeroPdvEmConferencia` - caso contrário → liberar com sucesso ### 3) Comanda está `livre` - Bloquear: - `motivo = STATUS_LIVRE` (já está disponível) ### 4) Comanda está `consumo` - Se tiver `pos_lancando` → bloquear: - `motivo = EM_LANCAMENTO_ITENS` - retornar `pos_lancando` - Se **não** tiver `pos_lancando` → bloquear: - `motivo = NAO_ESTA_EM_CONFERENCIA` - (porque não é uma comanda travada para faturamento do PDV Linux) ### 5) Comanda está `transferencia` - Bloquear: - `motivo = EM_TRANSFERENCIA` ### 6) Outros status - Bloquear: - `motivo = STATUS_INVALIDO` > Observação importante: mesmo parecendo “reset”, a regra do fluxo do PDV Linux é **liberar somente o que estava em conferência**, para reduzir risco de liberar mesa errada. --- ## 📤 Response – Sucesso (200) ### Quando acontece? Quando **pelo menos 1 comanda** foi liberada/resetada com sucesso. ### Estrutura do retorno A API sempre retorna duas listas:
```json { "comandasConfirmadasParaFaturar": [], "comandasBloqueadasParaConfirmar": [] } ``` --- ## ✅ `comandasConfirmadasParaFaturar` Lista das comandas que foram **liberadas/resetadas** com sucesso. ### Campos
CampoDescrição
`idMesa`ID da comanda
`codigoComanda`Código exibido ao operador
`statusAlteradoPara`Sempre `livre`
`mensagem`Texto explicativo
### Exemplo — 200 (todas liberadas)
```json { "comandasConfirmadasParaFaturar": [ { "idMesa": 4069, "codigoComanda": "21", "statusAlteradoPara": "livre", "mensagem": "Comanda liberada com sucesso." }, { "idMesa": 4070, "codigoComanda": "22", "statusAlteradoPara": "livre", "mensagem": "Comanda liberada com sucesso." } ], "comandasBloqueadasParaConfirmar": [] } ``` --- ## 🚫 `comandasBloqueadasParaConfirmar` Lista das comandas que **não puderam** ser liberadas. ### Campos
CampoDescrição
`idMesa`ID da comanda (quando existir)
`codigoComanda`Código da comanda (quando existir)
`statusAtual`Status atual da comanda (quando existir)
`motivo`Código padronizado do bloqueio
`mensagem`Mensagem explicativa
`numeroPdvEmConferencia`Somente quando `motivo = EM_CONFERENCIA_OUTRO_PDV`
`pos_lancando`Somente quando `motivo = EM_LANCAMENTO_ITENS`
### Exemplo — 200 (parcial)
```json { "comandasConfirmadasParaFaturar": [ { "idMesa": 4069, "codigoComanda": "21", "statusAlteradoPara": "livre", "mensagem": "Comanda liberada com sucesso." } ], "comandasBloqueadasParaConfirmar": [ { "idMesa": 4070, "codigoComanda": "22", "statusAtual": "conferencia", "motivo": "EM_CONFERENCIA_OUTRO_PDV", "numeroPdvEmConferencia": "15", "mensagem": "Comanda está em conferência por outro PDV." }, { "idMesa": 4073, "codigoComanda": "24", "statusAtual": "consumo", "motivo": "EM_LANCAMENTO_ITENS", "pos_lancando": [1, 2], "mensagem": "Comanda está em consumo tendo lançamento de itens." }, { "codigoComanda": "1231", "motivo": "NAO_ENCONTRADA", "mensagem": "Comanda não encontrada." } ] } ``` --- ## Response – (200 Quando **nenhuma comanda** enviada pôde ser liberada/resetada.) ### Quando acontece? Quando **nenhuma comanda** enviada pôde ser liberada/resetada. ### Comportamento esperado do PDV - considerar que **nenhuma mesa foi liberada**; - exibir os motivos ao operador; - seguir procedimento operacional (ex.: tratativa gerencial/manual quando necessário). ### Exemplo — 200 (nenhuma liberada)
```json { "comandasConfirmadasParaFaturar": [], "comandasBloqueadasParaConfirmar": [ { "idMesa": 4070, "codigoComanda": "22", "statusAtual": "conferencia", "motivo": "EM_CONFERENCIA_OUTRO_PDV", "numeroPdvEmConferencia": "15", "mensagem": "Comanda está em conferência por outro PDV." }, { "idMesa": 4073, "codigoComanda": "24", "statusAtual": "consumo", "motivo": "EM_LANCAMENTO_ITENS", "pos_lancando": [1, 2], "mensagem": "Comanda está em consumo tendo lançamento de itens." }, { "idMesa": 4071, "codigoComanda": "23", "statusAtual": "livre", "motivo": "STATUS_LIVRE", "mensagem": "Comanda já está livre." }, { "codigoComanda": "1231", "motivo": "NAO_ENCONTRADA", "mensagem": "Comanda não encontrada." } ] } ``` --- ## 🧾 Enum `motivo` (mínimo)
MotivoSignificado
`NAO_ENCONTRADA`Comanda não existe
`STATUS_LIVRE`Comanda já está livre
`NAO_ESTA_EM_CONFERENCIA`Comanda não está em conferência (não é do fluxo de faturamento)
`EM_CONFERENCIA_OUTRO_PDV`Comanda está em conferência por outro PDV
`EM_TRANSFERENCIA`Comanda em transferência
`EM_LANCAMENTO_ITENS`Comanda em consumo com lançamento de itens em andamento
`STATUS_INVALIDO`Status não permitido
## ✅ Boas práticas para quem integra (PDV) - Chame `confirmar-faturamento` **somente** para comandas que você recebeu em `comandasParaFaturar` no `iniciar-faturamento`. - Sempre trate **retorno parcial**: - confirme/libere as que vierem em `comandasConfirmadasParaFaturar` - exiba e trate operacionalmente as bloqueadas - Não tente “forçar” liberação de comanda em conferência de outro PDV via esta API (isso deve ser endpoint administrativo/gerencial).