# Integração Servidor Comandas

Documento de integração para utilizar as API's do servidor comandas.

# 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

<div class="TyagGW_tableContainer" id="bkmrk-status-significado-c"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Status</th><th>Significado</th></tr></thead><tbody><tr><td>`consumo`</td><td>Comanda em uso, com itens lançados</td></tr><tr><td>`conferencia`</td><td>Comanda travada para faturamento em um PDV</td></tr><tr><td>`livre`</td><td>Comanda sem itens ou já finalizada</td></tr><tr><td>`transferencia`</td><td>Comanda em processo de transferência</td></tr></tbody></table>

</div></div>### 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)

<div class="TyagGW_tableContainer" id="bkmrk-campo-tipo-obrigat%C3%B3r"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Campo</th><th>Tipo</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td>`numeroMesas`</td><td>`number[]`</td><td>✅</td><td>IDs das comandas que o PDV deseja faturar</td></tr><tr><td>`numeroPdv`</td><td>`string`</td><td>✅</td><td>Identificação do PDV solicitante</td></tr><tr><td>`operador_id`</td><td>`string`</td><td>✅</td><td>Identificação do operador</td></tr></tbody></table>

</div></div>### Exemplo de requisição

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--4"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr">  
</div></div>```
{
  "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:

<div class="TyagGW_tableContainer" id="bkmrk-situa%C3%A7%C3%A3o-da-comanda-"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Situação da comanda</th><th>Resultado</th></tr></thead><tbody><tr><td>Não existe</td><td>Bloqueada (`NAO_ENCONTRADA`)</td></tr><tr><td>Já está em conferência</td><td>Bloqueada (`EM_CONFERENCIA`)</td></tr><tr><td>Está livre</td><td>Bloqueada (`STATUS_LIVRE`)</td></tr><tr><td>Está em consumo e há PDVs lançando itens</td><td>Bloqueada (`EM_LANCAMENTO_ITENS`)</td></tr><tr><td>Está em transferência</td><td>Bloqueada (`EM_TRANSFERENCIA`)</td></tr><tr><td>Está em consumo (sem bloqueios)</td><td>✅ Elegível → status muda para `conferencia`</td></tr></tbody></table>

</div></div>---

## Response – Sucesso (200)

### Estrutura do retorno

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--7"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr">  
</div></div>```json
{
  "comandasParaFaturar": [],
  "comandasBloqueadasParaFaturar": []
}

```

---

## ✅ `comandasParaFaturar`

Lista das comandas que **foram liberadas para faturamento**.

### Campos

<div class="TyagGW_tableContainer" id="bkmrk-campo-descri%C3%A7%C3%A3o-idme"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr><td>`idMesa`</td><td>ID da comanda</td></tr><tr><td>`codigoComanda`</td><td>Código exibido ao operador</td></tr><tr><td>`statusAlteradoPara`</td><td>Sempre `conferencia`</td></tr><tr><td>`totalComanda`</td><td>Soma dos itens **não cancelados**</td></tr><tr><td>`itens`</td><td>Lista de itens da comanda</td></tr></tbody></table>

</div></div>### Regras do total

- `totalComanda` = soma de `preco_total` **somente dos itens com `cancelado = false`**

---

### Estrutura de um item

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--10"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr">  
</div></div>```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

<div class="TyagGW_tableContainer" id="bkmrk-campo-descri%C3%A7%C3%A3o-idme-1"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr><td>`idMesa`</td><td>ID da comanda (quando existir)</td></tr><tr><td>`codigoComanda`</td><td>Código da comanda</td></tr><tr><td>`statusAtual`</td><td>Status atual da comanda</td></tr><tr><td>`motivo`</td><td>Código do bloqueio</td></tr><tr><td>`mensagem`</td><td>Texto explicativo</td></tr><tr><td>`numeroPdvEmConferencia`</td><td>PDV que está usando a comanda (quando aplicável)</td></tr><tr><td>`pos_lancando`</td><td>PDVs lançando itens (quando aplicável)</td></tr></tbody></table>

</div></div>---

## 🧾 Enum `motivo`

<div class="TyagGW_tableContainer" id="bkmrk-motivo-significado-e"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Motivo</th><th>Significado</th></tr></thead><tbody><tr><td>`EM_CONFERENCIA`</td><td>Comanda já está sendo faturada</td></tr><tr><td>`STATUS_LIVRE`</td><td>Comanda está livre/sem itens</td></tr><tr><td>`NAO_ENCONTRADA`</td><td>Comanda inexistente</td></tr><tr><td>`EM_LANCAMENTO_ITENS`</td><td>Existem PDVs lançando itens</td></tr><tr><td>`EM_TRANSFERENCIA`</td><td>Comanda em transferência</td></tr><tr><td>`STATUS_INVALIDO`</td><td>Status não permitido</td></tr><tr><td>`SEM_ITENS`</td><td>Comanda sem itens (quando aplicável)</td></tr></tbody></table>

</div></div>## Response – Sucesso (200) <span class="text-big">contendo apenas comandas aptas a faturar.</span>

```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) <span class="text-big">contendo comandas aptas e não aptas a faturar</span><span class="text-big">.</span>

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

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--14"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr">  
</div></div>```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`

# 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)

<div class="TyagGW_tableContainer" id="bkmrk-campo-tipo-obrigat%C3%B3r"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Campo</th><th>Tipo</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td>`numeroMesas`</td><td>`number[]`</td><td>✅</td><td>Lista de mesas/comandas a serem liberadas/resetadas</td></tr><tr><td>`numeroPdv`</td><td>`string`</td><td>✅</td><td>Identificação do PDV solicitante</td></tr><tr><td>`operador_id`</td><td>`string`</td><td>✅</td><td>Identificação do operador solicitante</td></tr></tbody></table>

</div></div>### Exemplo

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--4"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr">  
</div></div>```json
{
  "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:

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--7"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr">  
</div></div>```json
{
  "comandasConfirmadasParaFaturar": [],
  "comandasBloqueadasParaConfirmar": []
}

```

---

## ✅ `comandasConfirmadasParaFaturar`

Lista das comandas que foram **liberadas/resetadas** com sucesso.

### Campos

<div class="TyagGW_tableContainer" id="bkmrk-campo-descri%C3%A7%C3%A3o-idme"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr><td>`idMesa`</td><td>ID da comanda</td></tr><tr><td>`codigoComanda`</td><td>Código exibido ao operador</td></tr><tr><td>`statusAlteradoPara`</td><td>Sempre `livre`</td></tr><tr><td>`mensagem`</td><td>Texto explicativo</td></tr></tbody></table>

</div></div>### Exemplo — 200 (todas liberadas)

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--9"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr">  
</div></div>```json
{
  "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

<div class="TyagGW_tableContainer" id="bkmrk-campo-descri%C3%A7%C3%A3o-idme-1"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr><td>`idMesa`</td><td>ID da comanda (quando existir)</td></tr><tr><td>`codigoComanda`</td><td>Código da comanda (quando existir)</td></tr><tr><td>`statusAtual`</td><td>Status atual da comanda (quando existir)</td></tr><tr><td>`motivo`</td><td>Código padronizado do bloqueio</td></tr><tr><td>`mensagem`</td><td>Mensagem explicativa</td></tr><tr><td>`numeroPdvEmConferencia`</td><td>Somente quando `motivo = EM_CONFERENCIA_OUTRO_PDV`</td></tr><tr><td>`pos_lancando`</td><td>Somente quando `motivo = EM_LANCAMENTO_ITENS`</td></tr></tbody></table>

</div></div>### Exemplo — 200 (parcial)

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--11"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr">  
</div></div>```json
{
  "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)

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--13"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr">  
</div></div>```json
{
  "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)

<div class="TyagGW_tableContainer" id="bkmrk-motivo-significado-n"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Motivo</th><th>Significado</th></tr></thead><tbody><tr><td>`NAO_ENCONTRADA`</td><td>Comanda não existe</td></tr><tr><td>`STATUS_LIVRE`</td><td>Comanda já está livre</td></tr><tr><td>`NAO_ESTA_EM_CONFERENCIA`</td><td>Comanda não está em conferência (não é do fluxo de faturamento)</td></tr><tr><td>`EM_CONFERENCIA_OUTRO_PDV`</td><td>Comanda está em conferência por outro PDV</td></tr><tr><td>`EM_TRANSFERENCIA`</td><td>Comanda em transferência</td></tr><tr><td>`EM_LANCAMENTO_ITENS`</td><td>Comanda em consumo com lançamento de itens em andamento</td></tr><tr><td>`STATUS_INVALIDO`</td><td>Status não permitido</td></tr></tbody></table>

</div></div>## ✅ 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).

# API para voltar o status da comanda para consumo após abortar operação.

# 📌 API – Cancelar Faturamento de Comandas

**Endpoint:**  
`POST /api/v1/mesas-comandas/cancelar-faturamento`

---

## 🎯 Para que serve

Esta API é usada quando o PDV **iniciou o faturamento** de uma ou mais comandas (elas ficaram em **`conferencia`**) mas **o atendimento NÃO foi concluído**.

Ao chamar esta API, o Servidor de Comandas:

- remove a trava de faturamento;
- altera o status da comanda de **`conferencia` → `consumo`**;
- registra auditoria do cancelamento.

✅ Use quando:

- o operador cancelou a venda no PDV;
- houve erro antes de concluir o atendimento (ex.: falha de cadastro de item);
- o cliente desistiu antes de finalizar.

🚫 Não use quando:

- a venda foi concluída e você quer liberar a comanda para novo cliente → use **`confirmar-faturamento`**.

---

## 🔁 Onde entra no fluxo do PDV

Fluxo típico:

1. PDV chama **`iniciar-faturamento`** → recebe `comandasParaFaturar` (essas entram em `conferencia`)
2. PDV tenta concluir a venda (pagamento/emissão fiscal são do PDV)
3. Se desistiu/cancelou → chama **`cancelar-faturamento`** enviando **somente as mesas que entraram em conferência**

> ⚠️ Boa prática obrigatória:  
> Envie para `cancelar-faturamento` **somente** as comandas que retornaram em `comandasParaFaturar` no `iniciar-faturamento`.

---

## 🔐 Autenticação

Segue o padrão de autenticação do Servidor de Comandas (definido pelo projeto).

> Se houver falha, o servidor retornará HTTP 401/403.

---

## 📥 Request

### Body (JSON)

<div class="TyagGW_tableContainer" id="bkmrk-campo-tipo-obrigat%C3%B3r"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Campo</th><th>Tipo</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td>`numeroMesas`</td><td>`number[]`</td><td>✅</td><td>IDs das comandas a cancelar (em lote)</td></tr><tr><td>`numeroPdv`</td><td>`string`</td><td>✅</td><td>Número/identificação do PDV solicitante</td></tr><tr><td>`operador_id`</td><td>`string`</td><td>✅</td><td>Identificação do operador solicitante</td></tr></tbody></table>

</div></div>### Exemplo

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--4"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr">  
</div></div>```json
{
  "numeroMesas": [4069, 4070, 4075],
  "numeroPdv": "12",
  "operador_id": "1275"
}

```

---

## ✅ O que o servidor faz (regras por comanda)

O servidor avalia **cada idMesa individualmente** e pode cancelar algumas e bloquear outras (retorno parcial).

### Quando a comanda é cancelada com sucesso

- Se `status = conferencia` **e** (se existir) `numeroPdvEmConferencia == numeroPdv` do request  
    → servidor altera status para `consumo` e retorna em `comandasCanceladasParaFaturar`.

### Quando a comanda é bloqueada

A comanda entra em `comandasBloqueadasParaCancelar` nos casos:

<div class="TyagGW_tableContainer" id="bkmrk-situa%C3%A7%C3%A3o-motivo-camp"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Situação</th><th>Motivo</th><th>Campo extra</th></tr></thead><tbody><tr><td>Comanda não existe</td><td>`NAO_ENCONTRADA`</td><td>—</td></tr><tr><td>`status = conferencia` por outro PDV</td><td>`EM_CONFERENCIA_OUTRO_PDV`</td><td>`numeroPdvEmConferencia`</td></tr><tr><td>`status = consumo`</td><td>`NAO_ESTA_EM_CONFERENCIA`</td><td>—</td></tr><tr><td>`status = livre`</td><td>`STATUS_LIVRE`</td><td>—</td></tr><tr><td>`status = transferencia`</td><td>`EM_TRANSFERENCIA`</td><td>—</td></tr><tr><td>`status = consumo` com lançamento em andamento</td><td>`EM_LANCAMENTO_ITENS`</td><td>`pos_lancando`</td></tr><tr><td>qualquer outro status</td><td>`STATUS_INVALIDO`</td><td>—</td></tr></tbody></table>

</div></div>---

## 📤 Response

### ✅ 200 – Cancelamento total ou parcial

Retorna **200** quando **pelo menos 1 comanda** foi cancelada com sucesso.

#### Estrutura

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--7"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr">  
</div></div>```json
{
  "comandasCanceladasParaFaturar": [],
  "comandasBloqueadasParaCancelar": []
}

```

---

### `comandasCanceladasParaFaturar[]` (sucesso)

Lista de comandas que foram efetivamente destravadas:

<div class="TyagGW_tableContainer" id="bkmrk-campo-descri%C3%A7%C3%A3o-idme"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr><td>`idMesa`</td><td>ID da comanda</td></tr><tr><td>`codigoComanda`</td><td>Código/identificador da comanda</td></tr><tr><td>`statusAlteradoPara`</td><td>Sempre `"consumo"`</td></tr><tr><td>`mensagem`</td><td>Mensagem para exibição/log</td></tr></tbody></table>

</div></div>---

### `comandasBloqueadasParaCancelar[]` (bloqueios)

Lista de comandas que não puderam ser canceladas:

<div class="TyagGW_tableContainer" id="bkmrk-campo-descri%C3%A7%C3%A3o-idme-1"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)"><thead><tr><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr><td>`idMesa`</td><td>ID da comanda (quando existir)</td></tr><tr><td>`codigoComanda`</td><td>Código da comanda (quando existir)</td></tr><tr><td>`statusAtual`</td><td>Status atual (quando existir)</td></tr><tr><td>`motivo`</td><td>Código do bloqueio</td></tr><tr><td>`mensagem`</td><td>Mensagem explicativa</td></tr><tr><td>`numeroPdvEmConferencia`</td><td>Apenas quando `EM_CONFERENCIA_OUTRO_PDV`</td></tr><tr><td>`pos_lancando`</td><td>Apenas quando `EM_LANCAMENTO_ITENS`</td></tr></tbody></table>

</div></div>---

## ✅ Exemplo — 200 (cancelamento completo)

```json
{
  "comandasCanceladasParaFaturar": [
    {
      "idMesa": 4069,
      "codigoComanda": "21",
      "statusAlteradoPara": "consumo",
      "mensagem": "Faturamento cancelado com sucesso. Comanda retornou para consumo."
    },
    {
      "idMesa": 4070,
      "codigoComanda": "22",
      "statusAlteradoPara": "consumo",
      "mensagem": "Faturamento cancelado com sucesso. Comanda retornou para consumo."
    }
  ],
  "comandasBloqueadasParaCancelar": []
}

```

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--11"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div></div>---

## ✅ Exemplo — 200 (parcial)

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--13"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr">  
</div></div>```json
{
  "comandasCanceladasParaFaturar": [
    {
      "idMesa": 4069,
      "codigoComanda": "21",
      "statusAlteradoPara": "consumo",
      "mensagem": "Faturamento cancelado com sucesso. Comanda retornou para consumo."
    }
  ],
  "comandasBloqueadasParaCancelar": [
    {
      "idMesa": 4070,
      "codigoComanda": "22",
      "statusAtual": "conferencia",
      "motivo": "EM_CONFERENCIA_OUTRO_PDV",
      "numeroPdvEmConferencia": "15",
      "mensagem": "Comanda está em conferência por outro PDV."
    },
    {
      "idMesa": 4072,
      "codigoComanda": "24",
      "statusAtual": "transferencia",
      "motivo": "EM_TRANSFERENCIA",
      "mensagem": "Comanda está em transferência de itens e não pode ser cancelada."
    }
  ]
}

```

---

## 200 — nenhuma comanda cancelável

Retorna erro quando **0 comandas** puderam ser canceladas.

### Exemplo — 200

<div class="contain-inline-size rounded-2xl corner-superellipse/1.1 relative bg-token-sidebar-surface-primary" id="bkmrk--15"><div class="sticky top-[calc(--spacing(9)+var(--header-height))] @w-xl/main:top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs">  
</div></div></div><div class="overflow-y-auto p-4" dir="ltr">  
</div></div>```json
{
  "comandasCanceladasParaFaturar": [],
  "comandasBloqueadasParaCancelar": [
    {
      "idMesa": 4070,
      "codigoComanda": "22",
      "statusAtual": "livre",
      "motivo": "STATUS_LIVRE",
      "mensagem": "Comanda está livre e não possui faturamento para cancelar."
    },
    {
      "idMesa": 4073,
      "codigoComanda": "26",
      "statusAtual": "consumo",
      "motivo": "NAO_ESTA_EM_CONFERENCIA",
      "mensagem": "Comanda não está em conferência."
    },
    {
      "codigoComanda": "9999",
      "motivo": "NAO_ENCONTRADA",
      "mensagem": "Comanda não encontrada."
    }
  ]
}

```

---

## 🧾 Enum `motivo` (mínimo)

- `NAO_ENCONTRADA`
- `NAO_ESTA_EM_CONFERENCIA`
- `STATUS_LIVRE`
- `EM_TRANSFERENCIA`
- `EM_LANCAMENTO_ITENS`
- `EM_CONFERENCIA_OUTRO_PDV`
- `STATUS_INVALIDO`

---

## ✅ Boas práticas para integradores (PDV)

- Sempre trate **retorno parcial**.
- Envie apenas as comandas que você recebeu em `comandasParaFaturar` no `iniciar-faturamento`.
- Se vier `EM_CONFERENCIA_OUTRO_PDV`, isso é **tratativa gerencial/manual** (não tente “resolver” pelo PDV).
- Após cancelar, o PDV deve:
    
    
    - limpar o contexto da venda local;
    - permitir que a comanda seja faturada novamente.

# Requisitos Centralizador PDV's Fast

**<span style="font-size:14pt;color:#2e6da4;">AVANÇO INFORMÁTICA</span>**

**<span style="font-size:26pt;color:#1a3a5c;">Centralizador PDV's Fast</span>**

<span style="font-size:14pt;color:#444444;">Guia de Requisitos para Implantação</span>

<span style="font-size:10pt;color:#666666;">Este documento descreve os requisitos de hardware, sistema operacional e infraestrutura de rede necessários para a instalação e operação do Centralizador PDV's Fast em ambiente do cliente.</span>

# 1. Visão Geral da Solução

<span style="color:#444444;">O Centralizador PDV's Fast é o componente central responsável por intermediar a comunicação entre os dispositivos do ambiente do cliente. Ele recebe e processa requisições provenientes de:</span>

<span>•<span style="font:7pt 'Times New Roman';"> </span></span><span style="color:#444444;">App de Comandas / PDV Mobile (dispositivos SmartPOS) — comunicação via API REST sobre Wi-Fi.</span>

<span>•<span style="font:7pt 'Times New Roman';"> </span></span><span style="color:#444444;">PDV Legado Desktop (Linux) — comunicação via rede cabeada.</span>

<span style="color:#444444;">Além disso, o Servidor Comandas precisa ter acesso ao servidor do Sistema Integral (ERP Linux), que é a máquina responsável pela gestão central dos dados do cliente.</span>

<span style="color:#444444;">Para que toda a solução funcione corretamente, é fundamental que a infraestrutura de rede e a máquina do Servidor Comandas atendam integralmente aos requisitos descritos neste documento.</span>

# 2. Topologia de Comunicação e Requisitos de Rede

<span style="color:#444444;">A ilustração abaixo representa a topologia de comunicação entre os componentes da solução:</span>

<table class="MsoNormalTable" id="bkmrk-componente-tipo-de-c" style="width:468pt;border-collapse:collapse;border:none;height:289.922px;"><thead><tr style="height:31.1094px;"><td style="width:140pt;border:1pt solid rgb(187,207,224);background:rgb(31,78,121);padding:5pt 8pt;height:31.1094px;">**<span style="font-size:10pt;color:#FFFFFF;">Componente</span>**

</td><td style="width:110pt;border-top:1pt solid rgb(187,207,224);border-right:1pt solid rgb(187,207,224);border-bottom:1pt solid rgb(187,207,224);border-left:none;background:rgb(31,78,121);padding:5pt 8pt;height:31.1094px;">**<span style="font-size:10pt;color:#FFFFFF;">Tipo de Conexão</span>**

</td><td style="width:218pt;border-top:1pt solid rgb(187,207,224);border-right:1pt solid rgb(187,207,224);border-bottom:1pt solid rgb(187,207,224);border-left:none;background:rgb(31,78,121);padding:5pt 8pt;height:31.1094px;">**<span style="font-size:10pt;color:#FFFFFF;">Requisito de Rede</span>**

</td></tr></thead><tbody><tr style="height:47.9062px;"><td style="width:140pt;border-right:1pt solid rgb(187,207,224);border-bottom:1pt solid rgb(187,207,224);border-left:1pt solid rgb(187,207,224);border-top:none;padding:5pt 8pt;height:47.9062px;"><span style="font-size:10pt;color:#444444;">SmartPOS (App Comandas / PDV Mobile)</span>

</td><td style="width:110pt;border-top:none;border-left:none;border-bottom:1pt solid rgb(187,207,224);border-right:1pt solid rgb(187,207,224);padding:5pt 8pt;height:47.9062px;"><span style="font-size:10pt;color:#444444;">Wi-Fi</span>

</td><td style="width:218pt;border-top:none;border-left:none;border-bottom:1pt solid rgb(187,207,224);border-right:1pt solid rgb(187,207,224);padding:5pt 8pt;height:47.9062px;"><span style="font-size:10pt;color:#444444;">Deve estar conectado à rede Wi-Fi que permita acesso ao Servidor Comandas e também a internet. </span>

</td></tr><tr style="height:81.5px;"><td style="width:140pt;border-right:1pt solid rgb(187,207,224);border-bottom:1pt solid rgb(187,207,224);border-left:1pt solid rgb(187,207,224);border-top:none;padding:5pt 8pt;height:81.5px;"><span style="font-size:10pt;color:#444444;">PDV Legado Desktop (Linux)</span>

</td><td style="width:110pt;border-top:none;border-left:none;border-bottom:1pt solid rgb(187,207,224);border-right:1pt solid rgb(187,207,224);padding:5pt 8pt;height:81.5px;"><span style="font-size:10pt;color:#444444;">Cabo de rede (Ethernet)</span>

</td><td style="width:218pt;border-top:none;border-left:none;border-bottom:1pt solid rgb(187,207,224);border-right:1pt solid rgb(187,207,224);padding:5pt 8pt;height:81.5px;"><span style="font-size:10pt;color:#444444;">Deve estar conectado via cabo na rede que permita acesso ao Servidor Comandas e ao servidor do Sistema Integral (ERP) e também a internet.</span>

</td></tr><tr style="height:81.5px;"><td style="width:140pt;border-right:1pt solid rgb(187,207,224);border-bottom:1pt solid rgb(187,207,224);border-left:1pt solid rgb(187,207,224);border-top:none;padding:5pt 8pt;height:81.5px;"><span style="font-size:10pt;color:#444444;">Centralizador PDV's Fast (Windows)</span>

</td><td style="width:110pt;border-top:none;border-left:none;border-bottom:1pt solid rgb(187,207,224);border-right:1pt solid rgb(187,207,224);padding:5pt 8pt;height:81.5px;"><span style="font-size:10pt;color:#444444;">Cabo de rede (Ethernet)</span>

</td><td style="width:218pt;border-top:none;border-left:none;border-bottom:1pt solid rgb(187,207,224);border-right:1pt solid rgb(187,207,224);padding:5pt 8pt;height:81.5px;"><span style="font-size:10pt;color:#444444;">Deve estar na rede que permita comunicação com: SmartPOS (Wi-Fi), PDV Linux (cabeado) e servidor do Sistema Integral (ERP Linux) como também a internet.</span>

</td></tr><tr style="height:47.9062px;"><td style="width:140pt;border-right:1pt solid rgb(187,207,224);border-bottom:1pt solid rgb(187,207,224);border-left:1pt solid rgb(187,207,224);border-top:none;padding:5pt 8pt;height:47.9062px;"><span style="font-size:10pt;color:#444444;">Servidor do Sistema Integral (ERP Linux)</span>

</td><td style="width:110pt;border-top:none;border-left:none;border-bottom:1pt solid rgb(187,207,224);border-right:1pt solid rgb(187,207,224);padding:5pt 8pt;height:47.9062px;"><span style="font-size:10pt;color:#444444;">Cabo de rede (Ethernet)</span>

</td><td style="width:218pt;border-top:none;border-left:none;border-bottom:1pt solid rgb(187,207,224);border-right:1pt solid rgb(187,207,224);padding:5pt 8pt;height:47.9062px;"><span style="font-size:10pt;color:#444444;">Deve estar acessível pelo Servidor Comandas e pelo PDV Legado Linux.</span>

</td></tr></tbody></table>

## 2.1 Requisitos Detalhados de Rede

**<span style="color:#c55a11;">⚠ Atenção: </span>**<span style="color:#7b3f00;">A comunicação entre todos os componentes ocorre pela rede local (LAN) do cliente. O Servidor Comandas deve conseguir se comunicar simultaneamente com os SmartPOS via Wi-Fi e com o PDV Linux e o servidor do ERP via cabo.</span>

<table class="MsoNormalTable" id="bkmrk-requisito-descri%C3%A7%C3%A3o-" style="width:468pt;border-collapse:collapse;border:none;"><thead><tr><td style="width:160pt;border:solid #BBCFE0 1pt;background:#1F4E79;padding:5pt 8pt 5pt 8pt;">**<span style="font-size:10pt;color:#FFFFFF;">Requisito</span>**

</td><td style="width:308pt;border:solid #BBCFE0 1pt;border-left:none;background:#1F4E79;padding:5pt 8pt 5pt 8pt;">**<span style="font-size:10pt;color:#FFFFFF;">Descrição</span>**

</td></tr></thead><tbody><tr><td style="width:160pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Padrão de rede</span>

</td><td style="width:308pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Ethernet 10/100/1000 Mbps (Gigabit Ethernet recomendado).</span>

</td></tr><tr><td style="width:160pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Topologia</span>

</td><td style="width:308pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Todos os dispositivos devem estar na mesma rede local (LAN) ou com roteamento adequado entre sub-redes.</span>

</td></tr><tr><td style="width:160pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">IP estático — Servidor Comandas</span>

</td><td style="width:308pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">É obrigatório configurar um endereço IP fixo (estático) na máquina do Servidor Comandas, para que os SmartPOS e o PDV Linux sempre consigam localizá-lo.</span>

</td></tr><tr><td style="width:160pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Firewall / Bloqueios</span>

</td><td style="width:308pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">As portas utilizadas pela aplicação Servidor Comandas devem estar liberadas no firewall da rede e no firewall do Windows da máquina. As portas específicas serão informadas pela equipe de implantação.</span>

</td></tr><tr><td style="width:160pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Wi-Fi (SmartPOS)</span>

</td><td style="width:308pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">O roteador ou access point Wi-Fi deve estar na mesma rede ou ter roteamento para o Servidor Comandas. Sinal estável e sem isolamento de cliente (AP Isolation desativado).</span>

</td></tr><tr><td style="width:160pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Cabo de rede (PDV Linux)</span>

</td><td style="width:308pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Conexão física obrigatória via cabo Ethernet entre o PDV Linux e o switch ou roteador da rede do cliente.</span>

</td></tr><tr><td style="width:160pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Velocidade mínima recomendada</span>

</td><td style="width:308pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Rede local com pelo menos 100 Mbps entre os dispositivos.</span>

</td></tr></tbody></table>

# 3. Requisitos de Hardware — Máquina do Servidor Comandas

<span style="color:#444444;">A máquina destinada a operar o Servidor Comandas deve atender às especificações mínimas a seguir. Recomendamos fortemente o uso das configurações recomendadas para garantir estabilidade e desempenho adequados.</span>

<table class="MsoNormalTable" id="bkmrk-componente-especific" style="width:468pt;border-collapse:collapse;border:none;"><thead><tr><td style="width:125pt;border:solid #BBCFE0 1pt;background:#1F4E79;padding:5pt 8pt 5pt 8pt;">**<span style="font-size:10pt;color:#FFFFFF;">Componente</span>**

</td><td style="width:175pt;border:solid #BBCFE0 1pt;border-left:none;background:#1F4E79;padding:5pt 8pt 5pt 8pt;">**<span style="font-size:10pt;color:#FFFFFF;">Especificação Mínima</span>**

</td><td style="width:168pt;border:solid #BBCFE0 1pt;border-left:none;background:#1F4E79;padding:5pt 8pt 5pt 8pt;">**<span style="font-size:10pt;color:#FFFFFF;">Especificação Recomendada</span>**

</td></tr></thead><tbody><tr><td style="width:125pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Sistema Operacional</span>

</td><td style="width:175pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Windows 11 — 64 bits</span>

</td><td style="width:168pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Windows 11 — 64 bits</span>

</td></tr><tr><td style="width:125pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Processador</span>

</td><td style="width:175pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Intel Core i3 (ou equivalente), clock mínimo de 2,3 GHz, pelo menos 4 núcleos.</span>

</td><td style="width:168pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Intel Core i5 ou superior, 4+ núcleos, clock ≥ 2,5 GHz.</span>

</td></tr><tr><td style="width:125pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Memória RAM</span>

</td><td style="width:175pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">8 GB DDR3</span>

</td><td style="width:168pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">12 GB DDR3 ou DDR4</span>

</td></tr><tr><td style="width:125pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Placa de Rede</span>

</td><td style="width:175pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Padrão 10/100/1000 Mbps (Gigabit Ethernet)</span>

</td><td style="width:168pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Padrão 10/100/1000 Mbps (Gigabit Ethernet)</span>

</td></tr><tr><td style="width:125pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Armazenamento</span>

</td><td style="width:175pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">SSD SATA ou NVMe de no mínimo 240 GB (Kingston ou similar)</span>

</td><td style="width:168pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">SSD SATA ou NVMe de no mínimo 240 GB (Kingston ou similar)</span>

</td></tr></tbody></table>

# 4. Requisitos de Sistema Operacional e Configuração da Máquina

## 4.1 Sistema Operacional

<span>•<span style="font:7pt 'Times New Roman';"> </span></span><span style="color:#444444;">Windows 11 — 64 bits</span>

<span>•<span style="font:7pt 'Times New Roman';"> </span></span><span style="color:#444444;">A conta de usuário do Windows utilizada pela aplicação deve ter permissões de Administrador Local.</span>

## 4.2 Configurações Importantes

<span>•<span style="font:7pt 'Times New Roman';"> </span></span><span style="color:#444444;">IP estático configurado na placa de rede (obrigatório — veja seção 2.1).</span>

<span>•<span style="font:7pt 'Times New Roman';"> </span></span><span style="color:#444444;">Atualizações automáticas do Windows: recomendamos que reinicializações automáticas fora do horário de funcionamento sejam configuradas para evitar interrupções no serviço.</span>

<span>•<span style="font:7pt 'Times New Roman';"> </span></span><span style="color:#444444;">Antivírus: caso haja antivírus instalado, os diretórios e processos do Servidor Comandas devem ser adicionados como exceção para evitar bloqueios indesejados.</span>

<span>•<span style="font:7pt 'Times New Roman';"> </span></span><span style="color:#444444;">Firewall do Windows: as portas da aplicação devem ser liberadas (a equipe de implantação orientará sobre quais portas configurar).</span>

<span>•<span style="font:7pt 'Times New Roman';"> </span></span><span style="color:#444444;">Ideal que essa máquina nunca seja desligada, já que ela realiza o envio das vendas ao servidor integral. Ou seja, ela precisa estar sempre em execução contínua.</span>

# 5. Checklist de Pré-Implantação

<span style="color:#444444;">Antes da visita de implantação, o cliente deve confirmar que todos os itens abaixo estão atendidos:</span>

<table class="MsoNormalTable" id="bkmrk-%23-item-status-1-m%C3%A1qu" style="width:468pt;border-collapse:collapse;border:none;"><thead><tr><td style="width:27pt;border:solid #BBCFE0 1pt;background:#1F4E79;padding:5pt 8pt 5pt 8pt;">**<span style="font-size:10pt;color:#FFFFFF;">\#</span>**

</td><td style="width:324pt;border:solid #BBCFE0 1pt;border-left:none;background:#1F4E79;padding:5pt 8pt 5pt 8pt;">**<span style="font-size:10pt;color:#FFFFFF;">Item</span>**

</td><td style="width:117pt;border:solid #BBCFE0 1pt;border-left:none;background:#1F4E79;padding:5pt 8pt 5pt 8pt;">**<span style="font-size:10pt;color:#FFFFFF;">Status</span>**

</td></tr></thead><tbody><tr><td style="width:27pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">1</span>

</td><td style="width:324pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Máquina com Windows 11 — 64 bits disponível e ligada.</span>

</td><td style="width:117pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">☐ Confirmado</span>

</td></tr><tr><td style="width:27pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">2</span>

</td><td style="width:324pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Processador com pelo menos 4 núcleos e 2,3 GHz.</span>

</td><td style="width:117pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">☐ Confirmado</span>

</td></tr><tr><td style="width:27pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">3</span>

</td><td style="width:324pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Mínimo de 8 GB de RAM instalados.</span>

</td><td style="width:117pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">☐ Confirmado</span>

</td></tr><tr><td style="width:27pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">4</span>

</td><td style="width:324pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">SSD de no mínimo 240 GB disponível.</span>

</td><td style="width:117pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">☐ Confirmado</span>

</td></tr><tr><td style="width:27pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">5</span>

</td><td style="width:324pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Placa de rede Gigabit (10/100/1000 Mbps).</span>

</td><td style="width:117pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">☐ Confirmado</span>

</td></tr><tr><td style="width:27pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">6</span>

</td><td style="width:324pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">IP estático configurado (ou a ser configurado pela equipe Avanço).</span>

</td><td style="width:117pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">☐ Confirmado</span>

</td></tr><tr><td style="width:27pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">7</span>

</td><td style="width:324pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Cabo de rede conectando a máquina ao switch/roteador.</span>

</td><td style="width:117pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">☐ Confirmado</span>

</td></tr><tr><td style="width:27pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">8</span>

</td><td style="width:324pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">SmartPOS com acesso à rede Wi-Fi que alcança o Servidor Comandas.</span>

</td><td style="width:117pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">☐ Confirmado</span>

</td></tr><tr><td style="width:27pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">9</span>

</td><td style="width:324pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">PDV Linux (legado) com acesso via cabo à mesma rede do Servidor Comandas.</span>

</td><td style="width:117pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">☐ Confirmado</span>

</td></tr><tr><td style="width:27pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">10</span>

</td><td style="width:324pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Servidor do Sistema Integral (ERP Linux) acessível na rede.</span>

</td><td style="width:117pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">☐ Confirmado</span>

</td></tr><tr><td style="width:27pt;border:solid #BBCFE0 1pt;border-top:none;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">11</span>

</td><td style="width:324pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">Firewall e antivírus configurados para permitir a aplicação (ou a configurar com apoio Avanço).</span>

</td><td style="width:117pt;border-top:none;border-left:none;border-bottom:solid #BBCFE0 1pt;border-right:solid #BBCFE0 1pt;padding:5pt 8pt 5pt 8pt;"><span style="font-size:10pt;color:#444444;">☐ Confirmado</span>

</td></tr></tbody></table>

# 6. Suporte e Contato

<span style="color:#444444;">Em caso de dúvidas sobre os requisitos ou durante o processo de implantação, entre em contato com a equipe da Avanço Informática:</span>

<table class="MsoNormalTable" id="bkmrk-avan%C3%A7o-inform%C3%A1tica-%E2%80%94" style="width:468pt;border-collapse:collapse;border:none;"><tbody><tr><td style="width:468pt;border:solid #BBCFE0 1pt;background:#D6E8F5;padding:5pt 10pt 5pt 10pt;">**<span style="color:#1a3a5c;">Avanço Informática — Suporte Técnico</span>**

<span style="font-size:10pt;color:#444444;">Site: www.avancoinfo.com.br</span>

<span style="font-size:10pt;color:#444444;">Telefone: (31) 3025-1188</span>

</td></tr></tbody></table>

*<span style="font-size:9pt;color:#aaaaaa;">— Documento gerado pela equipe Avanço Informática —</span>*