Referência

Restauração

A sala e as mesas, os postos de preparação (cozinha, bar), o menu, as fichas técnicas dos pratos, as comandas com o seu ciclo (lançar, enviar à cozinha, servir, pedir a conta, cobrar) e os relatórios. A conta cobra-se com um documento fiscal do núcleo (factura/recibo ou factura), pelo fluxo de sempre. Cancelar um item já enviado exige a permissão própria: o pedido de autorização a um supervisor, por PIN, faz-se ao balcão e não está na API.

Operação	O que faz
GET `/api/restauracao/sala`	A planta da sala: as zonas e as mesas, com a posição e a forma de cada uma.
POST `/api/restauracao/sala/zonas`	Cria uma zona da sala.
PUT `/api/restauracao/sala/zonas/{id}`	Altera o nome e a ordem de uma zona.
PUT `/api/restauracao/sala/zonas/{id}/activa`	Activa ou desactiva uma zona.
POST `/api/restauracao/sala/mesas`	Cria uma mesa numa zona, com o número, a capacidade, a forma e a posição na planta.
PUT `/api/restauracao/sala/mesas/{id}`	Altera a zona, o número, a capacidade, a forma e a posição de uma mesa.
PUT `/api/restauracao/sala/mesas/{id}/activa`	Activa ou desactiva uma mesa.
POST `/api/restauracao/sala/mesas/{id}/limpar`	Limpa uma mesa que fechou: volta a poder ser ocupada.
GET `/api/restauracao/postos`	Os postos de preparação (cozinha, bar…) onde chegam os talões.
POST `/api/restauracao/postos`	Cria um posto de preparação.
PUT `/api/restauracao/postos/{id}`	Altera o nome, a ordem e o passo «em preparação» de um posto.
PUT `/api/restauracao/postos/{id}/activo`	Activa ou desactiva um posto de preparação.
GET `/api/restauracao/postos/{postoId}/taloes`	Os talões de um posto (o ecrã da cozinha): o que há por preparar e, se pedir, o histórico.
POST `/api/restauracao/taloes/{talaoId}/pronto`	Marca o talão inteiro como pronto: tudo o que faltava preparar fica pronto.
GET `/api/restauracao/menu`	O menu que o garçom vê: os artigos de venda activos, com o preço de tabela e o posto de cada um.
PUT `/api/restauracao/produtos/{produtoId}/config`	Define, para um artigo, o posto onde se prepara, o nome curto e o tempo-alvo de preparação (`postoId`, `nomeCurto`, `tempoAlvoMinutos`).
PUT `/api/restauracao/produtos/{produtoId}/esgotado`	Marca ou repõe um artigo como esgotado: a cozinha marca-o quando acaba, e o garçom deixa de o poder lançar em qualquer terminal.
PUT `/api/restauracao/produtos/{produtoId}/quantidade-do-dia`	Define quantas doses de um artigo se vendem hoje (ou tira o limite, com `quantidade` nula).
PUT `/api/restauracao/produtos/{produtoId}/grupos`	Define, de uma vez, os grupos de opções que um artigo oferece, pela ordem dada.
GET `/api/restauracao/grupos-opcoes`	Os grupos de opções que um artigo pode oferecer, com as opções de cada um.
POST `/api/restauracao/grupos-opcoes`	Cria um grupo de opções, com o mínimo e o máximo que se podem escolher e as opções.
PUT `/api/restauracao/grupos-opcoes/{id}`	Altera um grupo de opções (nome, mínimo, máximo, ordem, estado e opções).
GET `/api/restauracao/fichas`	As fichas técnicas dos pratos e das preparações.
GET `/api/restauracao/fichas/{produtoId}`	A ficha técnica de um prato ou de uma preparação, com os ingredientes.
PUT `/api/restauracao/fichas/{produtoId}`	Cria ou substitui a ficha técnica de um prato ou de uma preparação.
GET `/api/restauracao/ingredientes`	Os artigos que se podem pôr numa ficha: os activos que controlam stock e as preparações já definidas.
GET `/api/restauracao/preparacoes/candidatos`	Os artigos que podem passar a preparações: activos, de produto, sem stock próprio e que ainda não têm ficha.
POST `/api/restauracao/comandas`	Abre uma comanda numa mesa.
GET `/api/restauracao/comandas/{id}`	Uma comanda com os itens e o estado da conta.
GET `/api/restauracao/mesas/{mesaId}/comanda`	A comanda aberta de uma mesa, ou nada se a mesa está livre.
POST `/api/restauracao/comandas/{id}/itens`	Lança um artigo na comanda.
PUT `/api/restauracao/itens/{itemId}`	Altera a quantidade, a observação, o lugar ou a fase de um item.
DELETE `/api/restauracao/itens/{itemId}`	Remove um item pendente da comanda (que ainda não foi enviado).
POST `/api/restauracao/comandas/{id}/enviar`	Envia a comanda: um talão por posto com os itens pendentes das fases já pedidas.
POST `/api/restauracao/itens/{itemId}/servir`	Marca um item como servido.
POST `/api/restauracao/itens/{itemId}/iniciar`	Marca o início da preparação de um item.
POST `/api/restauracao/itens/{itemId}/pronto`	Marca um item como pronto.
POST `/api/restauracao/itens/{itemId}/desfazer-pronto`	Desfaz o «pronto» nos 30 segundos seguintes (um toque enganado no ecrã).
POST `/api/restauracao/itens/{itemId}/cancelar`	Cancela um item já enviado, com um motivo estruturado.
POST `/api/restauracao/itens/{itemId}/pedir-cancelamento`	O posto (a cozinha, o bar) pede que um item já enviado seja cancelado: não o cancela, avisa o supervisor, que o vê na comanda e decide.
POST `/api/restauracao/itens/{itemId}/dispensar-pedido-cancelamento`	Quem tem a comanda (o garçom ou o supervisor) dispensa o pedido de cancelamento da cozinha: o item fica como estava.
POST `/api/restauracao/comandas/{id}/anular`	Anula uma comanda.
POST `/api/restauracao/comandas/{id}/transferir`	Passa a comanda inteira para outra mesa.
POST `/api/restauracao/comandas/{id}/juntar-mesas`	Junta mesas livres à comanda (um grupo grande que ocupa duas ou três mesas): continua a haver uma só conta.
POST `/api/restauracao/comandas/{id}/separar-mesa`	Separa uma mesa que estava junta: fica livre e a comanda continua com as outras.
POST `/api/restauracao/comandas/{id}/trocar-garcom`	Reatribui a mesa a outro garçom do mesmo estabelecimento.
POST `/api/restauracao/comandas/{id}/mover-itens`	Passa itens (todos da mesma comanda) para outra comanda aberta do mesmo estabelecimento.
GET `/api/restauracao/comandas/{id}/pre-conta`	A pré-conta, sem mexer na mesa: o que falta cobrar.
POST `/api/restauracao/comandas/{id}/pedir-conta`	O cliente pede a conta: a mesa passa a «à espera de conta» e devolve-se a pré-conta.
POST `/api/restauracao/comandas/{id}/reabrir-conta`	Reabre a conta: o cliente afinal pede mais, ou a conta foi pedida por engano, e a mesa volta a «ocupada».
POST `/api/restauracao/comandas/{id}/consulta-de-mesa`	Emite a Consulta de Mesa com tudo o que falta cobrar na comanda e passa a mesa a «conta pedida».
GET `/api/restauracao/comandas/{id}/consultas-de-mesa`	As consultas de mesa já emitidas para uma comanda, da mais recente para a mais antiga.
POST `/api/restauracao/comandas/{id}/cobrar`	Cobra uma parte da conta (ou toda) com um documento fiscal do núcleo: factura/recibo («FR», paga no acto) ou factura («FT», a crédito a um cliente especial).
GET `/api/restauracao/relatorio`	O relatório da restauração de um período.
GET `/api/restauracao/engenharia-do-menu`	A engenharia do menu de um período.
GET `/api/restauracao/reposicao`	A reposição de ingredientes: o que repor, com base no consumo recente.
GET `/api/restauracao/auditoria`	O registo de auditoria da sala, pesquisável por operador, mesa, tipo de acção e período.
GET `/api/restauracao/reservas`	As reservas de mesa de um dia, por hora.
GET `/api/restauracao/reservas/{id}`	Uma reserva de mesa.
POST `/api/restauracao/reservas`	Cria uma reserva de mesa.
PUT `/api/restauracao/reservas/{id}`	Altera uma reserva que ainda espera o cliente (mesa, hora, duração, pessoas, telefone e nota).
POST `/api/restauracao/reservas/{id}/chegou`	Regista a chegada do cliente.
POST `/api/restauracao/reservas/{id}/sentar`	Regista que o cliente se sentou (a reserva cumpriu-se e a mesa fica livre da reserva).
POST `/api/restauracao/reservas/{id}/faltou`	Regista que o cliente não veio.
POST `/api/restauracao/reservas/{id}/cancelar`	Cancela uma reserva e liberta a mesa.

GET/api/restauracao/sala#

A planta da sala: as zonas e as mesas, com a posição e a forma de cada uma.

Permissão Restauracao.SalaLer

apenasActivas (por omissão, verdadeiro) deixa de fora o que está desactivado. lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`lojaId`	na pesquisa	identificador (UUID)
`apenasActivas`	na pesquisa	verdadeiro/falso

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/sala' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/sala/zonas#

Cria uma zona da sala.

Permissão Restauracao.SalaEditar
Idempotência aceita Idempotency-Key

lojaId é opcional quando a chave só tem um estabelecimento.

Corpo do pedido (JSON · CriarZonaCommand)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`ordem`	número inteiro
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/sala/zonas' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto"
}'

PUT/api/restauracao/sala/zonas/{id}#

Altera o nome e a ordem de uma zona.

Permissão Restauracao.SalaEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ActualizarZonaRequest)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`ordem`	número inteiro	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/sala/zonas/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "ordem": 1
}'

PUT/api/restauracao/sala/zonas/{id}/activa#

Activa ou desactiva uma zona.

Permissão Restauracao.SalaEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · DefinirActivaRequest)

Campo	Tipo	Obrigatório
`activa`	verdadeiro/falso	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/sala/zonas/<id>/activa' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "activa": false
}'

POST/api/restauracao/sala/mesas#

Cria uma mesa numa zona, com o número, a capacidade, a forma e a posição na planta.

Permissão Restauracao.SalaEditar
Idempotência aceita Idempotency-Key

forma: Redonda, Quadrada, Rectangular ou Balcao. x, y, largura e altura posicionam a mesa na planta.

Corpo do pedido (JSON · CriarMesaCommand)

Campo	Tipo	Obrigatório	Significado
`zonaId`	identificador (UUID)	sim
`numero`	texto	sim	O número legível, atribuído pelo servidor («FR LC2026/25»).
`capacidade`	número inteiro	sim
`forma`	texto	sim
`x`	número inteiro	sim
`y`	número inteiro	sim
`largura`	número inteiro
`altura`	número inteiro

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/sala/mesas' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "zonaId": "00000000-0000-0000-0000-000000000000",
  "numero": "texto",
  "capacidade": 1,
  "forma": "texto",
  "x": 1,
  "y": 1
}'

PUT/api/restauracao/sala/mesas/{id}#

Altera a zona, o número, a capacidade, a forma e a posição de uma mesa.

Permissão Restauracao.SalaEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ActualizarMesaRequest)

Campo	Tipo	Obrigatório	Significado
`zonaId`	identificador (UUID)	sim
`numero`	texto	sim	O número legível, atribuído pelo servidor («FR LC2026/25»).
`capacidade`	número inteiro	sim
`forma`	texto	sim
`x`	número inteiro	sim
`y`	número inteiro	sim
`largura`	número inteiro	sim
`altura`	número inteiro	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/sala/mesas/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "zonaId": "00000000-0000-0000-0000-000000000000",
  "numero": "texto",
  "capacidade": 1,
  "forma": "texto",
  "x": 1,
  "y": 1,
  "largura": 1,
  "altura": 1
}'

PUT/api/restauracao/sala/mesas/{id}/activa#

Activa ou desactiva uma mesa.

Permissão Restauracao.SalaEditar

Uma mesa nunca se apaga: desactiva-se.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · DefinirActivaRequest)

Campo	Tipo	Obrigatório
`activa`	verdadeiro/falso	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/sala/mesas/<id>/activa' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "activa": false
}'

POST/api/restauracao/sala/mesas/{id}/limpar#

Limpa uma mesa que fechou: volta a poder ser ocupada.

Permissão Restauracao.ComandaOperar

É um acto da sala (o garçom ou o ajudante), não da gestão.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/sala/mesas/<id>/limpar' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/restauracao/postos#

Os postos de preparação (cozinha, bar…) onde chegam os talões.

Permissão Restauracao.SalaLer

apenasActivos (por omissão, verdadeiro).

Parâmetros

Nome	Onde	Tipo	Obrigatório
`apenasActivos`	na pesquisa	verdadeiro/falso

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/postos' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/postos#

Cria um posto de preparação.

Permissão Restauracao.CatalogoEditar
Idempotência aceita Idempotency-Key

nome, ordem e usaPassoEmPreparacao (por omissão, falso).

Corpo do pedido (JSON · CriarPostoCommand)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`ordem`	número inteiro
`usaPassoEmPreparacao`	verdadeiro/falso

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/postos' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto"
}'

PUT/api/restauracao/postos/{id}#

Altera o nome, a ordem e o passo «em preparação» de um posto.

Permissão Restauracao.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ActualizarPostoRequest)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`ordem`	número inteiro	sim
`usaPassoEmPreparacao`	verdadeiro/falso	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/postos/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "ordem": 1,
  "usaPassoEmPreparacao": false
}'

PUT/api/restauracao/postos/{id}/activo#

Activa ou desactiva um posto de preparação.

Permissão Restauracao.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · DefinirActivoRequest)

Campo	Tipo	Obrigatório	Significado
`activo`	verdadeiro/falso	sim	Se está activo.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/postos/<id>/activo' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "activo": false
}'

GET/api/restauracao/postos/{postoId}/taloes#

Os talões de um posto (o ecrã da cozinha): o que há por preparar e, se pedir, o histórico.

Permissão Restauracao.KdsOperar

historico (até 50) acrescenta à resposta uma lista de talões do histórico. lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`postoId`	no caminho	identificador (UUID)	sim
`lojaId`	na pesquisa	identificador (UUID)
`historico`	na pesquisa	número inteiro

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/postos/<postoId>/taloes' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/taloes/{talaoId}/pronto#

Marca o talão inteiro como pronto: tudo o que faltava preparar fica pronto.

Permissão Restauracao.KdsOperar

Devolve quantos itens mudaram.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`talaoId`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/taloes/<talaoId>/pronto' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/restauracao/menu#

O menu que o garçom vê: os artigos de venda activos, com o preço de tabela e o posto de cada um.

Permissão Restauracao.ComandaLer

Filtros: filtro (texto), categoriaId e tamanho (por omissão 200). lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo
`filtro`	na pesquisa	texto
`categoriaId`	na pesquisa	identificador (UUID)
`tamanho`	na pesquisa	número inteiro
`lojaId`	na pesquisa	identificador (UUID)

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/menu' \
  -H 'X-Api-Key: <a-sua-chave>'

PUT/api/restauracao/produtos/{produtoId}/config#

Define, para um artigo, o posto onde se prepara, o nome curto e o tempo-alvo de preparação (postoId, nomeCurto, tempoAlvoMinutos).

Permissão Restauracao.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`produtoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ConfigDoProdutoRequest)

Campo	Tipo	Obrigatório
`postoId`	identificador (UUID) ou nulo
`nomeCurto`	texto ou nulo
`tempoAlvoMinutos`	número inteiro ou nulo

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/produtos/<produtoId>/config' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{}'

PUT/api/restauracao/produtos/{produtoId}/esgotado#

Marca ou repõe um artigo como esgotado: a cozinha marca-o quando acaba, e o garçom deixa de o poder lançar em qualquer terminal.

Permissão Restauracao.KdsOperar

Fica no registo de auditoria da sala, com quem foi e quando. lojaId é opcional quando a chave só tem um estabelecimento.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`produtoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · DefinirEsgotadoRequest)

Campo	Tipo	Obrigatório	Significado
`esgotado`	verdadeiro/falso	sim
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/produtos/<produtoId>/esgotado' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "esgotado": false
}'

PUT/api/restauracao/produtos/{produtoId}/quantidade-do-dia#

Define quantas doses de um artigo se vendem hoje (ou tira o limite, com quantidade nula).

Permissão Restauracao.CatalogoEditar

Desce a cada lançamento (um item cancelado devolve a dose) e, quando chega a zero, o artigo fica esgotado até ao dia seguinte. lojaId é opcional quando a chave só tem um estabelecimento.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`produtoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · DefinirQuantidadeDoDiaRequest)

Campo	Tipo	Obrigatório	Significado
`quantidade`	número inteiro ou nulo		A quantidade.
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/produtos/<produtoId>/quantidade-do-dia' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{}'

PUT/api/restauracao/produtos/{produtoId}/grupos#

Define, de uma vez, os grupos de opções que um artigo oferece, pela ordem dada.

Permissão Restauracao.CatalogoEditar

Uma lista vazia tira-lhe todos os grupos.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`produtoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · GruposDoProdutoRequest)

Campo	Tipo	Obrigatório
`grupoIds`	lista de identificador (UUID)	sim

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/produtos/<produtoId>/grupos' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "grupoIds": [
    "00000000-0000-0000-0000-000000000000"
  ]
}'

GET/api/restauracao/grupos-opcoes#

Os grupos de opções que um artigo pode oferecer, com as opções de cada um.

Permissão Restauracao.SalaLer

apenasActivos (por omissão, verdadeiro).

Parâmetros

Nome	Onde	Tipo	Obrigatório
`apenasActivos`	na pesquisa	verdadeiro/falso

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/grupos-opcoes' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/grupos-opcoes#

Cria um grupo de opções, com o mínimo e o máximo que se podem escolher e as opções.

Permissão Restauracao.CatalogoEditar
Idempotência aceita Idempotency-Key

Corpo do pedido (JSON · CriarGrupoDeOpcoesCommand)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`minimo`	número inteiro	sim
`maximo`	número inteiro	sim
`ordem`	número inteiro	sim
`opcoes`	lista de objectos	sim
`opcoes[].id`	identificador (UUID) ou nulo		Identificador único (UUID).
`opcoes[].nome`	texto	sim	O nome.
`opcoes[].produtoExtraId`	identificador (UUID) ou nulo
`opcoes[].ordem`	número inteiro
`opcoes[].activa`	verdadeiro/falso

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/grupos-opcoes' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "minimo": 1,
  "maximo": 1,
  "ordem": 1,
  "opcoes": [
    {
      "nome": "texto"
    }
  ]
}'

PUT/api/restauracao/grupos-opcoes/{id}#

Altera um grupo de opções (nome, mínimo, máximo, ordem, estado e opções).

Permissão Restauracao.CatalogoEditar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ActualizarGrupoRequest)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`minimo`	número inteiro	sim
`maximo`	número inteiro	sim
`ordem`	número inteiro	sim
`activo`	verdadeiro/falso	sim	Se está activo.
`opcoes`	lista de objectos	sim
`opcoes[].id`	identificador (UUID) ou nulo		Identificador único (UUID).
`opcoes[].nome`	texto	sim	O nome.
`opcoes[].produtoExtraId`	identificador (UUID) ou nulo
`opcoes[].ordem`	número inteiro
`opcoes[].activa`	verdadeiro/falso

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/grupos-opcoes/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "minimo": 1,
  "maximo": 1,
  "ordem": 1,
  "activo": false,
  "opcoes": [
    {
      "nome": "texto"
    }
  ]
}'

GET/api/restauracao/fichas#

As fichas técnicas dos pratos e das preparações.

Permissão Restauracao.CatalogoEditar

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/fichas' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/restauracao/fichas/{produtoId}#

A ficha técnica de um prato ou de uma preparação, com os ingredientes.

Permissão Restauracao.CatalogoEditar

lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`produtoId`	no caminho	identificador (UUID)	sim
`lojaId`	na pesquisa	identificador (UUID)

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/fichas/<produtoId>' \
  -H 'X-Api-Key: <a-sua-chave>'

PUT/api/restauracao/fichas/{produtoId}#

Cria ou substitui a ficha técnica de um prato ou de uma preparação.

Permissão Restauracao.CatalogoEditar

O artigo não pode ter stock próprio: com ficha, o stock desce pelos ingredientes (um artigo que também controlasse stock descia a dobrar na emissão). Um artigo de venda é um prato; um artigo de consumo interno, sem stock, é uma preparação (a ficha é por uma unidade dele).

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`produtoId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · DefinirFichaRequest)

Campo	Tipo	Obrigatório	Significado
`activa`	verdadeiro/falso	sim
`ingredientes`	lista de objectos	sim
`ingredientes[].ingredienteId`	identificador (UUID)	sim
`ingredientes[].quantidadePorDose`	número	sim
`ingredientes[].rendimentoPercentual`	número
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/fichas/<produtoId>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "activa": false,
  "ingredientes": [
    {
      "ingredienteId": "00000000-0000-0000-0000-000000000000",
      "quantidadePorDose": 0
    }
  ]
}'

GET/api/restauracao/ingredientes#

Os artigos que se podem pôr numa ficha: os activos que controlam stock e as preparações já definidas.

Permissão Restauracao.CatalogoEditar

filtro pesquisa por nome ou código; tamanho (por omissão 20).

Parâmetros

Nome	Onde	Tipo	Obrigatório
`filtro`	na pesquisa	texto

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/ingredientes' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/restauracao/preparacoes/candidatos#

Os artigos que podem passar a preparações: activos, de produto, sem stock próprio e que ainda não têm ficha.

Permissão Restauracao.CatalogoEditar

filtro pesquisa por nome ou código; tamanho (por omissão 20).

Parâmetros

Nome	Onde	Tipo	Obrigatório
`filtro`	na pesquisa	texto

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/preparacoes/candidatos' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/comandas#

Abre uma comanda numa mesa.

Permissão Restauracao.ComandaOperar
Idempotência aceita Idempotency-Key

mesaId e pessoas.

Corpo do pedido (JSON · AbrirComandaCommand)

Campo	Tipo	Obrigatório
`mesaId`	identificador (UUID)	sim
`pessoas`	número inteiro	sim

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/comandas' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "mesaId": "00000000-0000-0000-0000-000000000000",
  "pessoas": 1
}'

GET/api/restauracao/comandas/{id}#

Uma comanda com os itens e o estado da conta.

Permissão Restauracao.ComandaLer

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/comandas/<id>' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/restauracao/mesas/{mesaId}/comanda#

A comanda aberta de uma mesa, ou nada se a mesa está livre.

Permissão Restauracao.ComandaLer

Parâmetros

Nome	Onde	Tipo	Obrigatório
`mesaId`	no caminho	identificador (UUID)	sim

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/mesas/<mesaId>/comanda' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/comandas/{id}/itens#

Lança um artigo na comanda.

Permissão Restauracao.ComandaOperar
Idempotência aceita Idempotency-Key

produtoId é obrigatório; quantidade (por omissão 1), observacao, lugar, fase (Agora, Entrada, Principal ou Sobremesa, por omissão Agora), precoUnitario e opcaoIds são opcionais.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · LancarItemRequest)

Campo	Tipo	Obrigatório	Significado
`produtoId`	identificador (UUID)	sim	O artigo.
`quantidade`	número		A quantidade.
`observacao`	texto ou nulo		O texto livre.
`lugar`	número inteiro ou nulo
`fase`	uma de: «Agora», «Entrada», «Principal», «Sobremesa»
`precoUnitario`	número ou nulo		O preço de uma unidade, sem imposto.
`opcaoIds`	lista de identificador (UUID) ou nulo

Resposta

Devolve 201 com o id do registo criado.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/comandas/<id>/itens' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "produtoId": "00000000-0000-0000-0000-000000000000"
}'

PUT/api/restauracao/itens/{itemId}#

Altera a quantidade, a observação, o lugar ou a fase de um item.

Permissão Restauracao.ComandaOperar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`itemId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · AlterarItemRequest)

Campo	Tipo	Obrigatório	Significado
`quantidade`	número	sim	A quantidade.
`observacao`	texto ou nulo		O texto livre.
`lugar`	número inteiro ou nulo
`fase`	uma de: «Agora», «Entrada», «Principal», «Sobremesa»

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/itens/<itemId>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "quantidade": 0
}'

DELETE/api/restauracao/itens/{itemId}#

Remove um item pendente da comanda (que ainda não foi enviado).

Permissão Restauracao.ComandaOperar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`itemId`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X DELETE 'https://<endereço-da-API>/api/restauracao/itens/<itemId>' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/comandas/{id}/enviar#

Envia a comanda: um talão por posto com os itens pendentes das fases já pedidas.

Permissão Restauracao.ComandaOperar
Idempotência aceita Idempotency-Key

faseAPedir (opcional) é o «pedir principais»: liberta essa fase antes de enviar. Enviar sem nada pendente não faz nada.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON)

Campo	Tipo	Obrigatório
`faseAPedir`	uma de: «Agora», «Entrada», «Principal», «Sobremesa» ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/comandas/<id>/enviar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/restauracao/itens/{itemId}/servir#

Marca um item como servido.

Permissão Restauracao.ComandaOperar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`itemId`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/itens/<itemId>/servir' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/itens/{itemId}/iniciar#

Marca o início da preparação de um item.

Permissão Restauracao.KdsOperar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`itemId`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/itens/<itemId>/iniciar' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/itens/{itemId}/pronto#

Marca um item como pronto.

Permissão Restauracao.KdsOperar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`itemId`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/itens/<itemId>/pronto' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/itens/{itemId}/desfazer-pronto#

Desfaz o «pronto» nos 30 segundos seguintes (um toque enganado no ecrã).

Permissão Restauracao.KdsOperar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`itemId`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/itens/<itemId>/desfazer-pronto' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/itens/{itemId}/cancelar#

Cancela um item já enviado, com um motivo estruturado.

Permissão Restauracao.ComandaOperar
Idempotência aceita Idempotency-Key

motivo: ErroDeLancamento, ClienteDesistiu, CozinhaSemStock ou Cortesia.

Cancela directamente quem tem a permissão «Restauracao.ItemCancelar» (ou a de autorizar do ponto de venda); sem ela, o pedido devolve 428 com o que é preciso autorizar. O cancelamento fica sempre no registo de auditoria, como acção sensível.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`itemId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · CancelarItemRequest)

Campo	Tipo	Obrigatório	Significado
`motivo`	uma de: «ErroDeLancamento», «ClienteDesistiu», «CozinhaSemStock», «Cortesia»	sim
`observacao`	texto ou nulo		O texto livre.
`autorizacaoSupervisorId`	identificador (UUID) ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/itens/<itemId>/cancelar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "motivo": "ErroDeLancamento"
}'

POST/api/restauracao/itens/{itemId}/pedir-cancelamento#

O posto (a cozinha, o bar) pede que um item já enviado seja cancelado: não o cancela, avisa o supervisor, que o vê na comanda e decide.

Permissão Restauracao.KdsOperar
Idempotência aceita Idempotency-Key

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`itemId`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · PedirCancelamentoRequest)

Campo	Tipo	Obrigatório
`motivo`	uma de: «ErroDeLancamento», «ClienteDesistiu», «CozinhaSemStock», «Cortesia»	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/itens/<itemId>/pedir-cancelamento' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "motivo": "ErroDeLancamento"
}'

POST/api/restauracao/itens/{itemId}/dispensar-pedido-cancelamento#

Quem tem a comanda (o garçom ou o supervisor) dispensa o pedido de cancelamento da cozinha: o item fica como estava.

Permissão Restauracao.ComandaOperar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`itemId`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/itens/<itemId>/dispensar-pedido-cancelamento' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/comandas/{id}/anular#

Anula uma comanda.

Permissão Restauracao.ComandaOperar
Idempotência aceita Idempotency-Key

motivo (opcional).

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON)

Campo	Tipo	Obrigatório
`motivo`	texto ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/comandas/<id>/anular' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/restauracao/comandas/{id}/transferir#

Passa a comanda inteira para outra mesa.

Permissão Restauracao.ComandaTransferir
Idempotência aceita Idempotency-Key

A mesa de destino tem de estar livre, limpa, activa e no mesmo estabelecimento.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · TransferirComandaRequest)

Campo	Tipo	Obrigatório
`mesaDestinoId`	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/comandas/<id>/transferir' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "mesaDestinoId": "00000000-0000-0000-0000-000000000000"
}'

POST/api/restauracao/comandas/{id}/juntar-mesas#

Junta mesas livres à comanda (um grupo grande que ocupa duas ou três mesas): continua a haver uma só conta.

Permissão Restauracao.ComandaTransferir
Idempotência aceita Idempotency-Key

As mesas têm de estar livres, limpas, activas e no mesmo estabelecimento.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · JuntarMesasRequest)

Campo	Tipo	Obrigatório
`mesaIds`	lista de identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/comandas/<id>/juntar-mesas' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "mesaIds": [
    "00000000-0000-0000-0000-000000000000"
  ]
}'

POST/api/restauracao/comandas/{id}/separar-mesa#

Separa uma mesa que estava junta: fica livre e a comanda continua com as outras.

Permissão Restauracao.ComandaTransferir
Idempotência aceita Idempotency-Key

A mesa principal não se separa.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · SepararMesaRequest)

Campo	Tipo	Obrigatório
`mesaId`	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/comandas/<id>/separar-mesa' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "mesaId": "00000000-0000-0000-0000-000000000000"
}'

POST/api/restauracao/comandas/{id}/trocar-garcom#

Reatribui a mesa a outro garçom do mesmo estabelecimento.

Permissão Restauracao.ComandaTransferir
Idempotência aceita Idempotency-Key

É uma decisão de supervisor.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · TrocarGarcomRequest)

Campo	Tipo	Obrigatório
`novoGarcomUserId`	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/comandas/<id>/trocar-garcom' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "novoGarcomUserId": "00000000-0000-0000-0000-000000000000"
}'

POST/api/restauracao/comandas/{id}/mover-itens#

Passa itens (todos da mesma comanda) para outra comanda aberta do mesmo estabelecimento.

Permissão Restauracao.ComandaTransferir
Idempotência aceita Idempotency-Key

O {id} do caminho é a comanda de destino; itemIds são os itens a passar. Devolve itensMovidos, o número de itens que mudaram.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · MoverItensRequest)

Campo	Tipo	Obrigatório
`itemIds`	lista de identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/comandas/<id>/mover-itens' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "itemIds": [
    "00000000-0000-0000-0000-000000000000"
  ]
}'

GET/api/restauracao/comandas/{id}/pre-conta#

A pré-conta, sem mexer na mesa: o que falta cobrar.

Permissão Restauracao.ComandaLer

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/comandas/<id>/pre-conta' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/comandas/{id}/pedir-conta#

O cliente pede a conta: a mesa passa a «à espera de conta» e devolve-se a pré-conta.

Permissão Restauracao.ComandaOperar

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/comandas/<id>/pedir-conta' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/comandas/{id}/reabrir-conta#

Reabre a conta: o cliente afinal pede mais, ou a conta foi pedida por engano, e a mesa volta a «ocupada».

Permissão Restauracao.ComandaOperar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/comandas/<id>/reabrir-conta' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/comandas/{id}/consulta-de-mesa#

Emite a Consulta de Mesa com tudo o que falta cobrar na comanda e passa a mesa a «conta pedida».

Permissão Restauracao.ComandaOperar
Idempotência aceita Idempotency-Key

Pode emitir-se várias vezes (cada uma com o seu número), por exemplo depois de a mesa pedir mais. Os itens por enviar à cozinha têm de se enviar antes: a consulta diz o que a mesa consumiu, e o que se vai cobrar é exactamente isso.

Envie Idempotency-Key: repetir o pedido não o executa duas vezes. Ver Idempotência.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON)

Campo	Tipo	Obrigatório	Significado
`clienteId`	identificador (UUID) ou nulo		O cliente do documento.

Erros específicos

IDEMPOTENCIA_CONFLITO — além dos gerais.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/comandas/<id>/consulta-de-mesa' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET/api/restauracao/comandas/{id}/consultas-de-mesa#

As consultas de mesa já emitidas para uma comanda, da mais recente para a mais antiga.

Permissão Restauracao.ComandaLer

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/comandas/<id>/consultas-de-mesa' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/comandas/{id}/cobrar#

Cobra uma parte da conta (ou toda) com um documento fiscal do núcleo: factura/recibo («FR», paga no acto) ou factura («FT», a crédito a um cliente especial).

Permissão Restauracao.ComandaOperar
Idempotência aceita Idempotency-Key

Sem linhas cobra tudo o que falta; com elas, só essas quantidades (dividir a conta por pessoas). O documento é emitido pelo fluxo de sempre (numeração, assinatura, IVA, caixa, stock, facturação electrónica), e a ligação à comanda grava-se na mesma transacção. Quando tudo está cobrado e a cozinha não tem nada em aberto, a comanda fecha e a mesa passa a «suja».

Envie Idempotency-Key: repetir o pedido não o executa duas vezes. Ver Idempotência.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · CobrarRequest)

Campo	Tipo	Obrigatório	Significado
`tipoDocumento`	texto	sim
`pagamentos`	lista de objectos	sim
`pagamentos[].metodoPagamentoId`	identificador (UUID)	sim	O método de pagamento.
`pagamentos[].valor`	número	sim	O valor.
`pagamentos[].numeroOperacaoBancaria`	texto ou nulo		O número da operação bancária (opcional).
`pagamentos[].dataOperacaoBancaria`	data e hora (ISO 8601) ou nulo		A data da operação bancária (opcional).
`linhas`	lista de objectos ou nulo
`linhas[].itemId`	identificador (UUID)	sim
`linhas[].quantidade`	número	sim	A quantidade.
`clienteId`	identificador (UUID) ou nulo		O cliente do documento.
`observacao`	texto ou nulo		O texto livre.
`armazemId`	identificador (UUID) ou nulo		O armazém de onde saiu (ou para onde voltou) o stock.
`dataVencimento`	data (AAAA-MM-DD) ou nulo		O dia do vencimento (facturas a crédito) ou da validade (cotações).
`descontoFinanceiroPercentual`	número		O desconto financeiro do documento aplicado a esta linha, em percentagem.
`autorizacaoSupervisorId`	identificador (UUID) ou nulo
`aplicarPromocoes`	verdadeiro/falso
`promocoesPermitidas`	lista de identificador (UUID) ou nulo

Erros específicos

IDEMPOTENCIA_CONFLITO — além dos gerais.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/comandas/<id>/cobrar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "tipoDocumento": "texto",
  "pagamentos": [
    {
      "metodoPagamentoId": "00000000-0000-0000-0000-000000000000",
      "valor": 0
    }
  ]
}'

GET/api/restauracao/relatorio#

O relatório da restauração de um período.

Permissão Restauracao.RelatoriosLer

inicio e fim são obrigatórios. lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`inicio`	na pesquisa	data (AAAA-MM-DD)	sim
`fim`	na pesquisa	data (AAAA-MM-DD)	sim
`lojaId`	na pesquisa	identificador (UUID)

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/relatorio' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/restauracao/engenharia-do-menu#

A engenharia do menu de um período.

Permissão Restauracao.RelatoriosLer

inicio e fim são obrigatórios. lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`inicio`	na pesquisa	data (AAAA-MM-DD)	sim
`fim`	na pesquisa	data (AAAA-MM-DD)	sim
`lojaId`	na pesquisa	identificador (UUID)

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/engenharia-do-menu' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/restauracao/reposicao#

A reposição de ingredientes: o que repor, com base no consumo recente.

Permissão Restauracao.RelatoriosLer

dias (por omissão 14) e diasAlvo (por omissão 7, no máximo 30) parametrizam o cálculo. lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo
`dias`	na pesquisa	número inteiro
`diasAlvo`	na pesquisa	número inteiro
`lojaId`	na pesquisa	identificador (UUID)

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/reposicao' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/restauracao/auditoria#

O registo de auditoria da sala, pesquisável por operador, mesa, tipo de acção e período.

Permissão Restauracao.AuditoriaLer

Do mais recente para o mais antigo: para paginar, passe o ocorridoEmUtc do último registo recebido. apenasSensiveis e limite (por omissão 100) restringem a lista. lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo
`lojaId`	na pesquisa	identificador (UUID)
`userId`	na pesquisa	identificador (UUID)
`mesaId`	na pesquisa	identificador (UUID)
`accao`	na pesquisa	texto
`de`	na pesquisa	data e hora (ISO 8601)
`ate`	na pesquisa	data e hora (ISO 8601)
`apenasSensiveis`	na pesquisa	verdadeiro/falso
`limite`	na pesquisa	número inteiro

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/auditoria' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/restauracao/reservas#

As reservas de mesa de um dia, por hora.

Permissão Restauracao.SalaLer

dia (AAAA-MM-DD, na hora de Luanda; por omissão, hoje). Por omissão só vêm as que ainda contam (confirmadas, já chegadas e sentadas); com todas=true vêm também as faltadas e as canceladas. lojaId é opcional quando a chave só tem um estabelecimento.

Parâmetros

Nome	Onde	Tipo
`dia`	na pesquisa	data (AAAA-MM-DD)
`lojaId`	na pesquisa	identificador (UUID)
`todas`	na pesquisa	verdadeiro/falso

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/reservas' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/restauracao/reservas/{id}#

Uma reserva de mesa.

Permissão Restauracao.SalaLer

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl 'https://<endereço-da-API>/api/restauracao/reservas/<id>' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/reservas#

Cria uma reserva de mesa.

Permissão Restauracao.ComandaOperar
Idempotência aceita Idempotency-Key

nome, pessoas (1 a 50), inicio e, opcionalmente, mesaId, telefone, duracaoMin (15 a 480; 90 por omissão) e nota. Só se guarda o nome e, se o cliente quiser, o telefone. Não se reserva no passado, nem uma mesa que não tenha lugares para todos. lojaId é opcional quando a chave só tem um estabelecimento.

A mesma mesa não se reserva a duas pessoas ao mesmo tempo: a segunda recebe 400 com o código MESA_RESERVADA. Uma reserva sem mesa fica «por atribuir» e não ocupa nenhuma. Não há depósito.

Envie Idempotency-Key: repetir o pedido não o executa duas vezes. Ver Idempotência.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`lojaId`	na pesquisa	identificador (UUID)

Corpo do pedido (JSON · ReservaDeMesaRequest)

Campo	Tipo	Obrigatório	Significado
`mesaId`	identificador (UUID) ou nulo
`nome`	texto	sim	O nome.
`telefone`	texto ou nulo		O telefone.
`pessoas`	número inteiro	sim
`inicio`	data e hora (ISO 8601)	sim
`duracaoMin`	número inteiro
`nota`	texto ou nulo

Resposta

Devolve 201 com o id do registo criado.

Erros específicos

MESA_RESERVADA · IDEMPOTENCIA_CONFLITO — além dos gerais.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/reservas' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "pessoas": 1,
  "inicio": "2026-10-12T09:00:00Z"
}'

PUT/api/restauracao/reservas/{id}#

Altera uma reserva que ainda espera o cliente (mesa, hora, duração, pessoas, telefone e nota).

Permissão Restauracao.ComandaOperar

Os mesmos campos da criação. Só se altera enquanto a reserva está confirmada ou o cliente já chegou. Pode devolver MESA_RESERVADA.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · ReservaDeMesaRequest)

Campo	Tipo	Obrigatório	Significado
`mesaId`	identificador (UUID) ou nulo
`nome`	texto	sim	O nome.
`telefone`	texto ou nulo		O telefone.
`pessoas`	número inteiro	sim
`inicio`	data e hora (ISO 8601)	sim
`duracaoMin`	número inteiro
`nota`	texto ou nulo

Erros específicos

MESA_RESERVADA — além dos gerais.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/restauracao/reservas/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "pessoas": 1,
  "inicio": "2026-10-12T09:00:00Z"
}'

POST/api/restauracao/reservas/{id}/chegou#

Regista a chegada do cliente.

Permissão Restauracao.ComandaOperar

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/reservas/<id>/chegou' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/reservas/{id}/sentar#

Regista que o cliente se sentou (a reserva cumpriu-se e a mesa fica livre da reserva).

Permissão Restauracao.ComandaOperar
Idempotência aceita Idempotency-Key

comandaId (opcional) liga a reserva à comanda aberta da mesa; tem de ser dessa mesa e estar aberta.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON)

Campo	Tipo	Obrigatório
`comandaId`	identificador (UUID) ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/reservas/<id>/sentar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/restauracao/reservas/{id}/faltou#

Regista que o cliente não veio.

Permissão Restauracao.ComandaOperar

Só depois da hora marcada e antes de o cliente chegar.

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/reservas/<id>/faltou' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/restauracao/reservas/{id}/cancelar#

Cancela uma reserva e liberta a mesa.

Permissão Restauracao.ComandaOperar
Idempotência aceita Idempotency-Key

motivo é obrigatório (até 300 caracteres).

Devolve 204, sem corpo.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · CancelarReservaDeMesaRequest)

Campo	Tipo	Obrigatório
`motivo`	texto	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/restauracao/reservas/<id>/cancelar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "motivo": "texto"
}'