Uma chave por integração
Crias uma chave para cada sistema que se liga ao Mucanda, e revogas só essa quando já não for precisa.
Integrações e API
Os teus dados são teus: liga a loja online, a contabilidade ou o teu painel de gestão ao Mucanda com uma chave de API, só com as permissões que decidires.
# emitir uma factura/recibo da tua loja online
curl -X POST https://<endereço-da-API>/api/documentos \
-H "X-Api-Key: <a-tua-chave>" \
-H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-H "Content-Type: application/json" \
-d '{ "tipoDocumentoId": "...", "clienteId": "...", "itens": [...], "pagamentos": [...] }'
# a resposta traz o documento emitido; repetir o pedido
# com a mesma chave devolve o mesmo documento, nunca outro
{ "id": "01a12f68-f692-7d4d-8f54-377d674d730a" }Só as permissões que deres
Cada chave tem o perfil que escolheres: se o perfil não pode alterar artigos, a chave também não.
Documentação a sério
Guias, referência de cada operação com exemplos reais e o ficheiro OpenAPI para gerares um cliente na tua linguagem.
Como funciona
Os mesmos dados que vês no ecrã, por API
Uma chave de API dá a outro programa um acesso à tua empresa que tu controlas ao pormenor. As operações são as do próprio sistema, com as mesmas regras e as mesmas validações: um documento criado por API segue a mesma numeração, a mesma assinatura e as mesmas regras fiscais que um criado no balcão.
Quem desenvolve a integração tem tudo na documentação da API: primeiros passos, referência de cada operação, erros, limites e exemplos reais.
Importar
Trazer para o Mucanda artigos, clientes ou vendas que vêm de outro sistema.
Exportar
Disponibilizar os teus dados à contabilidade, a um painel de gestão ou a uma aplicação tua.
Emitir
Facturas, facturas/recibo, notas de crédito, recibos e guias, com stock e pagamentos tratados pelo sistema.
Exemplos
O que podes ligar ao Mucanda
Como a chave dá acesso às operações do sistema, os casos de uso seguem o que o Mucanda já faz.
Contabilidade
Uma aplicação do teu contabilista consulta os documentos, os pagamentos, as despesas e os ficheiros SAF-T do mês.
Painéis de gestão
Um painel teu (ou uma folha de cálculo) lê as vendas por artigo, as contas a receber e o stock.
Loja online ou aplicação própria
Consulta o stock e os preços, cria clientes e emite a factura/recibo de cada encomenda.
Importação inicial
Trazes para o Mucanda os artigos, clientes e fornecedores que já tinhas noutro sistema.
Manter dois sistemas iguais
Pedes só o que mudou desde a última vez (clientes, fornecedores e artigos alterados, e os eliminados), em vez de repetir a lista inteira.
Reagir na hora
A tua loja online recebe um aviso assim que a factura é emitida ou a AGT a valida, sem andar a perguntar.
Perfis só de leitura
Uma chave com um perfil que só consulta não consegue alterar nada, mesmo que alguém a usasse mal.
Avisos em tempo real
O Mucanda avisa o teu sistema quando algo acontece
Em vez de o teu sistema perguntar de cinco em cinco minutos se há novidades, indicas-nos um endereço dele e nós avisamos na hora: um documento emitido, a validação da AGT, um pagamento recebido. A isto chama-se webhook. Registas o endereço em Definições › Webhooks e escolhes os eventos que queres receber.
Como esse endereço é público, qualquer pessoa o podia chamar a fingir que é o Mucanda. Por isso cada aviso vai assinado: leva uma assinatura (um HMAC-SHA256) calculada com um segredo que só tu e nós conhecemos. O teu sistema recalcula-a e só confia no aviso se bater certo; se alguém alterar o conteúdo pelo caminho, deixa de bater.
Eventos
Documento emitido, documento validado ou recusado pela AGT, documento anulado, pagamento recebido e cliente criado. Cada endereço recebe só os que escolheres.
Assinatura verificável
Cada aviso leva a hora e a assinatura, e o teu sistema recusa avisos antigos ou alterados. A documentação traz o código pronto para Node.js, Python, PHP e C#.
Segredo mostrado uma só vez
Guardado por nós cifrado, e que podes rodar quando quiseres: durante 24 horas os avisos levam as duas assinaturas, para trocares o segredo sem perder nenhum.
Nada se perde
Se o teu servidor estiver em baixo, repetimos o aviso com intervalos crescentes durante cerca de 3 dias, e podes reenviar à mão o que falhou. Os eventos dos últimos 30 dias podem ainda ler-se por API para recuperar o que faltar.
Sem surpresas
Um aviso pode chegar mais de uma vez, por isso cada um traz um identificador único para o teu sistema ignorar os repetidos.
Só endereços públicos e seguros
Exigimos HTTPS e recusamos endereços de redes internas, para um webhook nunca servir de porta de entrada. E só uma pessoa autenticada cria webhooks, nunca uma chave de API.
Ecrã de acompanhamento
Vês cada entrega, a resposta do teu servidor e quantas tentativas foram precisas, e podes enviar um aviso de teste.
Todos os módulos
A API é completa: tu decides o que cada chave vê
A API cobre todos os módulos do Mucanda: facturação, clientes e fornecedores, artigos e stock, tesouraria e contas, caixa (em consulta), avenças, promoções, encomendas, conformidade fiscal, recursos humanos e os módulos de sector (produção, restauração, contratos, marcações, estética, lavandaria, oficinas e hospedagem). São mais de 900 operações. Como és tu, dentro do Mucanda, que crias cada chave e escolhes o que ela pode ver e fazer, não há módulos «escondidos»: o que não queres expor, não dás.
Tesouraria
Contas, extractos, lançamentos, transferências, receitas, fluxo de caixa, conciliação bancária e fecho de período.
Recursos humanos
Trabalhadores, férias e assiduidade, ponto, folha de salários, cessações, processos disciplinares e mais, com um acesso reforçado.
Módulos de sector
As operações de cada módulo contratado (por exemplo, ordens de produção, comandas, marcações ou reservas de quartos), com as mesmas regras do ecrã. Só funcionam nas empresas que têm o módulo.
Sempre fora do alcance de uma chave
Utilizadores, perfis e chaves, a chave de assinatura dos documentos, a subscrição, as cópias de segurança e a identidade de quem denuncia.
Dados sensíveis
Recursos humanos, hóspedes e fichas de beleza pedem um acesso reforçado, e o teu consentimento
Os dados dos trabalhadores (remunerações, folha, assiduidade, processos disciplinares), dos hóspedes e as fichas de saúde e beleza dos clientes são dados de pessoas. Por isso uma chave só chega lá se tu o decidires, de propósito, ao criá-la, e quem tem de ter atenção sabe a quê.
Consentimento registado
Lês o texto, aceitas em nome da empresa, e fica gravado quem aceitou, quando e qual era o texto.
Uma permissão própria
Não basta poder criar chaves; só quem tem permissão para autorizar dados sensíveis o pode fazer. Por omissão, o Administrador.
Endereços de rede obrigatórios e validade até 90 dias
A chave só funciona a partir dos servidores que indicares e tem de ser renovada, com novo consentimento.
Cada pedido fica registado, antes de ser atendido
Quando, o quê e de onde. Vês o registo em Definições › Chaves de API, e ninguém o consegue alterar nem apagar.
Sem acesso reforçado, nem por outra porta
Uma chave normal não vê nada destas áreas, mesmo que o perfil lhe desse permissão (nem na Visão 360°).
Controlo
Tu decides o alcance de cada chave
Uma chave nunca é «acesso a tudo». Quatro limites combinam-se, e cada um só pode restringir o anterior.
Uma lista fechada de operações
A API cobre todos os módulos, mas utilizadores, perfis, chaves, chave de assinatura, subscrição e a plataforma ficam sempre fora do alcance de qualquer chave, mesmo de um administrador.
Dados sensíveis só com consentimento
Os recursos humanos exigem um acesso reforçado, que és tu a dar ao criar a chave (ver abaixo).
Um perfil de acesso
A chave tem exactamente as permissões do perfil que escolheres, e nunca podes dar-lhe mais do que tu próprio tens.
Um estabelecimento (opcional)
Prende a chave a uma loja; ela só emite, movimenta stock e consulta nessa loja.
Endereços de rede (opcional)
A chave só funciona a partir dos servidores que indicares.
Segurança
Pensada para que uma chave perdida não seja um desastre
As chaves são feitas para ligações entre servidores e protegidas em vários pontos.
Mostrada uma só vez
O segredo vê-se no momento em que a chave é criada. Depois guardamos apenas uma impressão digital, que não permite reconstruir a chave.
Validade opcional e revogação imediata
Defines uma data de expiração, se quiseres, e revogas a chave a qualquer momento, com efeito no pedido seguinte.
Um titular
A chave actua em nome de quem a criou. Se essa pessoa sair da empresa, a chave pára; um administrador assume-a e a integração volta a funcionar sem mudar nada.
Limite de pedidos por chave
Cada chave tem o seu próprio limite, por isso uma integração em excesso não trava as outras nem quem trabalha no balcão.
Registo de utilização
Vês quando cada chave foi usada pela última vez e, em cada documento, qual a chave que o emitiu.
Uma chave não gere chaves
Só um administrador autenticado cria, lista ou revoga chaves.
Fiabilidade
Repetir um pedido não duplica nada
Nas ligações entre sistemas, um pedido pode falhar a meio e ser repetido. Com a chave de idempotência, o Mucanda reconhece o pedido repetido e devolve o resultado do primeiro, em vez de criar o registo duas vezes.
Vale para a emissão de documentos e para as operações que criam registos (clientes, fornecedores, artigos, compras, despesas, pagamentos).
Os documentos fiscais emitidos nunca se alteram: uma correcção faz-se com um novo documento, como a lei exige.
Cada erro traz um código estável e um identificador do pedido, para a tua equipa e a nossa saberem exactamente o que se passou.
O que convém saberes
O que ainda não está feito, o que foi testado de que maneira, e o que depende de ti. Preferimos dizê-lo aqui a prometer a mais.
A API é só para ligações entre servidores. As chaves não devem ser usadas em páginas de internet nem em aplicações instaladas em telemóveis.
Os webhooks avisam de seis tipos de eventos (documentos, validação da AGT, anulações, pagamentos e clientes novos). Para outras alterações, o outro sistema consulta os dados, só o que mudou, com a sincronização incremental.
Não há um ambiente de ensaio separado: para experimentar, pede-nos uma empresa de demonstração.
A API só inclui as operações documentadas. Se precisas de outra, diz-nos o caso de uso e avaliamo-la.
Queres ver as integrações por API a funcionar no teu negócio?
Mostramos o sistema com os teus próprios casos e preparamos uma proposta clara, sem compromisso.