Referência

Promoções

As promoções: criar, aprovar, pausar, terminar, simular o que acontece a uma venda e ver o que renderam e custaram.

Operação	O que faz
GET `/api/promocoes`	Lista as promoções.
GET `/api/promocoes/relatorio`	O que as promoções renderam e custaram num período, com o período anterior ao lado, por operador e por caixa, e os alertas.
GET `/api/promocoes/pdv`	A descarga das promoções para um ponto de venda.
GET `/api/promocoes/{id}`	Uma promoção, com as regras.
POST `/api/promocoes`	Cria uma promoção (fica em rascunho).
PUT `/api/promocoes/{id}`	Altera uma promoção em rascunho.
POST `/api/promocoes/{id}/aprovar`	Aprova uma promoção: passa a valer.
POST `/api/promocoes/{id}/pausar`	Pausa uma promoção (com um motivo, opcional).
POST `/api/promocoes/{id}/retomar`	Retoma uma promoção pausada.
POST `/api/promocoes/{id}/reabrir`	Reabre uma promoção como rascunho, para a poder alterar.
POST `/api/promocoes/{id}/terminar`	Termina uma promoção (com um motivo, opcional).
POST `/api/promocoes/{id}/duplicar`	Duplica uma promoção, como rascunho.
POST `/api/promocoes/simular`	Simula o que as promoções fazem a uma venda: as linhas, os descontos e o total, sem emitir nada.

GET/api/promocoes#

Lista as promoções.

Permissão Promocoes.Ler

situacao e pesquisa filtram.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`situacao`	na pesquisa	uma de: «Rascunho», «Agendada», «Activa», «Pausada», «Terminada», «null»
`pesquisa`	na pesquisa	texto

Pedido

curl

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

GET/api/promocoes/relatorio#

O que as promoções renderam e custaram num período, com o período anterior ao lado, por operador e por caixa, e os alertas.

Permissão Promocoes.Ler

dataInicio e dataFim obrigatórias; lojaId limita a um estabelecimento.

Parâmetros

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

Pedido

curl

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

GET/api/promocoes/pdv#

A descarga das promoções para um ponto de venda.

Permissão Documentos.Emitir

Funciona como os catálogos: com If-None-Match e a versão que já tem, a resposta é 304 sem corpo enquanto nada mudou.

Pedido

curl

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

GET/api/promocoes/{id}#

Uma promoção, com as regras.

Permissão Promocoes.Ler

Parâmetros

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

Pedido

curl

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

POST/api/promocoes#

Cria uma promoção (fica em rascunho).

Permissão Promocoes.Editar
Idempotência aceita Idempotency-Key

Devolve o id.

Corpo do pedido (JSON · DadosPromocao)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`nomeCurto`	texto	sim
`descricao`	texto ou nulo		A descrição.
`tipo`	uma de: «LeveXPagueY», «PercentagemDesconto», «DescontoValor», «PrecoEspecial», «PrecoPorQuantidade», «Conjunto», «OfertaArtigo», «DescontoCompraTotal», «PrecoCliente»	sim
`todosOsArtigos`	verdadeiro/falso
`produtoIds`	lista de identificador (UUID)
`categoriaIds`	lista de identificador (UUID)
`produtosExcluidosIds`	lista de identificador (UUID)
`categoriasExcluidasIds`	lista de identificador (UUID)
`unidades`	uma de: «Ambas», «SoBase», «SoAlternativas»
`leveX`	número inteiro ou nulo
`pagueY`	número inteiro ou nulo
`percentagem`	número ou nulo
`valorDesconto`	número ou nulo		O valor do desconto.
`preco`	número ou nulo
`escaloes`	lista de objectos
`escaloes[].quantidadeMinima`	número	sim
`escaloes[].precoUnitario`	número	sim	O preço de uma unidade, sem imposto.
`itensPack`	lista de objectos
`itensPack[].produtoId`	identificador (UUID)	sim	O artigo.
`itensPack[].quantidade`	número	sim	A quantidade.
`precoPack`	número ou nulo
`produtoOferecidoId`	identificador (UUID) ou nulo
`quantidadeOferecida`	número ou nulo
`inicio`	data e hora (ISO 8601)	sim
`fim`	data e hora (ISO 8601) ou nulo
`diasSemana`	número inteiro
`horaInicio`	texto ou nulo
`horaFim`	texto ou nulo
`clienteIds`	lista de identificador (UUID)
`quantidadeMinima`	número ou nulo
`valorMinimo`	número ou nulo
`metodoPagamentoIds`	lista de identificador (UUID)
`lojaIds`	lista de identificador (UUID)
`limiteUsosTotal`	número inteiro ou nulo
`limiteUsosPorCliente`	número inteiro ou nulo
`limiteAplicacoesPorVenda`	número inteiro ou nulo
`stockPromocional`	número ou nulo
`prioridade`	número inteiro
`acumula`	verdadeiro/falso
`permiteDescontoManual`	verdadeiro/falso

Pedido

curl

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

PUT/api/promocoes/{id}#

Altera uma promoção em rascunho.

Permissão Promocoes.Editar

Parâmetros

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

Corpo do pedido (JSON · DadosPromocao)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`nomeCurto`	texto	sim
`descricao`	texto ou nulo		A descrição.
`tipo`	uma de: «LeveXPagueY», «PercentagemDesconto», «DescontoValor», «PrecoEspecial», «PrecoPorQuantidade», «Conjunto», «OfertaArtigo», «DescontoCompraTotal», «PrecoCliente»	sim
`todosOsArtigos`	verdadeiro/falso
`produtoIds`	lista de identificador (UUID)
`categoriaIds`	lista de identificador (UUID)
`produtosExcluidosIds`	lista de identificador (UUID)
`categoriasExcluidasIds`	lista de identificador (UUID)
`unidades`	uma de: «Ambas», «SoBase», «SoAlternativas»
`leveX`	número inteiro ou nulo
`pagueY`	número inteiro ou nulo
`percentagem`	número ou nulo
`valorDesconto`	número ou nulo		O valor do desconto.
`preco`	número ou nulo
`escaloes`	lista de objectos
`escaloes[].quantidadeMinima`	número	sim
`escaloes[].precoUnitario`	número	sim	O preço de uma unidade, sem imposto.
`itensPack`	lista de objectos
`itensPack[].produtoId`	identificador (UUID)	sim	O artigo.
`itensPack[].quantidade`	número	sim	A quantidade.
`precoPack`	número ou nulo
`produtoOferecidoId`	identificador (UUID) ou nulo
`quantidadeOferecida`	número ou nulo
`inicio`	data e hora (ISO 8601)	sim
`fim`	data e hora (ISO 8601) ou nulo
`diasSemana`	número inteiro
`horaInicio`	texto ou nulo
`horaFim`	texto ou nulo
`clienteIds`	lista de identificador (UUID)
`quantidadeMinima`	número ou nulo
`valorMinimo`	número ou nulo
`metodoPagamentoIds`	lista de identificador (UUID)
`lojaIds`	lista de identificador (UUID)
`limiteUsosTotal`	número inteiro ou nulo
`limiteUsosPorCliente`	número inteiro ou nulo
`limiteAplicacoesPorVenda`	número inteiro ou nulo
`stockPromocional`	número ou nulo
`prioridade`	número inteiro
`acumula`	verdadeiro/falso
`permiteDescontoManual`	verdadeiro/falso

Pedido

curl

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

POST/api/promocoes/{id}/aprovar#

Aprova uma promoção: passa a valer.

Permissão Promocoes.Aprovar

Precisa da permissão de aprovar promoções.

Parâmetros

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

Pedido

curl

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

POST/api/promocoes/{id}/pausar#

Pausa uma promoção (com um motivo, opcional).

Permissão Promocoes.Aprovar
Idempotência aceita Idempotency-Key

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/promocoes/<id>/pausar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/promocoes/{id}/retomar#

Retoma uma promoção pausada.

Permissão Promocoes.Aprovar

Parâmetros

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

Pedido

curl

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

POST/api/promocoes/{id}/reabrir#

Reabre uma promoção como rascunho, para a poder alterar.

Permissão Promocoes.Editar

Parâmetros

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

Pedido

curl

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

POST/api/promocoes/{id}/terminar#

Termina uma promoção (com um motivo, opcional).

Permissão Promocoes.Aprovar
Idempotência aceita Idempotency-Key

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/promocoes/<id>/terminar' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/promocoes/{id}/duplicar#

Duplica uma promoção, como rascunho.

Permissão Promocoes.Editar

Devolve o id da cópia.

Parâmetros

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

Pedido

curl

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

POST/api/promocoes/simular#

Simula o que as promoções fazem a uma venda: as linhas, os descontos e o total, sem emitir nada.

Permissão Promocoes.Ler
Idempotência aceita Idempotency-Key

Corpo do pedido (JSON · SimularPromocoesQuery)

Campo	Tipo	Obrigatório	Significado
`linhas`	lista de objectos	sim
`linhas[].produtoId`	identificador (UUID)	sim	O artigo.
`linhas[].quantidade`	número	sim	A quantidade.
`linhas[].unidadeVendaId`	identificador (UUID) ou nulo
`linhas[].precoUnitario`	número ou nulo		O preço de uma unidade, sem imposto.
`linhas[].descontoManualPercentual`	número
`clienteId`	identificador (UUID) ou nulo		O cliente do documento.
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`metodosPagamento`	lista de identificador (UUID) ou nulo
`agora`	data e hora (ISO 8601) ou nulo
`promocaoEmTeste`	objecto ou nulo
`promocaoEmTeste.nome`	texto	sim	O nome.
`promocaoEmTeste.nomeCurto`	texto	sim
`promocaoEmTeste.descricao`	texto ou nulo		A descrição.
`promocaoEmTeste.tipo`	uma de: «LeveXPagueY», «PercentagemDesconto», «DescontoValor», «PrecoEspecial», «PrecoPorQuantidade», «Conjunto», «OfertaArtigo», «DescontoCompraTotal», «PrecoCliente»	sim
`promocaoEmTeste.todosOsArtigos`	verdadeiro/falso
`promocaoEmTeste.produtoIds`	lista de identificador (UUID)
`promocaoEmTeste.categoriaIds`	lista de identificador (UUID)
`promocaoEmTeste.produtosExcluidosIds`	lista de identificador (UUID)
`promocaoEmTeste.categoriasExcluidasIds`	lista de identificador (UUID)
`promocaoEmTeste.unidades`	uma de: «Ambas», «SoBase», «SoAlternativas»
`promocaoEmTeste.leveX`	número inteiro ou nulo
`promocaoEmTeste.pagueY`	número inteiro ou nulo
`promocaoEmTeste.percentagem`	número ou nulo
`promocaoEmTeste.valorDesconto`	número ou nulo		O valor do desconto.
`promocaoEmTeste.preco`	número ou nulo
`promocaoEmTeste.escaloes`	lista de objectos
`promocaoEmTeste.escaloes[].quantidadeMinima`	número	sim
`promocaoEmTeste.escaloes[].precoUnitario`	número	sim	O preço de uma unidade, sem imposto.
`promocaoEmTeste.itensPack`	lista de objectos
`promocaoEmTeste.itensPack[].produtoId`	identificador (UUID)	sim	O artigo.
`promocaoEmTeste.itensPack[].quantidade`	número	sim	A quantidade.
`promocaoEmTeste.precoPack`	número ou nulo
`promocaoEmTeste.produtoOferecidoId`	identificador (UUID) ou nulo
`promocaoEmTeste.quantidadeOferecida`	número ou nulo
`promocaoEmTeste.inicio`	data e hora (ISO 8601)	sim
`promocaoEmTeste.fim`	data e hora (ISO 8601) ou nulo
`promocaoEmTeste.diasSemana`	número inteiro
`promocaoEmTeste.horaInicio`	texto ou nulo
`promocaoEmTeste.horaFim`	texto ou nulo
`promocaoEmTeste.clienteIds`	lista de identificador (UUID)
`promocaoEmTeste.quantidadeMinima`	número ou nulo
`promocaoEmTeste.valorMinimo`	número ou nulo
`promocaoEmTeste.metodoPagamentoIds`	lista de identificador (UUID)
`promocaoEmTeste.lojaIds`	lista de identificador (UUID)
`promocaoEmTeste.limiteUsosTotal`	número inteiro ou nulo
`promocaoEmTeste.limiteUsosPorCliente`	número inteiro ou nulo
`promocaoEmTeste.limiteAplicacoesPorVenda`	número inteiro ou nulo
`promocaoEmTeste.stockPromocional`	número ou nulo
`promocaoEmTeste.prioridade`	número inteiro
`promocaoEmTeste.acumula`	verdadeiro/falso
`promocaoEmTeste.permiteDescontoManual`	verdadeiro/falso
`substituiPromocaoId`	identificador (UUID) ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/promocoes/simular' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "linhas": [
    {
      "produtoId": "00000000-0000-0000-0000-000000000000",
      "quantidade": 0
    }
  ]
}'