Começar
Permissões e alcance
Os limites em camadas: a lista fechada de operações, o perfil, os dados sensíveis, o estabelecimento e os endereços de rede.
Uma chave nunca tem «acesso a tudo». Os limites combinam-se, do mais largo ao mais estreito, e cada um só pode restringir o anterior:
| Limite | O que decide | Quando falha |
|---|---|---|
| Lista fechada de operações | Onde a chave pode ir: só as operações desta documentação. Utilizadores, perfis, chaves, chave de assinatura, subscrição, suporte e a plataforma ficam sempre de fora, mesmo para um administrador. | 403 RECURSO_FORA_DO_ALCANCE_DA_CHAVE |
| Dados sensíveis (recursos humanos) | Só com acesso reforçado, dado pelo dono da empresa ao criar a chave, com consentimento registado, endereços de rede e validade até 90 dias. Ver Dados sensíveis. | 403 DADOS_SENSIVEIS_NAO_AUTORIZADOS |
| Perfil | O que cada operação permite: a mesma permissão que exigiria a uma pessoa (Documentos.Emitir, Produtos.Ler…). | 403 SEM_PERMISSAO (a resposta diz qual) |
| Estabelecimento (opcional) | Prende a chave a um estabelecimento: só emite, movimenta stock e consulta nele. | 403 ESTABELECIMENTO_NAO_PERMITIDO |
| Endereços (opcional) | Os endereços de rede (IP ou intervalo) de onde a chave pode ser usada. | 403 ORIGEM_NAO_PERMITIDA |
#Escolher o perfil
Crie um perfil por integração, com o mínimo necessário, em vez de reutilizar o de administrador. Se a integração só consulta, um perfil de leitura garante que, mesmo que a chave seja mal usada, nada se altera.
Loja online (lê artigos e stock, cria clientes, emite e corrige vendas)
Permissões do perfil:
Clientes.EditarCriar, editar e eliminar clientesClientes.LerVer clientes e os seus extractosDocumentos.AnularAnular documentosDocumentos.EmitirEmitir documentos (facturas, recibos, guias, notas de crédito, pró-formas)Documentos.LerVer documentos, rascunhos e tipos de documentoEmpresa.LerVer os dados da empresa e as séries de documentosEstoque.ArmazemLerVer armazénsEstoque.ProdutosEmEstoqueLerVer o stock actual e o stock baixoLojas.LerVer lojasMetodosPagamento.LerVer métodos de pagamento
Contabilidade (só leitura de documentos, pagamentos, compras e ficheiros fiscais)
Permissões do perfil:
Clientes.LerVer clientes e os seus extractosDocumentos.LerVer documentos, rascunhos e tipos de documentoDocumentosEmitidos.LerVer o histórico de documentos emitidosFinanceiro.ContasPagarLerVer as contas a pagar a fornecedores e os seus pagamentosFornecedores.LerVer fornecedoresRelatoriosDetalhados.LerVer relatórios detalhados (vendas, produtos, clientes, pagamentos)Saft.ExportarExportar o ficheiro SAF-T (contém todos os documentos e NIF de clientes)
Painel de gestão (só leitura de números)
Permissões do perfil:
DocumentosEmitidos.LerVer o histórico de documentos emitidosEstoque.ProdutosEmEstoqueLerVer o stock actual e o stock baixoFinanceiro.ContasPagarLerVer as contas a pagar a fornecedores e os seus pagamentosRelatoriosDetalhados.LerVer relatórios detalhados (vendas, produtos, clientes, pagamentos)
#O que a lista fechada deixa de fora
A API cobre todos os módulos do Mucanda: o dono da empresa decide, em Definições › Chaves de API, o que cada chave vê. Os recursos humanos, por serem dados de pessoas, exigem um acesso reforçado (Dados sensíveis). Ficam de fora só o que permitiria escalar poderes ou sair do controlo da empresa:
- Utilizadores, perfis e chaves de API (uma chave não gere chaves, nem se dá poderes a si própria).
- A chave de assinatura dos documentos, a adesão e as séries da facturação electrónica, a alteração das séries de documentos e da identidade fiscal da empresa.
- A subscrição e os planos, o suporte e a plataforma; as sessões e os dispositivos do ponto de venda; a gestão dos webhooks (só uma pessoa os cria).
- As cópias de segurança (levariam tudo, inclusive recursos humanos, por um caminho sem controlo), a importação em massa de trabalhadores e a identidade de quem denuncia no canal de denúncias.
- Abrir, fechar e movimentar o caixa: são do operador no balcão. A API só consulta o caixa.
Uma operação nova só entra na lista quando é documentada e testada: a lista só cresce. Um pedido fora dela responde sempre 403 RECURSO_FORA_DO_ALCANCE_DA_CHAVE, mesmo que o perfil tivesse a permissão.