Como usar a Moloni no Hub

Abrir painel Moloni
Guia passo-a-passo para o dia-a-dia: consultar clientes e produtos, listar e enviar documentos, emitir faturas à mão e passar encomendas Shopify para a Moloni — sem sair do Hub.
Importante antes de começares Tudo o que fazes neste painel acontece mesmo na Moloni — é a mesma base de dados que a contabilidade usa. Emitir um documento Final é definitivo (a Moloni só permite anular com nota de crédito). Em caso de dúvida, emite primeiro como Rascunho.

Conteúdo

  1. Abrir o painel e ler o estado
  2. Visão geral e contadores
  3. Clientes
  4. Fornecedores
  5. Produtos e categorias
  6. Stock
  7. Documentos (listar, PDF, email)
  8. Emitir uma fatura à mão
  9. Sincronizar encomenda Shopify
  10. Configurações (IVA, séries, armazéns…)
  11. Consola raw (avançado)
  12. Problemas e perguntas
  13. Glossário

1 Abrir o painel e ler o estado da ligação

Na sidebar do Hub vai a Integrações → Moloni, ou usa o atalho directo /moloni.

No topo tens a barra de estado. A bolinha à esquerda diz se está tudo bem:

  • Verde — ligado e a autenticar correctamente. Podes trabalhar.
  • Laranja — ligado mas com avisos (ex.: token a expirar). Funciona, mas avisa o Emídio.
  • Vermelho — sem ligação. As credenciais falham. Nada vai carregar.

À direita da barra há dois selos: env (em que ambiente está configurado) e modo — atenção a este: diz Produção (documentos reais) ou Sandbox (ambiente de testes, não conta para a contabilidade).

Se algo encravar: "Reset token" O botão Reset token na barra de estado limpa a sessão guardada e força nova autenticação. É o primeiro a tentar quando aparecem erros de autenticação. Não apaga dados — só renova a ligação.

2 Visão geral e contadores

Por baixo da barra de estado tens 4 cartões de resumo: Clientes, Produtos, Documentos (recentes) e Empresa ativa (com o NIF). É a fotografia rápida da empresa ligada.

Logo a seguir está a fila de abas. Vais usar sobretudo as do dia-a-dia — Clientes, Produtos, Documentos, Nova fatura e Sincronização Shopify. As restantes (IVA, Pagamentos, Armazéns, Séries, Países) são de configuração e mexem-se raramente.

A primeira aba, Visão geral, lista as empresas autorizadas. O botão Recarregar visão geral volta a buscar tudo à Moloni se algo parecer desactualizado.

3 Clientes

Na aba Clientes tens uma barra de pesquisa e quatro botões:

  • Pesquisar — escreve nome ou parte do nome.
  • Por NIF — cola o número de contribuinte para encontrar o cliente exacto.
  • Listar todos — traz a lista completa (pode demorar uns segundos).
  • + Novo cliente — abre um formulário para criar.

A tabela mostra Nº, Nome, NIF, Email, Telefone e Cidade. Clica numa linha para editar os dados desse cliente.

142 · Padaria Central, Lda. · NIF 501234567 · Porto
Editar
Antes de criar, pesquisa Procura sempre pelo NIF antes de criar um cliente novo — evita duplicados na Moloni, que depois baralham a faturação.

4 Fornecedores

A aba Fornecedores funciona igual à de Clientes, mas para quem nos vende:

  • Pesquisar por NIF — encontra o fornecedor pelo contribuinte.
  • Listar todos — lista completa.
  • + Novo fornecedor — cria um novo registo.

Clica numa linha para ver/editar. Os mesmos fornecedores aparecem também noutras páginas do Hub (ex.: /hub/suppliers), que cruzam estes dados com encomendas e faturação.

5 Produtos e categorias

Produtos

Na aba Produtos podes encontrar um artigo de várias maneiras:

  • Pesquisar por nome · Por referência (SKU) · Por EAN (código de barras) · Listar todos.
  • + Novo produto para criar um artigo (nome, referência, preço, IVA, categoria).

A tabela mostra Referência, Nome, Preço, Stock, IVA e Categoria. Clica para editar.

Categorias

A aba Categorias organiza os produtos em árvore. Listar para ver, + Nova categoria para criar. Só mexes aqui quando estás a arrumar o catálogo.

Referência (SKU) tem de bater certo com a Shopify Para a sincronização Shopify → Moloni encontrar o produto correcto, a referência na Moloni deve ser igual ao SKU na Shopify.

6 Stock

Na aba Stock indicas o ID do produto e clicas Consultar para ver o stock e o histórico de movimentos por armazém.

Para corrigir stock (quebra, oferta, acerto de inventário) usa + Movimento de stock: escolhes o tipo de movimento, a quantidade e o armazém, e o ajuste fica registado na Moloni.

Para o armazém, há atalho melhor Movimentos de stock do dia-a-dia (quebras, ofertas, transferências entre armazéns) fazem-se mais à mão em /hub/stock-movements, que regista o motivo em texto e sincroniza com a Moloni. Esta aba serve para consultar e para acertos pontuais.

7 Documentos — listar, abrir PDF, enviar por email

A aba Documentos é onde consultas tudo o que já foi emitido. No topo:

  1. Escolhe o tipo no menu: Faturas, Faturas-recibo, Faturas simplificadas, Notas de crédito, Notas de débito, Pró-forma, Orçamentos, Encomendas, Guias de transporte, Recibos, Guias de movimentação ou Faturas de consignação.
  2. Opcional: filtra por datas (de / até) e por ID de cliente.
  3. Clica Listar.

Cada linha mostra o documento, data, cliente, total e o estado — Final ou Rascunho. À direita, dois botões:

Fatura FT 2026/142 · 30/05/2026 · Padaria Central · 248,50 €
PDFEmail
  • PDF — abre o documento em PDF numa nova aba (para imprimir ou guardar).
  • Email — pede o endereço do destinatário e envia o documento directamente pela Moloni.

8 Emitir uma fatura à mão Manual

Para faturar algo que não veio da Shopify (venda directa, B2B, serviço), usa a aba Nova fatura:

  1. Escolhe o cliente e o tipo de documento (fatura, fatura-recibo, etc.).
  2. Na tabela de linhas, clica + Linha por cada produto/serviço: nome, quantidade, preço, desconto % e taxa de IVA.
  3. Confirma o total que aparece em baixo.
  4. Clica Emitir documento.
Rascunho vs. Final Emite primeiro como Rascunho se quiseres rever. Um documento Final é fiscalmente definitivo — para o corrigir tens de emitir uma nota de crédito. Na dúvida, rascunho.

9 Passar uma encomenda Shopify para a Moloni

A aba Sincronização Shopify cria a fatura na Moloni a partir de uma encomenda da loja. Útil quando uma encomenda não foi faturada automaticamente.

  1. Cola no campo grande o JSON da encomenda (objeto order do Shopify Admin).
  2. Indica a Série a usar e o Método de pagamento.
  3. Define Marcar como paga? (Sim/Não) e o Estado (Final ou Rascunho).
  4. Escolhe a acção:
    • Só sincronizar cliente — cria/actualiza apenas o cliente na Moloni, sem fatura. Bom para testar primeiro.
    • Criar fatura na Moloni — cria o cliente (se preciso) e emite o documento.

O resultado aparece em baixo, em texto, com o que foi criado.

Onde arranjar o JSON da encomenda Vem do Shopify Admin (REST API da order). Se não tiveres à mão, pede ao Emídio ou usa antes as páginas que já fazem isto de forma assistida. Esta aba serve sobretudo para casos pontuais e para corrigir falhas.

10 Configurações: IVA, Pagamentos, Armazéns, Séries, Países

Estas abas são de leitura/configuração e mexem-se raramente. Servem para confirmar como a empresa está montada na Moloni:

  • IVA — taxas de imposto disponíveis (23%, 13%, 6%, isento…) e a respectiva zona fiscal.
  • Pagamentos — métodos de pagamento (numerário, transferência, MB…) com IBAN/SWIFT.
  • Armazéns — locais de stock da empresa.
  • Séries — séries de numeração dos documentos e qual o próximo número. É daqui que tiras o ID da série para a sincronização Shopify (Passo 9).
  • Países / Idiomas — tabelas de referência (países, idiomas, moedas, zonas fiscais, unidades de medida).

Cada uma tem Listar para ver. Criar/editar destas tabelas tem impacto fiscal — confirma com o Emídio antes de mexer.

11 Consola raw Avançado

A aba Consola raw permite chamar qualquer função da API Moloni directamente (ex.: customers.search). É uma ferramenta de debug — usa-se sobretudo com o Emídio ao lado.

Cuidado Chamadas em POST podem criar ou alterar dados reais na Moloni. Se não tens a certeza do que faz, não executes. Para o dia-a-dia não precisas desta aba.

? Problemas e perguntas

A bolinha de estado está vermelha / "erro de autenticação"

Por esta ordem:

  • Clica Reset token na barra de estado e depois Recarregar.
  • Se continuar vermelho, as credenciais expiraram ou mudaram — avisa o Emídio (é configuração de servidor, não se resolve no painel).
As tabelas aparecem vazias mesmo depois de "Listar"

Confirma primeiro o estado no topo (tem de estar verde). Algumas listagens trazem muitos registos e demoram uns segundos — espera. Se for a aba Documentos, verifica se o intervalo de datas não está demasiado apertado.

Emiti um documento como Final por engano

Não dá para apagar (é fiscalmente definitivo). Tens de emitir uma nota de crédito a anular esse documento. Fala com o Emídio ou com a contabilidade para fazer certo.

O selo de modo diz "Sandbox"

Estás no ambiente de testes — os documentos que emitires não contam para a contabilidade real. Útil para experimentar. Para faturar a sério tem de estar em Produção; se não estiver e devia estar, avisa o Emídio.

O PDF não abre quando clico

Costuma ser bloqueio de pop-ups do browser. Permite pop-ups para o domínio do Hub e tenta de novo.

A sincronização Shopify deu erro "produto não encontrado"

A referência do produto na Moloni tem de ser igual ao SKU na Shopify. Vai à aba Produtos, procura pela referência, e corrige se não bater certo. Depois repete a sincronização.

Criei um cliente duplicado

Pesquisa sempre pelo NIF antes de criar. Se já criaste o duplicado, edita/marca o errado e usa o correcto na faturação. Para limpar a fundo, fala com a contabilidade.

A Glossário rápido

Final vs. Rascunho
Final = documento fiscalmente definitivo, conta para a contabilidade. Rascunho = ainda editável, não é oficial.
Série
Sequência de numeração dos documentos (ex.: FT 2026/…). Cada tipo de documento tem a sua. O ID da série usa-se na sincronização Shopify.
Referência
O código interno do produto (SKU). Tem de ser igual ao SKU da Shopify para a sincronização funcionar.
EAN
Código de barras do produto. Pesquisável na aba Produtos.
NIF
Número de contribuinte. A forma mais segura de encontrar um cliente ou fornecedor sem criar duplicados.
Nota de crédito
Documento que anula (total ou parcialmente) uma fatura já emitida. É assim que se corrige um Final errado.
Zona fiscal
Regime de impostos consoante o território (Continente, Açores, Madeira, estrangeiro). Define as taxas de IVA aplicáveis.
Sandbox vs. Produção
Sandbox = ambiente de testes, não conta. Produção = a Moloni real da empresa. Lê o selo "modo" no topo.
Reset token
Renova a sessão de ligação à Moloni quando há erros de autenticação. Não apaga dados.

Pronto para começar?

Abre o painel Moloni e confirma que a bolinha de estado está verde.

Abrir painel Moloni