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>
 

  <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>Comanda em uso, com itens lançados</td>
        </tr>
        <tr>
          <td><code>conferencia</code></td>
          <td>Comanda travada para faturamento em um PDV</td>
        </tr>
        <tr>
          <td><code>livre</code></td>
          <td>Comanda sem itens ou já finalizada</td>
        </tr>
        <tr>
          <td><code>transferencia</code></td>
          <td>Comanda em processo de transferência</td>
        </tr>
     

Regras gerais

    Nunca existe faturamento parcial de itens: ou a comanda entra inteira ou não entra.</t

    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)

    Quando acontece?

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

    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 – 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