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ção | O que faz |
|---|---|
GET /api/produtos | Lista 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-custos | O 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-venda | A 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-pdv | Os identificadores dos artigos que mais saem: o separador «Mais vendidos» do ponto de venda. |
GET /api/produtos/grupos-variacao | Os grupos de variação: artigos que são variações um do outro (tamanho, cor). |
POST /api/produtos | Cria um artigo. |
PUT /api/produtos/{id} | Actualiza o cadastro de um artigo. |
POST /api/produtos/{id}/activar | Volta a activar um artigo desactivado. |
POST /api/produtos/{id}/desactivar | Desactiva um artigo: deixa de poder ser vendido, mas o histórico fica. |
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). |
PUT /api/produtos/{id}/composicao | Define a composição de um conjunto (kit): os artigos e as quantidades que o formam. |
POST /api/produtos/grupos-variacao | Cria 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}/variacao | Define o grupo e a variação («M · Azul») de um artigo. |
POST /api/produtos/{id}/variacoes | Cria uma variação de um artigo, por cópia. |
POST /api/produtos/{id}/variacoes/em-serie | Cria todas as variações de uma vez (tamanhos × cores). |
PUT /api/produtos/{id}/unidades-venda | Define 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}/activar | Activa um item de um catálogo de apoio. |
POST /api/produtos/catalogos/{tipo}/{id}/desactivar | Desactiva um item de um catálogo de apoio. |
/api/produtos#Lista os artigos (produtos e serviços) com os preços e o custo.
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
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
filtro | na pesquisa | texto | |
apenasActivos | na pesquisa | verdadeiro/falso | |
cursor | na pesquisa | texto | |
tamanho | na pesquisa | número inteiro | |
paraVenda | na pesquisa | verdadeiro/falso | |
alteradoDesde | na pesquisa | data e hora (ISO 8601) | |
estocavel | na pesquisa | verdadeiro/falso | |
lojaId | na pesquisa | identificador (UUID) |
Resposta (200 · JSON)
| Campo | Tipo | Significado |
|---|---|---|
itens | lista de objectos | Os registos desta página. |
itens[].id | identificador (UUID) | Identificador único (UUID). |
itens[].codigoInterno | texto ou nulo | O código interno do artigo. |
itens[].codigoBarra | texto ou nulo | O código de barras. |
itens[].nome | texto | O nome. |
itens[].tipoProduto | texto | Produto (com stock) ou Servico. |
itens[].pvp1 | número | O preço de venda do nível 1, sem imposto. |
itens[].precoCusto | número ou nulo | O custo do artigo. |
itens[].activo | verdadeiro/falso | Se está activo. |
itens[].grupoVariacaoNome | texto ou nulo | |
itens[].variacao | texto ou nulo | |
itens[].paraVenda | verdadeiro/falso | |
itens[].alteradoEmUtc | data e hora (ISO 8601) | |
proximoCursor | texto ou nulo | O 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)
curl 'https://<endereço-da-API>/api/produtos?tamanho=1&filtro=arroz' \
-H 'X-Api-Key: assw_v1_<chave>'
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()
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()
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
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"
}
/api/produtos/{id}#O cadastro completo de um artigo.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
id | no caminho | identificador (UUID) | sim |
Resposta (200 · JSON)
| Campo | Tipo | Significado |
|---|---|---|
id | identificador (UUID) | Identificador único (UUID). |
codigoInterno | texto ou nulo | O código interno do artigo. |
codigoBarra | texto ou nulo | O código de barras. |
nome | texto | O nome. |
descricao | texto ou nulo | A descrição. |
tipoProduto | texto | Produto (com stock) ou Servico. |
impostoId | identificador (UUID) | |
motivoIsencaoIvaId | identificador (UUID) ou nulo | |
taxaRetencaoId | identificador (UUID) ou nulo | |
categoriaId | identificador (UUID) ou nulo | |
unidadeId | identificador (UUID) ou nulo | |
marcaId | identificador (UUID) ou nulo | |
modeloId | identificador (UUID) ou nulo | |
fabricanteId | identificador (UUID) ou nulo | |
tamanhoId | identificador (UUID) ou nulo | |
fornecedorId | identificador (UUID) ou nulo | |
estocavel | verdadeiro/falso | |
estoqueMinimo | número ou nulo | |
controlarValidade | verdadeiro/falso | |
composto | verdadeiro/falso | |
informarPrecoNoPdv | verdadeiro/falso | |
precificacaoAvancada | verdadeiro/falso | |
variado | verdadeiro/falso | |
itemCozinha | verdadeiro/falso | |
mostrarDescricaoNaFactura | verdadeiro/falso | |
activo | verdadeiro/falso | Se está activo. |
precoCusto | número ou nulo | O custo do artigo. |
lucroPvp1 | número | |
pvp1 | número | O preço de venda do nível 1, sem imposto. |
lucroPvp2 | número | |
pvp2 | número | O preço de venda do nível 2, sem imposto. |
lucroPvp3 | número | |
pvp3 | número | O preço de venda do nível 3, sem imposto. |
lucroPvp4 | número | |
pvp4 | número | O preço de venda do nível 4, sem imposto. |
paisOrigemId | identificador (UUID) ou nulo | |
origem | texto ou nulo | |
peso | número ou nulo | |
comprimento | número ou nulo | |
largura | número ou nulo | |
altura | número ou nulo | |
tipoInventarioFiscal | texto ou nulo | |
valorCif | número ou nulo | |
despesasTransporte | número ou nulo | |
despesasArmazenagem | número ou nulo | |
encargosAduaneiros | número ou nulo | |
despesasBancarias | número ou nulo | |
encargosGerais | número ou nulo | |
composicao | lista de objectos | |
composicao[].id | identificador (UUID) | Identificador único (UUID). |
composicao[].produtoAssociadoId | identificador (UUID) | |
composicao[].quantidade | número | A quantidade. |
composicao[].precoUnitario | número | O preço de uma unidade, sem imposto. |
composicao[].produtoAssociadoNome | texto ou nulo | |
unidadesVenda | lista de objectos | |
unidadesVenda[].id | identificador (UUID) | Identificador único (UUID). |
unidadesVenda[].unidadeId | identificador (UUID) | |
unidadesVenda[].nome | texto | O nome. |
unidadesVenda[].factor | número | |
unidadesVenda[].pvp1 | número ou nulo | O preço de venda do nível 1, sem imposto. |
unidadesVenda[].pvp2 | número ou nulo | O preço de venda do nível 2, sem imposto. |
unidadesVenda[].pvp3 | número ou nulo | O preço de venda do nível 3, sem imposto. |
unidadesVenda[].pvp4 | número ou nulo | O preço de venda do nível 4, sem imposto. |
grupoVariacaoId | identificador (UUID) ou nulo | |
grupoVariacaoNome | texto ou nulo | |
variacao | texto ou nulo | |
paraVenda | verdadeiro/falso | |
controlarLote | verdadeiro/falso | |
usaLote | verdadeiro/falso |
Erros específicos
NAO_ENCONTRADO — além dos gerais.
Pedido
curl 'https://<endereço-da-API>/api/produtos/<id>' \
-H 'X-Api-Key: <a-sua-chave>'
/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).
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
id | no caminho | identificador (UUID) | sim |
Resposta (200 · JSON)
| Campo | Tipo | Significado |
|---|---|---|
[].id | identificador (UUID) | Identificador único (UUID). |
[].custoUnitario | número | |
[].vigenteDesde | data e hora (ISO 8601) | |
[].origem | texto |
Pedido
curl 'https://<endereço-da-API>/api/produtos/<id>/historico-custos' \
-H 'X-Api-Key: <a-sua-chave>'
/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.
É 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
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
filtro | na pesquisa | texto | |
armazemId | na pesquisa | identificador (UUID) | |
tamanho | na pesquisa | número inteiro | |
produtoIds | na pesquisa | lista de identificador (UUID) |
Resposta (200 · JSON)
| Campo | Tipo | Significado |
|---|---|---|
[].id | identificador (UUID) | Identificador único (UUID). |
[].codigoInterno | texto ou nulo | O código interno do artigo. |
[].codigoBarra | texto ou nulo | O código de barras. |
[].nome | texto | O nome. |
[].tipoProduto | texto | Produto (com stock) ou Servico. |
[].unidadeDescricao | texto ou nulo | |
[].pvp1 | número | O preço de venda do nível 1, sem imposto. |
[].pvp2 | número | O preço de venda do nível 2, sem imposto. |
[].pvp3 | número | O preço de venda do nível 3, sem imposto. |
[].pvp4 | número | O preço de venda do nível 4, sem imposto. |
[].impostoId | identificador (UUID) | |
[].impostoPercentual | número | A taxa de IVA aplicada, em percentagem. |
[].motivoIsencaoIvaId | identificador (UUID) ou nulo | |
[].taxaRetencaoId | identificador (UUID) ou nulo | |
[].estocavel | verdadeiro/falso | |
[].composto | verdadeiro/falso | |
[].activo | verdadeiro/falso | Se está activo. |
[].saldoNoArmazem | número ou nulo | |
[].controlarValidade | verdadeiro/falso | |
[].categoriaId | identificador (UUID) ou nulo | |
[].usaLote | verdadeiro/falso | |
[].unidadesVenda | lista de objectos | |
[].unidadesVenda[].id | identificador (UUID) | Identificador único (UUID). |
[].unidadesVenda[].nome | texto | O nome. |
[].unidadesVenda[].factor | número | |
[].unidadesVenda[].pvp1 | número | O preço de venda do nível 1, sem imposto. |
[].unidadesVenda[].pvp2 | número | O preço de venda do nível 2, sem imposto. |
[].unidadesVenda[].pvp3 | número | O preço de venda do nível 3, sem imposto. |
[].unidadesVenda[].pvp4 | número | O preço de venda do nível 4, sem imposto. |
[].grupoVariacaoId | identificador (UUID) ou nulo | |
[].grupoVariacaoNome | texto ou nulo | |
[].variacao | texto ou nulo |
Exemplo
Pesquisa para venda: preços, imposto e saldo do armazém
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>'
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()
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()
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
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
}
]
/api/produtos/mais-vendidos-pdv#Os identificadores dos artigos que mais saem: o separador «Mais vendidos» do ponto de venda.
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
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
lojaId | na pesquisa | identificador (UUID) | |
dias | na pesquisa | número inteiro | |
quantos | na pesquisa | número inteiro |
Resposta (200 · JSON)
Pedido
curl 'https://<endereço-da-API>/api/produtos/mais-vendidos-pdv' \
-H 'X-Api-Key: <a-sua-chave>'
/api/produtos/grupos-variacao#Os grupos de variação: artigos que são variações um do outro (tamanho, cor).
Resposta (200 · JSON)
| Campo | Tipo | Significado |
|---|---|---|
[].id | identificador (UUID) | Identificador único (UUID). |
[].nome | texto | O nome. |
[].variacoes | número inteiro |
Pedido
curl 'https://<endereço-da-API>/api/produtos/grupos-variacao' \
-H 'X-Api-Key: <a-sua-chave>'
/api/produtos#Cria um artigo.
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)
| Campo | Tipo | Obrigatório | Significado |
|---|---|---|---|
nome | texto | sim | O nome. |
tipoProduto | uma de: «Produto», «Servico» | sim | Produto (com stock) ou Servico. |
impostoId | identificador (UUID) | sim | |
motivoIsencaoIvaId | identificador (UUID) ou nulo | ||
informarPrecoNoPdv | verdadeiro/falso | sim | |
precoCusto | número ou nulo | O custo do artigo. | |
valorCIF | número ou nulo | ||
despesasTransporte | número ou nulo | ||
despesasArmazenagem | número ou nulo | ||
encargosAduaneiros | número ou nulo | ||
despesasBancarias | número ou nulo | ||
encargosGerais | número ou nulo | ||
margemPvp1 | número | sim | |
margemPvp2 | número | sim | |
margemPvp3 | número | sim | |
margemPvp4 | número | sim | |
codigoInterno | texto ou nulo | O código interno do artigo. | |
codigoBarra | texto ou nulo | O código de barras. | |
descricao | texto ou nulo | A descrição. | |
categoriaId | identificador (UUID) ou nulo | ||
unidadeId | identificador (UUID) ou nulo | ||
marcaId | identificador (UUID) ou nulo | ||
modeloId | identificador (UUID) ou nulo | ||
fabricanteId | identificador (UUID) ou nulo | ||
tamanhoId | identificador (UUID) ou nulo | ||
fornecedorId | identificador (UUID) ou nulo | ||
taxaRetencaoId | identificador (UUID) ou nulo | ||
estocavel | verdadeiro/falso | sim | |
estoqueMinimo | número ou nulo | ||
controlarValidade | verdadeiro/falso | sim | |
paisOrigemId | identificador (UUID) ou nulo | ||
origem | texto ou nulo | ||
peso | número ou nulo | ||
comprimento | número ou nulo | ||
largura | número ou nulo | ||
altura | número ou nulo | ||
precificacaoAvancada | verdadeiro/falso | ||
tipoInventarioFiscal | uma de: «Mercadoria», «MateriaPrima», «ProdutoAcabado», «Subproduto», «TrabalhoEmCurso», «ActivoBiologico», «null» ou nulo | ||
paraVenda | verdadeiro/falso | ||
controlarLote | verdadeiro/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)
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
}'
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()
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()
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
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"
}
/api/produtos/{id}#Actualiza o cadastro de um artigo.
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
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
id | no caminho | identificador (UUID) | sim |
Corpo do pedido (JSON · UpdateProdutoRequest)
| Campo | Tipo | Obrigatório | Significado |
|---|---|---|---|
nome | texto | sim | O nome. |
impostoId | identificador (UUID) | sim | |
motivoIsencaoIvaId | identificador (UUID) ou nulo | ||
informarPrecoNoPdv | verdadeiro/falso | sim | |
precoCusto | número ou nulo | O custo do artigo. | |
valorCIF | número ou nulo | ||
despesasTransporte | número ou nulo | ||
despesasArmazenagem | número ou nulo | ||
encargosAduaneiros | número ou nulo | ||
despesasBancarias | número ou nulo | ||
encargosGerais | número ou nulo | ||
margemPvp1 | número | sim | |
margemPvp2 | número | sim | |
margemPvp3 | número | sim | |
margemPvp4 | número | sim | |
codigoInterno | texto ou nulo | O código interno do artigo. | |
codigoBarra | texto ou nulo | O código de barras. | |
descricao | texto ou nulo | A descrição. | |
categoriaId | identificador (UUID) ou nulo | ||
unidadeId | identificador (UUID) ou nulo | ||
marcaId | identificador (UUID) ou nulo | ||
modeloId | identificador (UUID) ou nulo | ||
fabricanteId | identificador (UUID) ou nulo | ||
tamanhoId | identificador (UUID) ou nulo | ||
fornecedorId | identificador (UUID) ou nulo | ||
taxaRetencaoId | identificador (UUID) ou nulo | ||
estocavel | verdadeiro/falso | sim | |
estoqueMinimo | número ou nulo | ||
controlarValidade | verdadeiro/falso | sim | |
variado | verdadeiro/falso | sim | |
itemCozinha | verdadeiro/falso | sim | |
mostrarDescricaoNaFactura | verdadeiro/falso | sim | |
paisOrigemId | identificador (UUID) ou nulo | ||
origem | texto ou nulo | ||
peso | número ou nulo | ||
comprimento | número ou nulo | ||
largura | número ou nulo | ||
altura | número ou nulo | ||
precificacaoAvancada | verdadeiro/falso | ||
tipoInventarioFiscal | uma de: «Mercadoria», «MateriaPrima», «ProdutoAcabado», «Subproduto», «TrabalhoEmCurso», «ActivoBiologico», «null» ou nulo | ||
paraVenda | verdadeiro/falso ou nulo | ||
controlarLote | verdadeiro/falso ou nulo |
Resposta
Devolve 204 sem corpo.
Pedido
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
}'
/api/produtos/{id}/activar#Volta a activar um artigo desactivado.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
id | no caminho | identificador (UUID) | sim |
Resposta
Devolve 204 sem corpo.
Pedido
curl -X POST 'https://<endereço-da-API>/api/produtos/<id>/activar' \
-H 'X-Api-Key: <a-sua-chave>'
/api/produtos/{id}/desactivar#Desactiva um artigo: deixa de poder ser vendido, mas o histórico fica.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
id | no caminho | identificador (UUID) | sim |
Resposta
Devolve 204 sem corpo.
Pedido
curl -X POST 'https://<endereço-da-API>/api/produtos/<id>/desactivar' \
-H 'X-Api-Key: <a-sua-chave>'
/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).
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
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
armazemId | na pesquisa | identificador (UUID) | |
cursor | na pesquisa | texto | |
tamanho | na pesquisa | número inteiro |
Resposta (200 · JSON)
| Campo | Tipo | Significado |
|---|---|---|
itens | lista de objectos | Os registos desta página. |
itens[].id | identificador (UUID) | Identificador único (UUID). |
itens[].codigoInterno | texto ou nulo | O código interno do artigo. |
itens[].codigoBarra | texto ou nulo | O código de barras. |
itens[].nome | texto | O nome. |
itens[].tipoProduto | texto | Produto (com stock) ou Servico. |
itens[].unidadeDescricao | texto ou nulo | |
itens[].pvp1 | número | O preço de venda do nível 1, sem imposto. |
itens[].pvp2 | número | O preço de venda do nível 2, sem imposto. |
itens[].pvp3 | número | O preço de venda do nível 3, sem imposto. |
itens[].pvp4 | número | O preço de venda do nível 4, sem imposto. |
itens[].impostoId | identificador (UUID) | |
itens[].impostoPercentual | número | A taxa de IVA aplicada, em percentagem. |
itens[].motivoIsencaoIvaId | identificador (UUID) ou nulo | |
itens[].taxaRetencaoId | identificador (UUID) ou nulo | |
itens[].estocavel | verdadeiro/falso | |
itens[].composto | verdadeiro/falso | |
itens[].activo | verdadeiro/falso | Se está activo. |
itens[].saldoNoArmazem | número ou nulo | |
itens[].controlarValidade | verdadeiro/falso | |
itens[].categoriaId | identificador (UUID) ou nulo | |
itens[].usaLote | verdadeiro/falso | |
itens[].unidadesVenda | lista de objectos | |
itens[].unidadesVenda[].id | identificador (UUID) | Identificador único (UUID). |
itens[].unidadesVenda[].nome | texto | O nome. |
itens[].unidadesVenda[].factor | número | |
itens[].unidadesVenda[].pvp1 | número | O preço de venda do nível 1, sem imposto. |
itens[].unidadesVenda[].pvp2 | número | O preço de venda do nível 2, sem imposto. |
itens[].unidadesVenda[].pvp3 | número | O preço de venda do nível 3, sem imposto. |
itens[].unidadesVenda[].pvp4 | número | O preço de venda do nível 4, sem imposto. |
itens[].grupoVariacaoId | identificador (UUID) ou nulo | |
itens[].grupoVariacaoNome | texto ou nulo | |
itens[].variacao | texto ou nulo | |
proximoCursor | texto ou nulo | O cursor da página seguinte; nulo quando não há mais. Ver Paginação. |
Pedido
curl 'https://<endereço-da-API>/api/produtos/sincronizacao-venda' \
-H 'X-Api-Key: <a-sua-chave>'
/api/produtos/{id}/composicao#Define a composição de um conjunto (kit): os artigos e as quantidades que o formam.
Substitui a composição inteira. O corpo é a lista de linhas.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
id | no caminho | identificador (UUID) | sim |
Corpo do pedido (JSON)
| Campo | Tipo | Obrigatório | Significado |
|---|---|---|---|
[].produtoAssociadoId | identificador (UUID) | sim | |
[].quantidade | número | sim | A quantidade. |
[].precoUnitario | número | sim | O preço de uma unidade, sem imposto. |
Pedido
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
}
]'
/api/produtos/grupos-variacao#Cria um grupo de variações («Camisola Polo»).
Devolve o id.
Corpo do pedido (JSON · NomeDoGrupoRequest)
| Campo | Tipo | Obrigatório | Significado |
|---|---|---|---|
nome | texto | sim | O nome. |
Pedido
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"
}'
/api/produtos/grupos-variacao/{id}#Renomeia um grupo de variações.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
id | no caminho | identificador (UUID) | sim |
Corpo do pedido (JSON · NomeDoGrupoRequest)
| Campo | Tipo | Obrigatório | Significado |
|---|---|---|---|
nome | texto | sim | O nome. |
Pedido
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"
}'
/api/produtos/grupos-variacao/{id}#Elimina um grupo de variações.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
id | no caminho | identificador (UUID) | sim |
Pedido
curl -X DELETE 'https://<endereço-da-API>/api/produtos/grupos-variacao/<id>' \
-H 'X-Api-Key: <a-sua-chave>'
/api/produtos/{id}/variacao#Define o grupo e a variação («M · Azul») de um artigo.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
id | no caminho | identificador (UUID) | sim |
Corpo do pedido (JSON · DefinirVariacaoRequest)
| Campo | Tipo | Obrigatório |
|---|---|---|
grupoVariacaoId | identificador (UUID) ou nulo | |
variacao | texto ou nulo |
Pedido
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 '{}'
/api/produtos/{id}/variacoes#Cria uma variação de um artigo, por cópia.
Devolve o id da variação nova.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
id | no caminho | identificador (UUID) | sim |
Corpo do pedido (JSON · CriarVariacaoRequest)
| Campo | Tipo | Obrigatório | Significado |
|---|---|---|---|
variacao | texto | sim | |
nome | texto ou nulo | O nome. | |
codigoInterno | texto ou nulo | O código interno do artigo. | |
codigoBarra | texto ou nulo | O código de barras. |
Pedido
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"
}'
/api/produtos/{id}/variacoes/em-serie#Cria todas as variações de uma vez (tamanhos × cores).
O artigo pode ainda não estar num grupo.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
id | no caminho | identificador (UUID) | sim |
Corpo do pedido (JSON · CriarVariacoesEmSerieRequest)
| Campo | Tipo | Obrigatório |
|---|---|---|
variacoes | lista de texto | sim |
grupoVariacaoId | identificador (UUID) ou nulo | |
novoGrupo | texto ou nulo | |
variacaoDaOrigem | texto ou nulo |
Pedido
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"
]
}'
/api/produtos/{id}/unidades-venda#Define as unidades de venda de um artigo (caixa, dúzia, unidade…).
Substitui as unidades inteiras. O corpo é a lista de linhas.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
id | no caminho | identificador (UUID) | sim |
Corpo do pedido (JSON)
| Campo | Tipo | Obrigatório | Significado |
|---|---|---|---|
[].unidadeId | identificador (UUID) | sim | |
[].factor | número | sim | |
[].pvp1 | número ou nulo | O preço de venda do nível 1, sem imposto. | |
[].pvp2 | número ou nulo | O preço de venda do nível 2, sem imposto. | |
[].pvp3 | número ou nulo | O preço de venda do nível 3, sem imposto. | |
[].pvp4 | número ou nulo | O preço de venda do nível 4, sem imposto. |
Pedido
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
}
]'
/api/produtos/catalogos/{tipo}#Cria um item de um catálogo de apoio dos artigos.
tipo é um de: Categoria, Unidade, Marca, Modelo, Fabricante, Tamanho. Devolve o id.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
tipo | no caminho | uma de: «Categoria», «Unidade», «Marca», «Modelo», «Fabricante», «Tamanho» | sim |
Corpo do pedido (JSON · CriarCatalogoItemRequest)
| Campo | Tipo | Obrigatório | Significado |
|---|---|---|---|
nome | texto | sim | O nome. |
Pedido
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"
}'
/api/produtos/catalogos/{tipo}/{id}#Altera um item de um catálogo de apoio dos artigos.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
tipo | no caminho | uma de: «Categoria», «Unidade», «Marca», «Modelo», «Fabricante», «Tamanho» | sim |
id | no caminho | identificador (UUID) | sim |
Corpo do pedido (JSON · CriarCatalogoItemRequest)
| Campo | Tipo | Obrigatório | Significado |
|---|---|---|---|
nome | texto | sim | O nome. |
Pedido
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"
}'
/api/produtos/catalogos/{tipo}/{id}/activar#Activa um item de um catálogo de apoio.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
tipo | no caminho | uma de: «Categoria», «Unidade», «Marca», «Modelo», «Fabricante», «Tamanho» | sim |
id | no caminho | identificador (UUID) | sim |
Pedido
curl -X POST 'https://<endereço-da-API>/api/produtos/catalogos/<tipo>/<id>/activar' \
-H 'X-Api-Key: <a-sua-chave>'
/api/produtos/catalogos/{tipo}/{id}/desactivar#Desactiva um item de um catálogo de apoio.
Parâmetros
| Nome | Onde | Tipo | Obrigatório |
|---|---|---|---|
tipo | no caminho | uma de: «Categoria», «Unidade», «Marca», «Modelo», «Fabricante», «Tamanho» | sim |
id | no caminho | identificador (UUID) | sim |
Pedido
curl -X POST 'https://<endereço-da-API>/api/produtos/catalogos/<tipo>/<id>/desactivar' \
-H 'X-Api-Key: <a-sua-chave>'