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: chamado POST /api/v1/mesas-comandas/iniciar-faturamento (e recebido comandas em conferencia), e 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) Campo Tipo Obrigatório Descriçã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 { "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: { "comandasConfirmadasParaFaturar": [], "comandasBloqueadasParaConfirmar": [] } ✅ comandasConfirmadasParaFaturar Lista das comandas que foram liberadas/resetadas com sucesso. Campos Campo Descrição idMesa ID da comanda codigoComanda Código exibido ao operador statusAlteradoPara Sempre livre mensagem Texto explicativo Exemplo — 200 (todas liberadas) { "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 Campo Descriçã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) { "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) { "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) Motivo Significado 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).