API para buscar comanda a ser faturada. 📌 API – Iniciar Faturamento de Comandas Endpoint: POST /api/v1/mesas-comandas/iniciar-faturamento 🎯 Objetivo da API Esta API permite que um PDV solicite ao Servidor de Comandas o início do faturamento de uma ou mais comandas, possibilitando que elas sejam pagas juntas em uma única venda. O Servidor de Comandas: valida cada comanda solicitada; trava (coloca em conferencia) apenas as comandas que podem ser faturadas; retorna os itens da comanda para o PDV montar a venda; retorna também as comandas que não puderam ser faturadas, com o motivo. ⚠️ Importante: A API permite sucesso parcial. Se 3 comandas forem enviadas e apenas 2 puderem ser faturadas, essas 2 serão liberadas para faturamento e a outra será retornada como bloqueada. 🧠 Conceitos importantes (antes de integrar) Status da comanda Status Significado consumo Comanda em uso, com itens lançados conferencia Comanda travada para faturamento em um PDV livre Comanda sem itens ou já finalizada transferencia Comanda em processo de transferência Regras gerais Nunca existe faturamento parcial de itens: ou a comanda entra inteira ou não entra. Itens cancelados sempre são retornados, mas não entram no total. O PDV não recalcula valores: deve confiar nos valores retornados pela API. 🔐 Autenticação Segue o padrão de autenticação do Servidor de Comandas (definido pelo projeto). Caso a autenticação falhe, a API retornará erro HTTP (401/403). 📥 Request Body (JSON) Campo Tipo Obrigatório Descrição numeroMesas number[] ✅ IDs das comandas que o PDV deseja faturar numeroPdv string ✅ Identificação do PDV solicitante operador_id string ✅ Identificação do operador Exemplo de requisição { "numeroMesas": [4069, 4070, 4075], "numeroPdv": "12", "operador_id": "1275" } ⚙️ O que o servidor faz ao receber a requisição Para cada comanda enviada, o servidor avalia: Situação da comanda Resultado Não existe Bloqueada ( NAO_ENCONTRADA) Já está em conferência Bloqueada ( EM_CONFERENCIA) Está livre Bloqueada ( STATUS_LIVRE) Está em consumo e há PDVs lançando itens Bloqueada ( EM_LANCAMENTO_ITENS) Está em transferência Bloqueada ( EM_TRANSFERENCIA) Está em consumo (sem bloqueios) ✅ Elegível → status muda para conferencia Response – Sucesso (200) Estrutura do retorno { "comandasParaFaturar": [], "comandasBloqueadasParaFaturar": [] } ✅ comandasParaFaturar Lista das comandas que foram liberadas para faturamento. Campos Campo Descrição idMesa ID da comanda codigoComanda Código exibido ao operador statusAlteradoPara Sempre conferencia totalComanda Soma dos itens não cancelados itens Lista de itens da comanda Regras do total totalComanda = soma de preco_total somente dos itens com cancelado = false Estrutura de um item { "id": 34, "usuario_lancamento": "1275895", "produto_id": 9381649, "ean": "00000000100700", "descricao_resumida": "PROD TESTE 01", "quantidade": 1, "valorTotalAcrescimo": 10, "valorTotalDesconto": 0, "cancelado": false, "cancelado_por": null, "preco_unitario": 15, "preco_total": 25, "data_hora": "27/01/2026, 11:03:12" } ⚠️ Itens cancelados cancelado = true Não entram no total Servem apenas para auditoria/relatórios preco_total é apenas informativo 🚫 comandasBloqueadasParaFaturar Lista das comandas que não puderam ser faturadas. Campos Campo Descrição idMesa ID da comanda (quando existir) codigoComanda Código da comanda statusAtual Status atual da comanda motivo Código do bloqueio mensagem Texto explicativo numeroPdvEmConferencia PDV que está usando a comanda (quando aplicável) pos_lancando PDVs lançando itens (quando aplicável) 🧾 Enum motivo Motivo Significado EM_CONFERENCIA Comanda já está sendo faturada STATUS_LIVRE Comanda está livre/sem itens NAO_ENCONTRADA Comanda inexistente EM_LANCAMENTO_ITENS Existem PDVs lançando itens EM_TRANSFERENCIA Comanda em transferência STATUS_INVALIDO Status não permitido SEM_ITENS Comanda sem itens (quando aplicável) Response – Sucesso (200) contendo apenas comandas aptas a faturar. { "comandasParaFaturar": [ { "idMesa": 4069, "codigoComanda": "21", "statusAlteradoPara": "conferencia",     "totalComanda": 31.50, "itens": [ { "id": 34, "usuario_lancamento": "1275895", "produto_id": 9381649, "ean": "00000000100700", "descricao_resumida": "PROD TESTE 01", "quantidade": 1, "valorTotalAcrescimo": 10, "valorTotalDesconto": 0, "cancelado": false, "cancelado_por": null, "preco_unitario": 15, "preco_total": 25, "data_hora": "27/01/2026, 11:03:12" }, { "id": 35, "usuario_lancamento": "1275895", "produto_id": 9381647, "ean": "00000000100670", "descricao_resumida": "PROD TESTE 40", "quantidade": 1, "valorTotalAcrescimo": 0, "valorTotalDesconto": 0, "cancelado": false, "cancelado_por": null, "preco_unitario": 6.5, "preco_total": 6.5, "data_hora": "27/01/2026, 11:03:12" }, { "id": 36, "usuario_lancamento": "1275895", "produto_id": 8104916, "ean": "00000001267532", "descricao_resumida": "10 OVO", "quantidade": 1,         "valorTotalAcrescimo": 0, "valorTotalDesconto": 0, "cancelado": true, "cancelado_por": "1275895", "preco_unitario": 50, "preco_total": 50, "data_hora": "27/01/2026, 11:07:01" } ] } ], "comandasBloqueadasParaFaturar": [] } Response – Sucesso (200) contendo comandas aptas e não aptas a faturar. { "comandasParaFaturar": [ { "idMesa": 4069, "codigoComanda": "21", "statusAlteradoPara": "conferencia",     "totalComanda": 31.50, "itens": [ { "id": 34, "usuario_lancamento": "1275895", "produto_id": 9381649, "ean": "00000000100700", "descricao_resumida": "PROD TESTE 01", "quantidade": 1, "valorTotalAcrescimo": 10, "valorTotalDesconto": 0, "cancelado": false, "cancelado_por": null, "preco_unitario": 15, "preco_total": 25, "data_hora": "27/01/2026, 11:03:12" }, { "id": 35, "usuario_lancamento": "1275895", "produto_id": 9381647, "ean": "00000000100670", "descricao_resumida": "PROD TESTE 40", "quantidade": 1, "valorTotalAcrescimo": 0, "valorTotalDesconto": 0, "cancelado": false, "cancelado_por": null, "preco_unitario": 6.5, "preco_total": 6.5, "data_hora": "27/01/2026, 11:03:12" }, { "id": 36, "usuario_lancamento": "1275895", "produto_id": 8104916, "ean": "00000001267532", "descricao_resumida": "10 OVO", "quantidade": 1,         "valorTotalAcrescimo": 0, "valorTotalDesconto": 0, "cancelado": true, "cancelado_por": "1275895", "preco_unitario": 50, "preco_total": 50, "data_hora": "27/01/2026, 11:07:01" } ] } ], "comandasBloqueadasParaFaturar": [ { "idMesa": 4070, "codigoComanda": "22", "statusAtual": "conferencia", "motivo": "EM_CONFERENCIA",     "numeroPdvEmConferencia": "12", "mensagem": "Comanda já está em conferência." }, { "idMesa": 4071, "codigoComanda": "23", "statusAtual": "livre", "motivo": "STATUS_LIVRE", "mensagem": "Comanda está livre e sem itens a faturar." }, { "codigoComanda": "23", "mensagem": "Comanda não encontrada" } ] }  Response – 200 - Nenhuma comanda apta a faturar.   Quando acontece? Quando nenhuma comanda enviada pode ser faturada. Comportamento esperado do PDV Não montar a venda Exibir os motivos ao operador Encerrar o fluxo Exemplo { "comandasParaFaturar": [], "comandasBloqueadasParaFaturar": [ { "idMesa": 4070, "codigoComanda": "22", "statusAtual": "conferencia", "motivo": "EM_CONFERENCIA",     "numeroPdvEmConferencia": "12", "mensagem": "Comanda já está em conferência." }, { "idMesa": 4072, "codigoComanda": "23", "statusAtual": "livre", "motivo": "STATUS_LIVRE", "mensagem": "Comanda está livre e sem itens a faturar." }, { "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": "25", "statusAtual": "transferencia", "motivo": "EM_TRANSFERENCIA", "mensagem": "Comanda está em transferência de itens." },    { "codigoComanda": "1231", "motivo": "NAO_ENCONTRADA", "mensagem": "Comanda não encontrada."    } ] } ✅ Boas práticas para quem integra (PDV) Sempre trate sucesso parcial Nunca recalcular valores Não tente faturar comandas bloqueadas Guarde localmente as comandas que entraram em conferencia Use essa lista depois para: confirmar-faturamento cancelar-faturamento