Referência

Relatórios

Os números do negócio por período. Os relatórios são pesados: a empresa só pode ter dois a correr ao mesmo tempo (ver Limites).

Operação	O que faz
GET `/api/relatorios/mapas/{codigo}`	Um mapa de gestão (o código diz qual) de um período.
GET `/api/relatorios/caixas/{id}/resumo`	O resumo de uma sessão de caixa.
GET `/api/visao-360`	A Visão 360° do negócio: vendas, dinheiro, dívidas, stock e impostos num só pedido.
GET `/api/relatorios/clientes/ranking`	Os melhores clientes do período, por valor vendido.
GET `/api/relatorios/documentos`	Os documentos emitidos num período, com totais, por tipo, cliente, utilizador, estabelecimento e estado.
GET `/api/relatorios/iva`	O resumo do IVA do período: base e imposto por taxa.
GET `/api/relatorios/pagamentos`	Os pagamentos recebidos no período, por método.
GET `/api/relatorios/pendentes`	As facturas pendentes de pagamento, com o escalão de atraso.
GET `/api/relatorios/produtos-vendidos`	Os artigos vendidos no período, com quantidade, valor, custo e lucro.
GET `/api/relatorios/produtos/classificacao-abc`	A classificação ABC dos artigos pelo valor vendido.
GET `/api/relatorios/produtos/ranking`	Os artigos mais (ou menos) vendidos do período.
GET `/api/relatorios/produtos/{produtoId}/ultimas-vendas`	As últimas vendas de um artigo.
GET `/api/relatorios/resumo-facturacao`	A facturação de hoje, da semana, do mês e do ano (descontadas as notas de crédito).
GET `/api/relatorios/vendas-mensais`	As vendas de cada mês de um ano, por artigo.

GET/api/relatorios/mapas/{codigo}#

Um mapa de gestão (o código diz qual) de um período.

Permissão RelatoriosDetalhados.Ler

inicio, fim e lojaId filtram. O mapa de custos com pessoal só se vê com acesso a dados sensíveis (ver Dados sensíveis).

Parâmetros

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

Resposta (200 · JSON)

Campo	Tipo	Significado
`codigo`	texto	O código curto.
`titulo`	texto
`nota`	texto ou nulo
`inicio`	data (AAAA-MM-DD)
`fim`	data (AAAA-MM-DD)
`colunas`	lista de objectos
`colunas[].chave`	texto
`colunas[].rotulo`	texto
`colunas[].tipo`	texto
`linhas`	lista de objectos
`totais`	lista de objectos
`totais[].rotulo`	texto
`totais[].valor`	número	O valor.
`totais[].tipo`	texto
`truncado`	verdadeiro/falso

Pedido

curl

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

GET/api/relatorios/caixas/{id}/resumo#

O resumo de uma sessão de caixa.

Permissão Caixa.HistoricoLer

Parâmetros

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

Pedido

curl

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

GET/api/visao-360#

A Visão 360° do negócio: vendas, dinheiro, dívidas, stock e impostos num só pedido.

Permissão Visao360.Ler

A parte da equipa (recursos humanos) só vem com uma chave de acesso a dados sensíveis; sem ela, o campo equipa vai vazio.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`periodo`	na pesquisa	texto
`estabelecimentoId`	na pesquisa	identificador (UUID)

Pedido

curl

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

GET/api/relatorios/clientes/ranking#

Os melhores clientes do período, por valor vendido.

Permissão RelatoriosDetalhados.Ler

top limita a lista (por omissão 50).

Parâmetros

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

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].posicao`	número inteiro
`[].clienteId`	identificador (UUID)	O cliente do documento.
`[].cliente`	texto
`[].totalVendas`	número

Pedido

curl

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

GET/api/relatorios/documentos#

Os documentos emitidos num período, com totais, por tipo, cliente, utilizador, estabelecimento e estado.

Permissão DocumentosEmitidos.Ler

dataInicio e dataFim são obrigatórias (AAAA-MM-DD, inclusivas, hora de Angola).

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

Parâmetros

Nome	Onde	Tipo	Obrigatório
`dataInicio`	na pesquisa	data (AAAA-MM-DD)	sim
`dataFim`	na pesquisa	data (AAAA-MM-DD)	sim
`tipoDocumentoId`	na pesquisa	identificador (UUID)
`clienteId`	na pesquisa	identificador (UUID)
`usuarioId`	na pesquisa	identificador (UUID)
`lojaId`	na pesquisa	identificador (UUID)
`estado`	na pesquisa	texto
`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[].siglaDocumento`	texto	A sigla do tipo («FT», «FR», «NC»…).
`itens[].tipoDescricao`	texto
`itens[].numero`	texto	O número legível, atribuído pelo servidor («FR LC2026/25»).
`itens[].data`	data e hora (ISO 8601)	A data e hora (UTC).
`itens[].clienteId`	identificador (UUID)	O cliente do documento.
`itens[].clienteNome`	texto	O nome do cliente tal como estava na emissão.
`itens[].usuarioId`	identificador (UUID) ou nulo
`itens[].estado`	texto	O estado actual.
`itens[].motivoAnulacao`	texto ou nulo	O motivo, quando o documento foi anulado.
`itens[].referencia`	texto ou nulo
`itens[].subtotal`	número	A soma das linhas, já com desconto e sem imposto.
`itens[].imposto`	número
`itens[].desconto`	número	O desconto habitual do cliente, em percentagem.
`itens[].retencao`	número
`itens[].totalGeral`	número	O total do documento: subtotal + imposto − retenção + outros encargos.
`itens[].pago`	número
`itens[].porPagar`	número
`proximoCursor`	texto ou nulo	O cursor da página seguinte; nulo quando não há mais. Ver Paginação.

Pedido

curl

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

GET/api/relatorios/iva#

O resumo do IVA do período: base e imposto por taxa.

Permissão RelatoriosDetalhados.Ler

Parâmetros

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

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].taxa`	número	A taxa, em percentagem.
`[].motivoIsencao`	texto ou nulo
`[].incidencia`	número
`[].imposto`	número

Pedido

curl

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

GET/api/relatorios/pagamentos#

Os pagamentos recebidos no período, por método.

Permissão RelatoriosDetalhados.Ler

Parâmetros

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

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].data`	data e hora (ISO 8601)	A data e hora (UTC).
`[].documento`	texto
`[].tipoDocumento`	texto
`[].metodo`	texto
`[].valor`	número	O valor.
`[].sentido`	texto
`[].usuarioId`	identificador (UUID) ou nulo

Pedido

curl

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

GET/api/relatorios/pendentes#

As facturas pendentes de pagamento, com o escalão de atraso.

Permissão DocumentosEmitidos.Ler

Parâmetros

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

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].id`	identificador (UUID)	Identificador único (UUID).
`[].numero`	texto	O número legível, atribuído pelo servidor («FR LC2026/25»).
`[].data`	data e hora (ISO 8601)	A data e hora (UTC).
`[].clienteId`	identificador (UUID)	O cliente do documento.
`[].clienteNome`	texto	O nome do cliente tal como estava na emissão.
`[].numeroContribuinte`	texto ou nulo	O número de contribuinte (NIF).
`[].totalGeral`	número	O total do documento: subtotal + imposto − retenção + outros encargos.
`[].pago`	número
`[].porPagar`	número
`[].diasEmAberto`	número inteiro
`[].escalao`	texto	O escalão de atraso: «A vencer», «0-30», «31-60» ou «61+».

Pedido

curl

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

GET/api/relatorios/produtos-vendidos#

Os artigos vendidos no período, com quantidade, valor, custo e lucro.

Permissão RelatoriosDetalhados.Ler

Parâmetros

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

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].produtoId`	identificador (UUID)	O artigo.
`[].produto`	texto
`[].quantidade`	número	A quantidade.
`[].totalVendas`	número
`[].totalImposto`	número
`[].totalRetencao`	número
`[].totalCusto`	número
`[].lucro`	número

Pedido

curl

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

GET/api/relatorios/produtos/classificacao-abc#

A classificação ABC dos artigos pelo valor vendido.

Permissão RelatoriosDetalhados.Ler

limiteA e limiteB são as fracções acumuladas (por omissão 0,8 e 0,9).

Parâmetros

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

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].produtoId`	identificador (UUID)	O artigo.
`[].produto`	texto
`[].quantidade`	número	A quantidade.
`[].vendas`	número
`[].percentagemIndividual`	número
`[].percentagemAcumulada`	número
`[].classe`	texto

Pedido

curl

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

GET/api/relatorios/produtos/ranking#

Os artigos mais (ou menos) vendidos do período.

Permissão RelatoriosDetalhados.Ler

ordem é mais (por omissão) ou menos; incluirSemVendas=true inclui os que não venderam nada.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`dataInicio`	na pesquisa	data (AAAA-MM-DD)	sim
`dataFim`	na pesquisa	data (AAAA-MM-DD)	sim
`ordem`	na pesquisa	texto
`top`	na pesquisa	número inteiro
`incluirSemVendas`	na pesquisa	verdadeiro/falso
`lojaId`	na pesquisa	identificador (UUID)

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].posicao`	número inteiro
`[].produtoId`	identificador (UUID)	O artigo.
`[].produto`	texto
`[].quantidade`	número	A quantidade.
`[].totalVendas`	número

Pedido

curl

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

GET/api/relatorios/produtos/{produtoId}/ultimas-vendas#

As últimas vendas de um artigo.

Permissão RelatoriosDetalhados.Ler

Parâmetros

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

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].documentoId`	identificador (UUID)
`[].data`	data e hora (ISO 8601)	A data e hora (UTC).
`[].siglaDocumento`	texto	A sigla do tipo («FT», «FR», «NC»…).
`[].numero`	texto	O número legível, atribuído pelo servidor («FR LC2026/25»).
`[].clienteNome`	texto ou nulo	O nome do cliente tal como estava na emissão.
`[].quantidade`	número	A quantidade.
`[].precoUnitario`	número	O preço de uma unidade, sem imposto.
`[].total`	número	O total.

Pedido

curl

curl 'https://<endereço-da-API>/api/relatorios/produtos/<produtoId>/ultimas-vendas' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/relatorios/resumo-facturacao#

A facturação de hoje, da semana, do mês e do ano (descontadas as notas de crédito).

Permissão RelatoriosDetalhados.Ler

Com lojaId limita a um estabelecimento. É a consulta mais leve da área: boa para um painel.

Parâmetros

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

Resposta (200 · JSON)

Campo	Tipo	Significado
`hoje`	número	A facturação de hoje.
`estaSemana`	número	A facturação da semana.
`esteMes`	número	A facturação do mês.
`esteAno`	número	A facturação do ano.

Exemplo

Facturação de hoje, da semana, do mês e do ano

Pedido

curl 'https://<endereço-da-API>/api/relatorios/resumo-facturacao?lojaId=01a12201-f4d4-7c07-86b7-e5b24035993e' \
  -H 'X-Api-Key: assw_v1_<chave>'

Pedido

const resposta = await fetch('https://<endereço-da-API>/api/relatorios/resumo-facturacao?lojaId=01a12201-f4d4-7c07-86b7-e5b24035993e', {
  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/relatorios/resumo-facturacao?lojaId=01a12201-f4d4-7c07-86b7-e5b24035993e',
    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/relatorios/resumo-facturacao?lojaId=01a12201-f4d4-7c07-86b7-e5b24035993e");
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

{
  "hoje": 69540,
  "estaSemana": 69540,
  "esteMes": 2074574.05,
  "esteAno": 2074574.05
}

GET/api/relatorios/vendas-mensais#

As vendas de cada mês de um ano, por artigo.

Permissão RelatoriosDetalhados.Ler

Parâmetros

Nome	Onde	Tipo	Obrigatório
`ano`	na pesquisa	número inteiro	sim
`produtoId`	na pesquisa	identificador (UUID)
`lojaId`	na pesquisa	identificador (UUID)

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].mes`	número inteiro
`[].produtoId`	identificador (UUID)	O artigo.
`[].produto`	texto
`[].quantidade`	número	A quantidade.
`[].valor`	número	O valor.

Pedido

curl

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