Referência

Artigos

Produtos e serviços: o cadastro, os níveis de preço, o imposto e a pesquisa para venda com o saldo de stock.

Produtos e serviços: o cadastro, os níveis de preço, o imposto e a pesquisa para venda com o saldo de stock.

OperaçãoO que faz
GET /api/produtosLista os artigos (produtos e serviços) com os preços e o custo.
GET /api/produtos/{id}O cadastro completo de um artigo.
GET /api/produtos/{id}/historico-custosO histórico do custo de um artigo: o custo unitário, desde quando vigora e de onde veio (compra ou actualização).
GET /api/produtos/pesquisa-vendaA pesquisa de artigos para vender: preços de todos os níveis, imposto e o saldo de stock no armazém.
GET /api/produtos/mais-vendidos-pdvOs identificadores dos artigos que mais saem: o separador «Mais vendidos» do ponto de venda.
GET /api/produtos/grupos-variacaoOs grupos de variação: artigos que são variações um do outro (tamanho, cor).
POST /api/produtosCria um artigo.
PUT /api/produtos/{id}Actualiza o cadastro de um artigo.
POST /api/produtos/{id}/activarVolta a activar um artigo desactivado.
POST /api/produtos/{id}/desactivarDesactiva um artigo: deixa de poder ser vendido, mas o histórico fica.
GET /api/produtos/sincronizacao-vendaO catálogo completo de artigos para venda, para guardar numa cópia local (sincronização de um ponto de venda ou de uma loja online).
PUT /api/produtos/{id}/composicaoDefine a composição de um conjunto (kit): os artigos e as quantidades que o formam.
POST /api/produtos/grupos-variacaoCria um grupo de variações («Camisola Polo»).
PUT /api/produtos/grupos-variacao/{id}Renomeia um grupo de variações.
DELETE /api/produtos/grupos-variacao/{id}Elimina um grupo de variações.
PUT /api/produtos/{id}/variacaoDefine o grupo e a variação («M · Azul») de um artigo.
POST /api/produtos/{id}/variacoesCria uma variação de um artigo, por cópia.
POST /api/produtos/{id}/variacoes/em-serieCria todas as variações de uma vez (tamanhos × cores).
PUT /api/produtos/{id}/unidades-vendaDefine as unidades de venda de um artigo (caixa, dúzia, unidade…).
POST /api/produtos/catalogos/{tipo}Cria um item de um catálogo de apoio dos artigos.
PUT /api/produtos/catalogos/{tipo}/{id}Altera um item de um catálogo de apoio dos artigos.
POST /api/produtos/catalogos/{tipo}/{id}/activarActiva um item de um catálogo de apoio.
POST /api/produtos/catalogos/{tipo}/{id}/desactivarDesactiva um item de um catálogo de apoio.
GET/api/produtos#

Lista os artigos (produtos e serviços) com os preços e o custo.

  • Permissão Produtos.Ler

filtro procura no nome, no código interno e no código de barras. apenasActivos (por omissão falso) esconde os desactivados. Com alteradoDesde (data e hora ISO 8601 em UTC) só vêm os criados ou alterados desde esse instante, por ordem de alteração, e os desactivados aparecem sempre: ver Sincronização incremental.

A resposta é uma página: itens e proximoCursor. Ver Paginação.

Parâmetros

NomeOndeTipoObrigatório
filtrona pesquisatexto
apenasActivosna pesquisaverdadeiro/falso
cursorna pesquisatexto
tamanhona pesquisanúmero inteiro
paraVendana pesquisaverdadeiro/falso
alteradoDesdena pesquisadata e hora (ISO 8601)
estocavelna pesquisaverdadeiro/falso
lojaIdna pesquisaidentificador (UUID)

Resposta (200 · JSON)

CampoTipoSignificado
itenslista de objectosOs registos desta página.
itens[].ididentificador (UUID)Identificador único (UUID).
itens[].codigoInternotexto ou nuloO código interno do artigo.
itens[].codigoBarratexto ou nuloO código de barras.
itens[].nometextoO nome.
itens[].tipoProdutotextoProduto (com stock) ou Servico.
itens[].pvp1númeroO preço de venda do nível 1, sem imposto.
itens[].precoCustonúmero ou nuloO custo do artigo.
itens[].activoverdadeiro/falsoSe está activo.
itens[].grupoVariacaoNometexto ou nulo
itens[].variacaotexto ou nulo
itens[].paraVendaverdadeiro/falso
itens[].alteradoEmUtcdata e hora (ISO 8601)
proximoCursortexto ou nuloO cursor da página seguinte; nulo quando não há mais. Ver Paginação.

Exemplo

Listar artigos (filtro por nome, código interno ou código de barras)

Pedido
curl 'https://<endereço-da-API>/api/produtos?tamanho=1&filtro=arroz' \
  -H 'X-Api-Key: assw_v1_<chave>'
Pedido
const resposta = await fetch('https://<endereço-da-API>/api/produtos?tamanho=1&filtro=arroz', {
  method: 'GET',
  headers: {
    "X-Api-Key": "assw_v1_<chave>"
  },
})
const dados = await resposta.json()
Pedido
import requests

resposta = requests.get(
    'https://<endereço-da-API>/api/produtos?tamanho=1&filtro=arroz',
    headers={
        'X-Api-Key': 'assw_v1_<chave>'
    },
)
dados = resposta.json()
Pedido
using var cliente = new HttpClient { BaseAddress = new Uri("https://<endereço-da-API>") };
using var pedido = new HttpRequestMessage(HttpMethod.Get, "/api/produtos?tamanho=1&filtro=arroz");
pedido.Headers.Add("X-Api-Key", "assw_v1_<chave>");
using var resposta = await cliente.SendAsync(pedido);
var texto = await resposta.Content.ReadAsStringAsync();

200 OK Resposta

Resposta
content-type: application/json; charset=utf-8
x-mucanda-api-version: 1

{
  "itens": [
    {
      "id": "01a12201-fa97-7f9b-8eec-2f731b91a53b",
      "codigoInterno": "MC0001",
      "codigoBarra": "560000100137",
      "nome": "Arroz agulha 5 kg",
      "tipoProduto": "Produto",
      "pvp1": 6500,
      "precoCusto": 5000,
      "activo": true,
      "grupoVariacaoNome": null,
      "variacao": null
    }
  ],
  "proximoCursor": "QXJyb3ogYWd1bGhhIDUga2cgMDFhMTIyMDEtZmE5Ny03ZjliLThlZWMtMmY3MzFiOTFhNTNi"
}
GET/api/produtos/{id}#

O cadastro completo de um artigo.

  • Permissão Produtos.Ler

Parâmetros

NomeOndeTipoObrigatório
idno caminhoidentificador (UUID)sim

Resposta (200 · JSON)

CampoTipoSignificado
ididentificador (UUID)Identificador único (UUID).
codigoInternotexto ou nuloO código interno do artigo.
codigoBarratexto ou nuloO código de barras.
nometextoO nome.
descricaotexto ou nuloA descrição.
tipoProdutotextoProduto (com stock) ou Servico.
impostoIdidentificador (UUID)
motivoIsencaoIvaIdidentificador (UUID) ou nulo
taxaRetencaoIdidentificador (UUID) ou nulo
categoriaIdidentificador (UUID) ou nulo
unidadeIdidentificador (UUID) ou nulo
marcaIdidentificador (UUID) ou nulo
modeloIdidentificador (UUID) ou nulo
fabricanteIdidentificador (UUID) ou nulo
tamanhoIdidentificador (UUID) ou nulo
fornecedorIdidentificador (UUID) ou nulo
estocavelverdadeiro/falso
estoqueMinimonúmero ou nulo
controlarValidadeverdadeiro/falso
compostoverdadeiro/falso
informarPrecoNoPdvverdadeiro/falso
precificacaoAvancadaverdadeiro/falso
variadoverdadeiro/falso
itemCozinhaverdadeiro/falso
mostrarDescricaoNaFacturaverdadeiro/falso
activoverdadeiro/falsoSe está activo.
precoCustonúmero ou nuloO custo do artigo.
lucroPvp1número
pvp1númeroO preço de venda do nível 1, sem imposto.
lucroPvp2número
pvp2númeroO preço de venda do nível 2, sem imposto.
lucroPvp3número
pvp3númeroO preço de venda do nível 3, sem imposto.
lucroPvp4número
pvp4númeroO preço de venda do nível 4, sem imposto.
paisOrigemIdidentificador (UUID) ou nulo
origemtexto ou nulo
pesonúmero ou nulo
comprimentonúmero ou nulo
larguranúmero ou nulo
alturanúmero ou nulo
tipoInventarioFiscaltexto ou nulo
valorCifnúmero ou nulo
despesasTransportenúmero ou nulo
despesasArmazenagemnúmero ou nulo
encargosAduaneirosnúmero ou nulo
despesasBancariasnúmero ou nulo
encargosGeraisnúmero ou nulo
composicaolista de objectos
composicao[].ididentificador (UUID)Identificador único (UUID).
composicao[].produtoAssociadoIdidentificador (UUID)
composicao[].quantidadenúmeroA quantidade.
composicao[].precoUnitarionúmeroO preço de uma unidade, sem imposto.
composicao[].produtoAssociadoNometexto ou nulo
unidadesVendalista de objectos
unidadesVenda[].ididentificador (UUID)Identificador único (UUID).
unidadesVenda[].unidadeIdidentificador (UUID)
unidadesVenda[].nometextoO nome.
unidadesVenda[].factornúmero
unidadesVenda[].pvp1número ou nuloO preço de venda do nível 1, sem imposto.
unidadesVenda[].pvp2número ou nuloO preço de venda do nível 2, sem imposto.
unidadesVenda[].pvp3número ou nuloO preço de venda do nível 3, sem imposto.
unidadesVenda[].pvp4número ou nuloO preço de venda do nível 4, sem imposto.
grupoVariacaoIdidentificador (UUID) ou nulo
grupoVariacaoNometexto ou nulo
variacaotexto ou nulo
paraVendaverdadeiro/falso
controlarLoteverdadeiro/falso
usaLoteverdadeiro/falso

Erros específicos

NAO_ENCONTRADO — além dos gerais.

Pedido

curl
curl 'https://<endereço-da-API>/api/produtos/<id>' \
  -H 'X-Api-Key: <a-sua-chave>'
GET/api/produtos/{id}/historico-custos#

O histórico do custo de um artigo: o custo unitário, desde quando vigora e de onde veio (compra ou actualização).

  • Permissão Produtos.Ler

Parâmetros

NomeOndeTipoObrigatório
idno caminhoidentificador (UUID)sim

Resposta (200 · JSON)

CampoTipoSignificado
[].ididentificador (UUID)Identificador único (UUID).
[].custoUnitarionúmero
[].vigenteDesdedata e hora (ISO 8601)
[].origemtexto

Pedido

curl
curl 'https://<endereço-da-API>/api/produtos/<id>/historico-custos' \
  -H 'X-Api-Key: <a-sua-chave>'
GET/api/produtos/pesquisa-venda#

A pesquisa de artigos para vender: preços de todos os níveis, imposto e o saldo de stock no armazém.

  • Permissão Documentos.Emitir

É o pedido a usar num ecrã de venda. Com armazemId, cada artigo traz o saldo nesse armazém.

produtoIds (repetido na pesquisa) devolve exactamente esses artigos, por exemplo para refrescar um carrinho.

Parâmetros

NomeOndeTipoObrigatório
filtrona pesquisatexto
armazemIdna pesquisaidentificador (UUID)
tamanhona pesquisanúmero inteiro
produtoIdsna pesquisalista de identificador (UUID)

Resposta (200 · JSON)

CampoTipoSignificado
[].ididentificador (UUID)Identificador único (UUID).
[].codigoInternotexto ou nuloO código interno do artigo.
[].codigoBarratexto ou nuloO código de barras.
[].nometextoO nome.
[].tipoProdutotextoProduto (com stock) ou Servico.
[].unidadeDescricaotexto ou nulo
[].pvp1númeroO preço de venda do nível 1, sem imposto.
[].pvp2númeroO preço de venda do nível 2, sem imposto.
[].pvp3númeroO preço de venda do nível 3, sem imposto.
[].pvp4númeroO preço de venda do nível 4, sem imposto.
[].impostoIdidentificador (UUID)
[].impostoPercentualnúmeroA taxa de IVA aplicada, em percentagem.
[].motivoIsencaoIvaIdidentificador (UUID) ou nulo
[].taxaRetencaoIdidentificador (UUID) ou nulo
[].estocavelverdadeiro/falso
[].compostoverdadeiro/falso
[].activoverdadeiro/falsoSe está activo.
[].saldoNoArmazemnúmero ou nulo
[].controlarValidadeverdadeiro/falso
[].categoriaIdidentificador (UUID) ou nulo
[].usaLoteverdadeiro/falso
[].unidadesVendalista de objectos
[].unidadesVenda[].ididentificador (UUID)Identificador único (UUID).
[].unidadesVenda[].nometextoO nome.
[].unidadesVenda[].factornúmero
[].unidadesVenda[].pvp1númeroO preço de venda do nível 1, sem imposto.
[].unidadesVenda[].pvp2númeroO preço de venda do nível 2, sem imposto.
[].unidadesVenda[].pvp3númeroO preço de venda do nível 3, sem imposto.
[].unidadesVenda[].pvp4númeroO preço de venda do nível 4, sem imposto.
[].grupoVariacaoIdidentificador (UUID) ou nulo
[].grupoVariacaoNometexto ou nulo
[].variacaotexto ou nulo

Exemplo

Pesquisa para venda: preços, imposto e saldo do armazém

Pedido
curl 'https://<endereço-da-API>/api/produtos/pesquisa-venda?filtro=arroz&armazemId=01a12201-f4d4-78a0-8dde-1efc41b94776&tamanho=1' \
  -H 'X-Api-Key: assw_v1_<chave>'
Pedido
const resposta = await fetch('https://<endereço-da-API>/api/produtos/pesquisa-venda?filtro=arroz&armazemId=01a12201-f4d4-78a0-8dde-1efc41b94776&tamanho=1', {
  method: 'GET',
  headers: {
    "X-Api-Key": "assw_v1_<chave>"
  },
})
const dados = await resposta.json()
Pedido
import requests

resposta = requests.get(
    'https://<endereço-da-API>/api/produtos/pesquisa-venda?filtro=arroz&armazemId=01a12201-f4d4-78a0-8dde-1efc41b94776&tamanho=1',
    headers={
        'X-Api-Key': 'assw_v1_<chave>'
    },
)
dados = resposta.json()
Pedido
using var cliente = new HttpClient { BaseAddress = new Uri("https://<endereço-da-API>") };
using var pedido = new HttpRequestMessage(HttpMethod.Get, "/api/produtos/pesquisa-venda?filtro=arroz&armazemId=01a12201-f4d4-78a0-8dde-1efc41b94776&tamanho=1");
pedido.Headers.Add("X-Api-Key", "assw_v1_<chave>");
using var resposta = await cliente.SendAsync(pedido);
var texto = await resposta.Content.ReadAsStringAsync();

200 OK Resposta

Resposta
content-type: application/json; charset=utf-8
x-mucanda-api-version: 1

[
  {
    "id": "01a12201-fa97-7f9b-8eec-2f731b91a53b",
    "codigoInterno": "MC0001",
    "codigoBarra": "560000100137",
    "nome": "Arroz agulha 5 kg",
    "tipoProduto": "Produto",
    "unidadeDescricao": "Unidade",
    "pvp1": 6500,
    "pvp2": 6250,
    "pvp3": 6000,
    "pvp4": 5750,
    "impostoId": "962b1189-25af-4864-bd7b-495a30abbc65",
    "impostoPercentual": 14,
    "motivoIsencaoIvaId": null,
    "taxaRetencaoId": null,
    "estocavel": true,
    "composto": false,
    "activo": true,
    "saldoNoArmazem": 536,
    "controlarValidade": false,
    "categoriaId": "01a12201-f8f9-7742-80ac-50e40368af4d",
    "unidadesVenda": [],
    "grupoVariacaoId": null,
    "grupoVariacaoNome": null,
    "variacao": null
  }
]
GET/api/produtos/mais-vendidos-pdv#

Os identificadores dos artigos que mais saem: o separador «Mais vendidos» do ponto de venda.

  • Permissão Documentos.Emitir

Devolve só os identificadores, do artigo que mais saiu para o que menos saiu (facturas e facturas/recibos, com as notas de crédito descontadas). Para os dados de cada artigo, use GET /api/produtos/pesquisa-venda com produtoIds.

lojaId limita a uma loja; dias é a janela de vendas (por omissão 30, no máximo 365) e quantos o número de artigos (por omissão 24, no máximo 100).

Pede a permissão de emitir documentos, não a dos relatórios.

Parâmetros

NomeOndeTipoObrigatório
lojaIdna pesquisaidentificador (UUID)
diasna pesquisanúmero inteiro
quantosna pesquisanúmero inteiro

Resposta (200 · JSON)

Pedido

curl
curl 'https://<endereço-da-API>/api/produtos/mais-vendidos-pdv' \
  -H 'X-Api-Key: <a-sua-chave>'
GET/api/produtos/grupos-variacao#

Os grupos de variação: artigos que são variações um do outro (tamanho, cor).

  • Permissão Produtos.Ler

Resposta (200 · JSON)

CampoTipoSignificado
[].ididentificador (UUID)Identificador único (UUID).
[].nometextoO nome.
[].variacoesnúmero inteiro

Pedido

curl
curl 'https://<endereço-da-API>/api/produtos/grupos-variacao' \
  -H 'X-Api-Key: <a-sua-chave>'
POST/api/produtos#

Cria um artigo.

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

Obrigatórios: nome, tipoProduto (Produto ou Servico) e impostoId. Os preços de venda (pvp1 a pvp4) são calculados a partir do custo e das margens.

Um artigo isento de imposto exige motivoIsencaoIvaId (de GET /api/catalogos).

O código de barras não pode repetir-se na empresa (erro DUPLICADO).

Criar o artigo não cria stock: dê entrada pela compra ou por um ajuste.

Corpo do pedido (JSON · CreateProdutoCommand)

CampoTipoObrigatórioSignificado
nometextosimO nome.
tipoProdutouma de: «Produto», «Servico»simProduto (com stock) ou Servico.
impostoIdidentificador (UUID)sim
motivoIsencaoIvaIdidentificador (UUID) ou nulo
informarPrecoNoPdvverdadeiro/falsosim
precoCustonúmero ou nuloO custo do artigo.
valorCIFnúmero ou nulo
despesasTransportenúmero ou nulo
despesasArmazenagemnúmero ou nulo
encargosAduaneirosnúmero ou nulo
despesasBancariasnúmero ou nulo
encargosGeraisnúmero ou nulo
margemPvp1númerosim
margemPvp2númerosim
margemPvp3númerosim
margemPvp4númerosim
codigoInternotexto ou nuloO código interno do artigo.
codigoBarratexto ou nuloO código de barras.
descricaotexto ou nuloA descrição.
categoriaIdidentificador (UUID) ou nulo
unidadeIdidentificador (UUID) ou nulo
marcaIdidentificador (UUID) ou nulo
modeloIdidentificador (UUID) ou nulo
fabricanteIdidentificador (UUID) ou nulo
tamanhoIdidentificador (UUID) ou nulo
fornecedorIdidentificador (UUID) ou nulo
taxaRetencaoIdidentificador (UUID) ou nulo
estocavelverdadeiro/falsosim
estoqueMinimonúmero ou nulo
controlarValidadeverdadeiro/falsosim
paisOrigemIdidentificador (UUID) ou nulo
origemtexto ou nulo
pesonúmero ou nulo
comprimentonúmero ou nulo
larguranúmero ou nulo
alturanúmero ou nulo
precificacaoAvancadaverdadeiro/falso
tipoInventarioFiscaluma de: «Mercadoria», «MateriaPrima», «ProdutoAcabado», «Subproduto», «TrabalhoEmCurso», «ActivoBiologico», «null» ou nulo
paraVendaverdadeiro/falso
controlarLoteverdadeiro/falso

Resposta

Devolve 201 com { "id": "…" }.

Erros específicos

DUPLICADO · ERRO_DE_VALIDACAO — além dos gerais.

Exemplo

Criar um artigo (preços calculados a partir do custo e das margens)

Pedido
curl -X POST 'https://<endereço-da-API>/api/produtos' \
  -H 'Idempotency-Key: 37cdd574-db7c-45bb-96f1-2a09e1cbc386' \
  -H 'X-Api-Key: assw_v1_<chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "Azeite virgem extra 750 ml",
  "tipoProduto": "Produto",
  "impostoId": "962b1189-25af-4864-bd7b-495a30abbc65",
  "motivoIsencaoIvaId": null,
  "informarPrecoNoPdv": false,
  "precoCusto": 4200,
  "margemPvp1": 40,
  "margemPvp2": 35,
  "margemPvp3": 30,
  "margemPvp4": 25,
  "codigoBarra": "614949903297",
  "estocavel": true,
  "controlarValidade": false
}'
Pedido
const resposta = await fetch('https://<endereço-da-API>/api/produtos', {
  method: 'POST',
  headers: {
    "Idempotency-Key": "37cdd574-db7c-45bb-96f1-2a09e1cbc386",
    "X-Api-Key": "assw_v1_<chave>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "nome": "Azeite virgem extra 750 ml",
    "tipoProduto": "Produto",
    "impostoId": "962b1189-25af-4864-bd7b-495a30abbc65",
    "motivoIsencaoIvaId": null,
    "informarPrecoNoPdv": false,
    "precoCusto": 4200,
    "margemPvp1": 40,
    "margemPvp2": 35,
    "margemPvp3": 30,
    "margemPvp4": 25,
    "codigoBarra": "614949903297",
    "estocavel": true,
    "controlarValidade": false
  }),
})
const dados = await resposta.json()
Pedido
import requests

resposta = requests.post(
    'https://<endereço-da-API>/api/produtos',
    headers={
        'Idempotency-Key': '37cdd574-db7c-45bb-96f1-2a09e1cbc386',
        'X-Api-Key': 'assw_v1_<chave>',
        'Content-Type': 'application/json'
    },
    json={
        'nome': 'Azeite virgem extra 750 ml',
        'tipoProduto': 'Produto',
        'impostoId': '962b1189-25af-4864-bd7b-495a30abbc65',
        'motivoIsencaoIvaId': None,
        'informarPrecoNoPdv': False,
        'precoCusto': 4200,
        'margemPvp1': 40,
        'margemPvp2': 35,
        'margemPvp3': 30,
        'margemPvp4': 25,
        'codigoBarra': '614949903297',
        'estocavel': True,
        'controlarValidade': False
    },
)
dados = resposta.json()
Pedido
using var cliente = new HttpClient { BaseAddress = new Uri("https://<endereço-da-API>") };
using var pedido = new HttpRequestMessage(HttpMethod.Post, "/api/produtos");
pedido.Headers.Add("Idempotency-Key", "37cdd574-db7c-45bb-96f1-2a09e1cbc386");
pedido.Headers.Add("X-Api-Key", "assw_v1_<chave>");
pedido.Content = new StringContent("""
{
  "nome": "Azeite virgem extra 750 ml",
  "tipoProduto": "Produto",
  "impostoId": "962b1189-25af-4864-bd7b-495a30abbc65",
  "motivoIsencaoIvaId": null,
  "informarPrecoNoPdv": false,
  "precoCusto": 4200,
  "margemPvp1": 40,
  "margemPvp2": 35,
  "margemPvp3": 30,
  "margemPvp4": 25,
  "codigoBarra": "614949903297",
  "estocavel": true,
  "controlarValidade": false
}
""", Encoding.UTF8, "application/json");
using var resposta = await cliente.SendAsync(pedido);
var texto = await resposta.Content.ReadAsStringAsync();

201 Created Resposta

Resposta
content-type: application/json; charset=utf-8
x-mucanda-api-version: 1
location: /api/produtos/01a12f69-9c27-7c48-9454-c67945355b50

{
  "id": "01a12f69-9c27-7c48-9454-c67945355b50"
}
PUT/api/produtos/{id}#

Actualiza o cadastro de um artigo.

  • Permissão Produtos.Editar

Substitui o cadastro inteiro: leia o artigo, altere o que precisa e envie todos os campos, incluindo as parcelas do custo, ou ficam sem valor.

O tipo (produto ou serviço) não se altera depois de criado.

Parâmetros

NomeOndeTipoObrigatório
idno caminhoidentificador (UUID)sim

Corpo do pedido (JSON · UpdateProdutoRequest)

CampoTipoObrigatórioSignificado
nometextosimO nome.
impostoIdidentificador (UUID)sim
motivoIsencaoIvaIdidentificador (UUID) ou nulo
informarPrecoNoPdvverdadeiro/falsosim
precoCustonúmero ou nuloO custo do artigo.
valorCIFnúmero ou nulo
despesasTransportenúmero ou nulo
despesasArmazenagemnúmero ou nulo
encargosAduaneirosnúmero ou nulo
despesasBancariasnúmero ou nulo
encargosGeraisnúmero ou nulo
margemPvp1númerosim
margemPvp2númerosim
margemPvp3númerosim
margemPvp4númerosim
codigoInternotexto ou nuloO código interno do artigo.
codigoBarratexto ou nuloO código de barras.
descricaotexto ou nuloA descrição.
categoriaIdidentificador (UUID) ou nulo
unidadeIdidentificador (UUID) ou nulo
marcaIdidentificador (UUID) ou nulo
modeloIdidentificador (UUID) ou nulo
fabricanteIdidentificador (UUID) ou nulo
tamanhoIdidentificador (UUID) ou nulo
fornecedorIdidentificador (UUID) ou nulo
taxaRetencaoIdidentificador (UUID) ou nulo
estocavelverdadeiro/falsosim
estoqueMinimonúmero ou nulo
controlarValidadeverdadeiro/falsosim
variadoverdadeiro/falsosim
itemCozinhaverdadeiro/falsosim
mostrarDescricaoNaFacturaverdadeiro/falsosim
paisOrigemIdidentificador (UUID) ou nulo
origemtexto ou nulo
pesonúmero ou nulo
comprimentonúmero ou nulo
larguranúmero ou nulo
alturanúmero ou nulo
precificacaoAvancadaverdadeiro/falso
tipoInventarioFiscaluma de: «Mercadoria», «MateriaPrima», «ProdutoAcabado», «Subproduto», «TrabalhoEmCurso», «ActivoBiologico», «null» ou nulo
paraVendaverdadeiro/falso ou nulo
controlarLoteverdadeiro/falso ou nulo

Resposta

Devolve 204 sem corpo.

Pedido

curl
curl -X PUT 'https://<endereço-da-API>/api/produtos/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "impostoId": "00000000-0000-0000-0000-000000000000",
  "informarPrecoNoPdv": false,
  "margemPvp1": 0,
  "margemPvp2": 0,
  "margemPvp3": 0,
  "margemPvp4": 0,
  "estocavel": false,
  "controlarValidade": false,
  "variado": false,
  "itemCozinha": false,
  "mostrarDescricaoNaFactura": false
}'
POST/api/produtos/{id}/activar#

Volta a activar um artigo desactivado.

  • Permissão Produtos.Editar

Parâmetros

NomeOndeTipoObrigatório
idno caminhoidentificador (UUID)sim

Resposta

Devolve 204 sem corpo.

Pedido

curl
curl -X POST 'https://<endereço-da-API>/api/produtos/<id>/activar' \
  -H 'X-Api-Key: <a-sua-chave>'
POST/api/produtos/{id}/desactivar#

Desactiva um artigo: deixa de poder ser vendido, mas o histórico fica.

  • Permissão Produtos.Editar

Parâmetros

NomeOndeTipoObrigatório
idno caminhoidentificador (UUID)sim

Resposta

Devolve 204 sem corpo.

Pedido

curl
curl -X POST 'https://<endereço-da-API>/api/produtos/<id>/desactivar' \
  -H 'X-Api-Key: <a-sua-chave>'
GET/api/produtos/sincronizacao-venda#

O catálogo completo de artigos para venda, para guardar numa cópia local (sincronização de um ponto de venda ou de uma loja online).

  • Permissão Documentos.Emitir

Paginado e sem filtro de texto: a pesquisa pontual é GET /api/produtos/pesquisa-venda. armazemId junta o saldo desse armazém.

A resposta é uma página: itens e proximoCursor. Ver Paginação.

Parâmetros

NomeOndeTipoObrigatório
armazemIdna pesquisaidentificador (UUID)
cursorna pesquisatexto
tamanhona pesquisanúmero inteiro

Resposta (200 · JSON)

CampoTipoSignificado
itenslista de objectosOs registos desta página.
itens[].ididentificador (UUID)Identificador único (UUID).
itens[].codigoInternotexto ou nuloO código interno do artigo.
itens[].codigoBarratexto ou nuloO código de barras.
itens[].nometextoO nome.
itens[].tipoProdutotextoProduto (com stock) ou Servico.
itens[].unidadeDescricaotexto ou nulo
itens[].pvp1númeroO preço de venda do nível 1, sem imposto.
itens[].pvp2númeroO preço de venda do nível 2, sem imposto.
itens[].pvp3númeroO preço de venda do nível 3, sem imposto.
itens[].pvp4númeroO preço de venda do nível 4, sem imposto.
itens[].impostoIdidentificador (UUID)
itens[].impostoPercentualnúmeroA taxa de IVA aplicada, em percentagem.
itens[].motivoIsencaoIvaIdidentificador (UUID) ou nulo
itens[].taxaRetencaoIdidentificador (UUID) ou nulo
itens[].estocavelverdadeiro/falso
itens[].compostoverdadeiro/falso
itens[].activoverdadeiro/falsoSe está activo.
itens[].saldoNoArmazemnúmero ou nulo
itens[].controlarValidadeverdadeiro/falso
itens[].categoriaIdidentificador (UUID) ou nulo
itens[].usaLoteverdadeiro/falso
itens[].unidadesVendalista de objectos
itens[].unidadesVenda[].ididentificador (UUID)Identificador único (UUID).
itens[].unidadesVenda[].nometextoO nome.
itens[].unidadesVenda[].factornúmero
itens[].unidadesVenda[].pvp1númeroO preço de venda do nível 1, sem imposto.
itens[].unidadesVenda[].pvp2númeroO preço de venda do nível 2, sem imposto.
itens[].unidadesVenda[].pvp3númeroO preço de venda do nível 3, sem imposto.
itens[].unidadesVenda[].pvp4númeroO preço de venda do nível 4, sem imposto.
itens[].grupoVariacaoIdidentificador (UUID) ou nulo
itens[].grupoVariacaoNometexto ou nulo
itens[].variacaotexto ou nulo
proximoCursortexto ou nuloO cursor da página seguinte; nulo quando não há mais. Ver Paginação.

Pedido

curl
curl 'https://<endereço-da-API>/api/produtos/sincronizacao-venda' \
  -H 'X-Api-Key: <a-sua-chave>'
PUT/api/produtos/{id}/composicao#

Define a composição de um conjunto (kit): os artigos e as quantidades que o formam.

  • Permissão Produtos.Editar

Substitui a composição inteira. O corpo é a lista de linhas.

Parâmetros

NomeOndeTipoObrigatório
idno caminhoidentificador (UUID)sim

Corpo do pedido (JSON)

CampoTipoObrigatórioSignificado
[].produtoAssociadoIdidentificador (UUID)sim
[].quantidadenúmerosimA quantidade.
[].precoUnitarionúmerosimO preço de uma unidade, sem imposto.

Pedido

curl
curl -X PUT 'https://<endereço-da-API>/api/produtos/<id>/composicao' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "produtoAssociadoId": "00000000-0000-0000-0000-000000000000",
    "quantidade": 0,
    "precoUnitario": 0
  }
]'
POST/api/produtos/grupos-variacao#

Cria um grupo de variações («Camisola Polo»).

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

Devolve o id.

Corpo do pedido (JSON · NomeDoGrupoRequest)

CampoTipoObrigatórioSignificado
nometextosimO nome.

Pedido

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

Renomeia um grupo de variações.

  • Permissão Produtos.Editar

Parâmetros

NomeOndeTipoObrigatório
idno caminhoidentificador (UUID)sim

Corpo do pedido (JSON · NomeDoGrupoRequest)

CampoTipoObrigatórioSignificado
nometextosimO nome.

Pedido

curl
curl -X PUT 'https://<endereço-da-API>/api/produtos/grupos-variacao/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto"
}'
DELETE/api/produtos/grupos-variacao/{id}#

Elimina um grupo de variações.

  • Permissão Produtos.Editar

Parâmetros

NomeOndeTipoObrigatório
idno caminhoidentificador (UUID)sim

Pedido

curl
curl -X DELETE 'https://<endereço-da-API>/api/produtos/grupos-variacao/<id>' \
  -H 'X-Api-Key: <a-sua-chave>'
PUT/api/produtos/{id}/variacao#

Define o grupo e a variação («M · Azul») de um artigo.

  • Permissão Produtos.Editar

Parâmetros

NomeOndeTipoObrigatório
idno caminhoidentificador (UUID)sim

Corpo do pedido (JSON · DefinirVariacaoRequest)

CampoTipoObrigatório
grupoVariacaoIdidentificador (UUID) ou nulo
variacaotexto ou nulo

Pedido

curl
curl -X PUT 'https://<endereço-da-API>/api/produtos/<id>/variacao' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{}'
POST/api/produtos/{id}/variacoes#

Cria uma variação de um artigo, por cópia.

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

Devolve o id da variação nova.

Parâmetros

NomeOndeTipoObrigatório
idno caminhoidentificador (UUID)sim

Corpo do pedido (JSON · CriarVariacaoRequest)

CampoTipoObrigatórioSignificado
variacaotextosim
nometexto ou nuloO nome.
codigoInternotexto ou nuloO código interno do artigo.
codigoBarratexto ou nuloO código de barras.

Pedido

curl
curl -X POST 'https://<endereço-da-API>/api/produtos/<id>/variacoes' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "variacao": "texto"
}'
POST/api/produtos/{id}/variacoes/em-serie#

Cria todas as variações de uma vez (tamanhos × cores).

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

O artigo pode ainda não estar num grupo.

Parâmetros

NomeOndeTipoObrigatório
idno caminhoidentificador (UUID)sim

Corpo do pedido (JSON · CriarVariacoesEmSerieRequest)

CampoTipoObrigatório
variacoeslista de textosim
grupoVariacaoIdidentificador (UUID) ou nulo
novoGrupotexto ou nulo
variacaoDaOrigemtexto ou nulo

Pedido

curl
curl -X POST 'https://<endereço-da-API>/api/produtos/<id>/variacoes/em-serie' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "variacoes": [
    "texto"
  ]
}'
PUT/api/produtos/{id}/unidades-venda#

Define as unidades de venda de um artigo (caixa, dúzia, unidade…).

  • Permissão Produtos.Editar

Substitui as unidades inteiras. O corpo é a lista de linhas.

Parâmetros

NomeOndeTipoObrigatório
idno caminhoidentificador (UUID)sim

Corpo do pedido (JSON)

CampoTipoObrigatórioSignificado
[].unidadeIdidentificador (UUID)sim
[].factornúmerosim
[].pvp1número ou nuloO preço de venda do nível 1, sem imposto.
[].pvp2número ou nuloO preço de venda do nível 2, sem imposto.
[].pvp3número ou nuloO preço de venda do nível 3, sem imposto.
[].pvp4número ou nuloO preço de venda do nível 4, sem imposto.

Pedido

curl
curl -X PUT 'https://<endereço-da-API>/api/produtos/<id>/unidades-venda' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "unidadeId": "00000000-0000-0000-0000-000000000000",
    "factor": 0
  }
]'
POST/api/produtos/catalogos/{tipo}#

Cria um item de um catálogo de apoio dos artigos.

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

tipo é um de: Categoria, Unidade, Marca, Modelo, Fabricante, Tamanho. Devolve o id.

Parâmetros

NomeOndeTipoObrigatório
tipono caminhouma de: «Categoria», «Unidade», «Marca», «Modelo», «Fabricante», «Tamanho»sim

Corpo do pedido (JSON · CriarCatalogoItemRequest)

CampoTipoObrigatórioSignificado
nometextosimO nome.

Pedido

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

Altera um item de um catálogo de apoio dos artigos.

  • Permissão Produtos.Editar

Parâmetros

NomeOndeTipoObrigatório
tipono caminhouma de: «Categoria», «Unidade», «Marca», «Modelo», «Fabricante», «Tamanho»sim
idno caminhoidentificador (UUID)sim

Corpo do pedido (JSON · CriarCatalogoItemRequest)

CampoTipoObrigatórioSignificado
nometextosimO nome.

Pedido

curl
curl -X PUT 'https://<endereço-da-API>/api/produtos/catalogos/<tipo>/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto"
}'
POST/api/produtos/catalogos/{tipo}/{id}/activar#

Activa um item de um catálogo de apoio.

  • Permissão Produtos.Editar

Parâmetros

NomeOndeTipoObrigatório
tipono caminhouma de: «Categoria», «Unidade», «Marca», «Modelo», «Fabricante», «Tamanho»sim
idno caminhoidentificador (UUID)sim

Pedido

curl
curl -X POST 'https://<endereço-da-API>/api/produtos/catalogos/<tipo>/<id>/activar' \
  -H 'X-Api-Key: <a-sua-chave>'
POST/api/produtos/catalogos/{tipo}/{id}/desactivar#

Desactiva um item de um catálogo de apoio.

  • Permissão Produtos.Editar

Parâmetros

NomeOndeTipoObrigatório
tipono caminhouma de: «Categoria», «Unidade», «Marca», «Modelo», «Fabricante», «Tamanho»sim
idno caminhoidentificador (UUID)sim

Pedido

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