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)

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

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

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)

✅ 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).