Skip to main content

Nova Página

<!doctype html>
<html lang="pt-BR">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>API – Iniciar Faturamento de Comandas</title>
  <style>
    :root { color-scheme: light; }
    body { font-family: Arial, Helvetica, sans-serif; line-height: 1.5; margin: 24px; color: #111; }
    h1 { margin: 0 0 12px; }
    h2 { margin: 24px 0 10px; }
    h3 { margin: 18px 0 8px; }
    p { margin: 8px 0; }
    .endpoint { padding: 10px 12px; border: 1px solid #ddd; border-radius: 8px; background: #fafafa; display: inline-block; }
    .callout { border-left: 4px solid #f5b301; background: #fff8e6; padding: 10px 12px; border-radius: 6px; margin: 12px 0; }
    .ok { border-left-color: #2e7d32; background: #eef7ef; }
    .warn { border-left-color: #b26a00; background: #fff8e6; }
    .bad { border-left-color: #c62828; background: #fdecec; }
    table { width: 100%; border-collapse: collapse; margin: 10px 0; }
    th, td { border: 1px solid #ddd; padding: 8px; vertical-align: top; }
    th { background: #f3f3f3; text-align: left; }
    code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace; }
    pre { background: #0b1020; color: #e6e6e6; padding: 12px; border-radius: 10px; overflow: auto; }
    .small { font-size: 0.95rem; color: #333; }
    ul { margin: 8px 0 8px 22px; }
    .badge { display:inline-block; padding:2px 8px; border-radius:999px; background:#eee; font-size: 12px; }
  </style>
</head>
<body>

  <header>
    <h1>

📌 API – Iniciar Faturamento de Comandas</h1>

Endpoint:
    <p class="endpoint"><strong>Endpoint:</strong> <code>POST /api/v1/mesas-comandas/iniciar-faturamento</code></p>
  </header>

 <section>
    <h2>

🎯 Objetivo da API</h2>

  <p>
     

Esta API permite que um PDV solicite ao Servidor de Comandas o início do faturamento de uma ou mais comandas,
 comandas, possibilitando que elas sejam pagas juntas em uma única venda.
    </p>

    <p><strong>O Servidor de Comandas:</strong></p>

    <ul>
  •     <li>

    valida cada comanda solicitada;</li>

    • <li>

  • trava (coloca em <code>conferencia</code>) apenas as comandas que podem ser faturadas;</li>

    • <li>

  • retorna os itens da comanda para o PDV montar a venda;</li>

    • <li>

  • retorna também as comandas que não puderam ser faturadas,faturadas, com o motivo.</li>
        </ul>

    <div class="callout warn">
      <p><strong>⚠️ Importante:</strong><br/>
        A API permite sucesso parcial. 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.
      </p>
    </div>
  </section>

 <section>
    <h2>

🧠 Conceitos importantes (antes de integrar)</h2>

    <h3>

Status da comanda</h3>

<table>
<thead>
<tr>
<th>Status</th>
<th>Significado</th>
</tr>
    </thead>
      <tbody>
        <tr>
          <td><code>consumo</code></td>
          <td></tr>
<tr>
          <td><code>conferencia</code></td>
          <td></tr>
<tr>
          <td><code>livre</code></td>
          <td></tr>
<tr>
          <td><code>transferencia</code></td>
          <td>
Status Significado
consumo Comanda em uso, com itens lançados</td>
conferencia Comanda travada para faturamento em um PDV</td>
livre Comanda sem itens ou já finalizada</td>
transferencia Comanda em processo de transferência</td>

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
numeroMesasnumber[]✅IDs das comandas que o PDV deseja faturar
numeroPdvstring✅Identificação do PDV solicitante
operador_idstring✅Identificação do operador

Exemplo de requisição


</tr>
{ "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)

Quando acontece?

Quando pelo menos uma comanda pôde ser colocada em conferencia.

Estrutura do retorno


</t
{ "comandasParaFaturar": [], "comandasBloqueadasParaFaturar": [] }

✅ comandasParaFaturar

Lista das comandas que foram liberadas para faturamento.

Campos

CampoDescrição
idMesaID da comanda
codigoComandaCódigo exibido ao operador
statusAlteradoParaSempre conferencia
totalComandaSoma dos itens não cancelados
itensLista 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

CampoDescrição
idMesaID da comanda (quando existir)
codigoComandaCódigo da comanda
statusAtualStatus atual da comanda
motivoCódigo do bloqueio
mensagemTexto explicativo
numeroPdvEmConferenciaPDV que está usando a comanda (quando aplicável)
pos_lancandoPDVs lançando itens (quando aplicável)

🧾 Enum motivo

MotivoSignificado
EM_CONFERENCIAComanda já está sendo faturada
STATUS_LIVREComanda está livre/sem itens
NAO_ENCONTRADAComanda inexistente
EM_LANCAMENTO_ITENSExistem PDVs lançando itens
EM_TRANSFERENCIAComanda em transferência
STATUS_INVALIDOStatus não permitido
SEM_ITENSComanda sem itens (quando aplicável)

❌ Response – Erro (422 ou 409)

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."
    }
  ]
}

✅ 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

Back to top