Referência

Empresa e estabelecimentos

Quem é a empresa e quais são os seus estabelecimentos. É por aqui que se confirma que a chave está ligada à empresa certa.

Operação	O que faz
GET `/api/empresa`	Os dados da própria empresa: identificação fiscal, morada, contactos, contas bancárias e o estado da chave de assinatura.
GET `/api/lojas`	Os estabelecimentos da empresa.
POST `/api/lojas`	Cria um estabelecimento.
PUT `/api/lojas/{id}`	Altera um estabelecimento.
GET `/api/pesquisa`	A pesquisa global: um texto procura em clientes, documentos, artigos e fornecedores.
GET `/api/empresa/configuracao-geral`	A configuração geral da empresa (por agora, as cópias a imprimir por omissão).
PUT `/api/empresa/configuracao-geral`	Altera a configuração geral da empresa.
GET `/api/empresa/politica-vendas`	A política de vendas da empresa.
PUT `/api/empresa/politica-vendas`	Altera a política de vendas da empresa.
GET `/api/empresa/configuracao-fiscal-compras`	A configuração fiscal das compras: as respostas da empresa que condicionam o seu tratamento.
GET `/api/empresa/configuracao-fiscal-compras/historico`	O histórico das alterações às respostas fiscais das compras.
GET `/api/empresa/logotipo`	O logotipo da empresa.

GET/api/empresa#

Os dados da própria empresa: identificação fiscal, morada, contactos, contas bancárias e o estado da chave de assinatura.

Permissão Empresa.Ler

Serve para confirmar a que empresa a chave pertence. A chave privada de assinatura nunca é devolvida; só se diz se existe e qual é a versão.

Resposta (200 · JSON)

Campo	Tipo	Significado
`nome`	texto	O nome.
`slug`	texto
`email`	texto	O endereço de e-mail.
`numeroContribuinte`	texto ou nulo	O número de contribuinte (NIF).
`endereco`	texto ou nulo	A morada.
`municipioId`	identificador (UUID) ou nulo
`regimeFiscalId`	identificador (UUID) ou nulo
`informacaoFactura`	texto ou nulo
`contasBancarias`	lista de objectos
`contasBancarias[].banco`	texto
`contasBancarias[].numeroConta`	texto ou nulo
`contasBancarias[].iban`	texto ou nulo
`telefone`	texto ou nulo	O telefone.
`website`	texto ou nulo
`temLogotipo`	verdadeiro/falso
`observacao`	texto ou nulo	O texto livre.
`dadosFiscaisBloqueados`	verdadeiro/falso
`bloqueadaNaVersaoDeTestes`	verdadeiro/falso

Exemplo

Os dados da própria empresa

Pedido

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

Pedido

const resposta = await fetch('https://<endereço-da-API>/api/empresa', {
  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/empresa',
    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/empresa");
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

{
  "nome": "Mutamba Comercial, Lda.",
  "slug": "mutamba-comercial",
  "email": "geral@mutambacomercial.co.ao",
  "numeroContribuinte": "5417000987",
  "endereco": "Rua da Missão, n.º 45, Luanda",
  "municipioId": "c8a4df25-a9c1-d51f-9223-367545fbcb49",
  "regimeFiscalId": "01a0ee03-0fe7-7d63-aca7-e189893867d9",
  "informacaoFactura": "Mercadoria entregue e conferida pelo cliente. Mutamba Comercial, Lda. — comércio a retalho e a grosso.",
  "contasBancarias": [
    {
      "banco": "Banco BAI",
      "numeroConta": "0040.0000.1234.5678.1013.1",
      "iban": "AO06.0040.0000.1234.5678.1013.1"
    },
    {
      "banco": "Banco BFA",
      "numeroConta": "0006.0000.9876.5432.1011.2",
      "iban": "AO06.0006.0000.9876.5432.1011.2"
    }
  ],
  "telefone": "+244 923 456 789",
  "website": "www.mutamba-demo.example",
  "temLogotipo": false,
  "observacao": null,
  "temChaveAssinatura": true,
  "numeroCertificadoAgt": "0001",
  "versaoChaveAssinatura": "1",
  "dadosFiscaisBloqueados": true
}

GET/api/lojas#

Os estabelecimentos da empresa.

Permissão Lojas.Ler

Quando a empresa tem mais do que um estabelecimento, os pedidos que emitem documentos têm de indicar lojaId (ver Estabelecimentos).

Com apenasMinhas=true só vêm os estabelecimentos a que a chave tem acesso (uma chave presa a um estabelecimento vê só esse).

Parâmetros

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

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].id`	identificador (UUID)	Identificador único (UUID).
`[].nome`	texto	O nome.
`[].codigo`	texto	O código curto.
`[].endereco`	texto ou nulo	A morada.
`[].limiteAlertaSaldoGaveta`	número ou nulo
`[].toleranciaQuebraFechoCaixa`	número
`[].fechamentoCegoActivo`	verdadeiro/falso
`[].municipioId`	identificador (UUID) ou nulo

Exemplo

Os estabelecimentos da empresa

Pedido

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

Pedido

const resposta = await fetch('https://<endereço-da-API>/api/lojas', {
  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/lojas',
    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/lojas");
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-f4d4-7c07-86b7-e5b24035993e",
    "nome": "Loja Central",
    "codigo": "LC",
    "endereco": "Rua da Missão, n.º 45, Luanda",
    "limiteAlertaSaldoGaveta": null,
    "toleranciaQuebraFechoCaixa": 0,
    "fechamentoCegoActivo": true,
    "municipioId": null
  },
  {
    "id": "01a12201-f4d4-7da7-a880-4239624940d5",
    "nome": "Loja de Viana",
    "codigo": "LV",
    "endereco": "Estrada de Catete, Viana",
    "limiteAlertaSaldoGaveta": null,
    "toleranciaQuebraFechoCaixa": 0,
    "fechamentoCegoActivo": true,
    "municipioId": null
  }
]

POST/api/lojas#

Cria um estabelecimento.

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

Devolve o id. Cada estabelecimento nasce com um armazém principal e uma conta Caixa.

Corpo do pedido (JSON · CreateLojaCommand)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`codigo`	texto	sim	O código curto.
`endereco`	texto ou nulo		A morada.

Pedido

curl

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

PUT/api/lojas/{id}#

Altera um estabelecimento.

Permissão Lojas.Editar

Parâmetros

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

Corpo do pedido (JSON · UpdateLojaRequest)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`endereco`	texto ou nulo		A morada.
`limiteAlertaSaldoGaveta`	número ou nulo
`toleranciaQuebraFechoCaixa`	número
`fechamentoCegoActivo`	verdadeiro/falso
`municipioId`	identificador (UUID) ou nulo

Pedido

curl

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

GET/api/pesquisa#

A pesquisa global: um texto procura em clientes, documentos, artigos e fornecedores.

Permissão Clientes.Ler DocumentosEmitidos.Ler Produtos.Ler Fornecedores.Ler

Só devolve os grupos que o perfil da chave pode ver.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`q`	na pesquisa	texto
`limite`	na pesquisa	número inteiro

Pedido

curl

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

GET/api/empresa/configuracao-geral#

A configuração geral da empresa (por agora, as cópias a imprimir por omissão).

Permissão Documentos.Ler

Resposta (200 · JSON)

Campo	Tipo
`viasPorOmissao`	número inteiro
`comercioAGrosso`	verdadeiro/falso

Pedido

curl

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

PUT/api/empresa/configuracao-geral#

Altera a configuração geral da empresa.

Permissão Configuracao.Editar

Corpo do pedido (JSON · AtualizarConfiguracaoGeralCommand)

Campo	Tipo	Obrigatório
`viasPorOmissao`	número inteiro	sim
`comercioAGrosso`	verdadeiro/falso

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/empresa/configuracao-geral' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "viasPorOmissao": 1
}'

GET/api/empresa/politica-vendas#

A política de vendas da empresa.

Permissão (nenhuma: basta a chave)

Resposta (200 · JSON)

Campo	Tipo
`permitirPrecoVendaLivre`	verdadeiro/falso
`descontoMaximoVendaPercentual`	número
`limiteDescontoOperadorPercentual`	número ou nulo
`fechoComDiferencaExigeSupervisor`	verdadeiro/falso
`notaCreditoNoPdvExigeSupervisor`	verdadeiro/falso

Pedido

curl

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

PUT/api/empresa/politica-vendas#

Altera a política de vendas da empresa.

Permissão Empresa.Editar

Corpo do pedido (JSON · AtualizarPoliticaVendasCommand)

Campo	Tipo	Obrigatório
`permitirPrecoVendaLivre`	verdadeiro/falso	sim
`descontoMaximoVendaPercentual`	número	sim
`limiteDescontoOperadorPercentual`	número ou nulo
`fechoComDiferencaExigeSupervisor`	verdadeiro/falso
`notaCreditoNoPdvExigeSupervisor`	verdadeiro/falso

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/empresa/politica-vendas' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "permitirPrecoVendaLivre": false,
  "descontoMaximoVendaPercentual": 0
}'

GET/api/empresa/configuracao-fiscal-compras#

A configuração fiscal das compras: as respostas da empresa que condicionam o seu tratamento.

Permissão Empresa.Ler

Resposta (200 · JSON)

Campo	Tipo	Significado
`perguntas`	lista de objectos
`perguntas[].codigo`	texto	O código curto.
`perguntas[].titulo`	texto
`perguntas[].ajuda`	texto
`perguntas[].opcoes`	lista de objectos
`perguntas[].opcoes[].codigo`	texto	O código curto.
`perguntas[].opcoes[].rotulo`	texto
`perguntas[].valor`	texto	O valor.
`perguntas[].confirmada`	verdadeiro/falso
`perguntas[].validadoPor`	texto ou nulo
`perguntas[].validadoEmUtc`	data e hora (ISO 8601) ou nulo
`perguntas[].porOmissao`	verdadeiro/falso
`porConfirmar`	número inteiro

Pedido

curl

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

GET/api/empresa/configuracao-fiscal-compras/historico#

O histórico das alterações às respostas fiscais das compras.

Permissão Empresa.Ler

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].id`	identificador (UUID)	Identificador único (UUID).
`[].pergunta`	texto
`[].titulo`	texto
`[].valorAnterior`	texto ou nulo
`[].confirmadaAnterior`	verdadeiro/falso ou nulo
`[].valorNovo`	texto
`[].confirmadaNova`	verdadeiro/falso
`[].validadoPor`	texto ou nulo
`[].utilizadorNome`	texto ou nulo
`[].emUtc`	data e hora (ISO 8601)

Pedido

curl

curl 'https://<endereço-da-API>/api/empresa/configuracao-fiscal-compras/historico' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/empresa/logotipo#

O logotipo da empresa.

Permissão (nenhuma: basta a chave)

Resposta

Devolve 200 com a imagem do logotipo.

Pedido

curl

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