# 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
StatusSignificado
`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)
CampoTipoObrigatórioDescriçã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 comandaResultado
Não existeBloqueada (`NAO_ENCONTRADA`)
Já está em conferênciaBloqueada (`EM_CONFERENCIA`)
Está livreBloqueada (`STATUS_LIVRE`)
Está em consumo e há PDVs lançando itensBloqueada (`EM_LANCAMENTO_ITENS`)
Está em transferênciaBloqueada (`EM_TRANSFERENCIA`)
Está em consumo (sem bloqueios)✅ Elegível → status muda para `conferencia`
--- ## Response – Sucesso (200) ### Estrutura do retorno
```json { "comandasParaFaturar": [], "comandasBloqueadasParaFaturar": [] } ``` --- ## ✅ `comandasParaFaturar` Lista das comandas que **foram liberadas para faturamento**. ### Campos
CampoDescriçã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
```json { "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
CampoDescriçã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`
MotivoSignificado
`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. ```json { "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. ```json { "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
```json { "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`