Moloni¶
Serviço Moloni — identificador moloni. A emissão de faturas-recibo e notas de
crédito, e a descarga dos respetivos PDF, foram verificadas com uma conta real do Moloni.
Configurar o Moloni¶
No Moloni¶
- Na área de programador do Moloni, crie uma aplicação. Anote o seu ID de programador (client_id) e o Segredo do cliente.
- Registe nessa aplicação o redirect URI do plugin. Aparece (com um botão Copiar) na
página de definições do plugin e é o mesmo para todos os eventos e organizadores:
https://<o seu domínio do pretix>/control/ptinvoicing/moloni/callback/. - Na empresa de onde vai faturar, confirme que tem uma série de documentos para faturas-recibo e outra, separada, para notas de crédito (uma série do Moloni está presa a um tipo de documento), além de pelo menos uma forma de pagamento e um prazo de vencimento ("Pronto pagamento").
No pretix¶
Abra Configurações → Faturação PT do evento e clique no cartão Moloni. Para configurar o Moloni uma só vez para todos os eventos de um organizador, faça o mesmo em Configurações → Faturação PT do organizador; veja Uma ligação para todos os eventos.

- Preencha o ID de programador (client_id) e o Segredo do cliente.
- Carregue em Ligar ao Moloni. É enviado para o Moloni para autorizar a aplicação e depois trazido de volta a esta página. O que tiver escrito é guardado pelo caminho; não é preciso guardar primeiro. De volta, o painel mostra Ligado, com os botões Voltar a ligar ao Moloni e Desligar.
- Escolha a Empresa. Com várias empresas na conta tem de escolher uma explicitamente; cada opção mostra o nome e o NIF. As restantes listas carregam para essa empresa.
- Escolha a Série de documentos das faturas-recibo e a Série de notas de crédito. Têm de ser séries diferentes, a segunda criada para o tipo de documento Nota de Crédito.
- Escolha a Taxa de IVA que o pretix cobra nos bilhetes e um Motivo de isenção se algum bilhete for vendido a 0%. Veja IVA.
-
Escolha a Forma de pagamento por omissão, um Prazo de vencimento, e o Tipo de artigo e a Unidade com que os artigos de catálogo do plugin são criados. Veja Artigos.

-
Opcionalmente, associe cada forma de pagamento do pretix a uma do Moloni na tabela Formas de pagamento. Veja Formas de pagamento.

-
Carregue em Guardar. Até o fazer, a secção diz Ainda não está em uso e nada é emitido.
A ligação¶
Ligar ao Moloni usa o fluxo de autorização do Moloni: não é guardada nenhuma palavra-passe do Moloni, só os tokens de acesso. O refresh token expira ao fim de 14 dias sem uso, por isso o plugin renova cada ligação uma vez por dia, e um evento sem vendas nunca a perde.
Se o Moloni recusar a renovação, a ligação fica expirada: a página de definições indica-o, os painéis das encomendas avisam que nada pode ser emitido, e o e-mail de contacto do evento (pretix Configurações → Geral) recebe uma mensagem com uma ligação para voltar a ligar. Carregue em Voltar a ligar ao Moloni.
Desligar pede confirmação primeiro, porque sem ligação não é possível emitir nenhum documento para o evento.
Utilizador e palavra-passe
Continuam a ser aceites como alternativa a Ligar ao Moloni, e ficam escondidos enquanto estiver ligado. Se estiverem preenchidos, uma ligação expirada volta a entrar sozinha, sem esperar que volte a ligar.
Uma ligação para todos os eventos¶
Carregue em Ligar ao Moloni em Configurações → Faturação PT do organizador e todos os eventos desse organizador passam a emitir por essa ligação, com a empresa, as séries e as restantes definições aí guardadas. Não é preciso ligar evento a evento; veja Definições ao nível do organizador para saber como os eventos herdam.
Na página de definições de um evento nessas condições:

- o painel diz Ligado através das definições do organizador, e não há botão Desligar, porque a ligação não é do evento;
- Ligar este evento em separado dá ao evento uma ligação própria (outra conta Moloni, por exemplo). A ligação do organizador, e todos os outros eventos, ficam como estavam. Desligar nesse evento, mais tarde, remove só a ligação dele, e o evento volta a usar a do organizador;
- a tabela de formas de pagamento continua a ser preenchida em cada evento.
Uma ligação partilhada é renovada uma vez por dia para o organizador, não uma vez por evento. Se expirar, a página de cada evento diz que a ligação do organizador expirou e tem uma ligação para a página do organizador, onde Voltar a ligar ao Moloni a repõe para todos. O e-mail de aviso segue para o e-mail de contacto dos eventos que a usam, uma vez por endereço.
Definições¶
A maioria dos campos passa a lista, preenchida a partir da sua conta Moloni, depois de ligado. Os campos de cada empresa carregam depois de escolher a Empresa.
| Definição | Obrigatória | Descrição |
|---|---|---|
| ID de programador (client_id) | sim | Da área de programador do Moloni. |
| Segredo do cliente | sim | Da área de programador do Moloni. |
| Utilizador / palavra-passe Moloni | não | Só sem Ligar ao Moloni; ver acima. |
| Empresa | sim | Com várias empresas na conta, tem de escolher uma explicitamente. Cada opção mostra o nome e o NIF. |
| Série de documentos | sim | Série usada nas faturas-recibo. |
| Série de notas de crédito | sim | Uma série criada para o tipo de documento Nota de Crédito. Não pode ser a série das faturas-recibo. |
| Taxa de IVA | em bilhetes com IVA | Tem de ser a mesma taxa que o pretix cobra; ver IVA. |
| Motivo de isenção | em bilhetes a 0% | Os códigos de isenção do Moloni, por exemplo M07 (Artigo 9.º do CIVA). |
| Forma de pagamento | sim | Uma fatura-recibo leva sempre um pagamento; é a forma com que fica registado quando a forma de pagamento do pretix não tem associação própria. |
| Tipo de artigo | sim | Serviço (por omissão), Produto ou Outro: como os artigos do catálogo são criados, salvo indicação na página do próprio produto. Ver Artigos. |
| Unidade | sim | A unidade de medida dos artigos. |
| Limite da referência | não | O comprimento máximo de uma referência de artigo no Moloni, prefixo incluído. Por omissão 30, o máximo do Moloni; baixe-o se a sua conta permitir menos. |
| Prazo de vencimento | sim | Usado em cada novo cliente no Moloni, por exemplo "Pronto pagamento". |
| Formas de pagamento (tabela) | não | Uma linha por forma de pagamento aceite no evento; ver Formas de pagamento. Não aparece na página de um organizador. |
Formas de pagamento¶
O Moloni regista um pagamento em cada fatura-recibo. A tabela Formas de pagamento lista cada forma de pagamento aceite no evento (Multibanco, MB WAY, transferência, bilheteira…) e deixa escolher a forma de pagamento do Moloni com que fica registada. Uma linha deixada em predefinida usa a definição Forma de pagamento acima.
Uma encomenda paga por várias formas recebe um pagamento por forma, com o respetivo valor. Uma encomenda marcada como paga à mão no Control é registada com a forma da sua última outra tentativa de pagamento (uma referência Multibanco que foi paga mas nunca confirmada automaticamente conta como Multibanco).
Artigos¶
O Moloni só fatura artigos do seu catálogo, por isso cada produto do pretix tem um, criado automaticamente na primeira venda e reutilizado daí em diante. Os relatórios de vendas do Moloni continuam assim separados por tipo de bilhete. Cada linha do documento continua a mostrar o nome do produto no pretix e o preço efetivamente pago.
Referência. Um artigo do catálogo é encontrado pela referência: o Prefixo das referências de
produto das definições gerais (pretix- por omissão) seguido da referência do próprio produto.
- Sem referência própria, a de um produto é
item-<id>, o que dápretix-item-<id>. Cada tipo de taxa (taxa de pagamento, de envio…) também tem um artigo,pretix-fee-<tipo>. -
Para a escolher, abra o produto no pretix: a página tem um separador Faturação PT com o campo Referência do produto.
VIPnesse campo dá a referência de catálogopretix-VIP. Dois produtos do mesmo evento não podem ter a mesma referência, e as formasitem-<número>efee-…estão reservadas.
-
Prefixo e referência juntos podem ter no máximo 30 caracteres (a definição Limite da referência). A página de definições mostra quantos sobram para a referência enquanto escreve o prefixo, e recusa um prefixo que deixe menos de 12. Uma referência demasiado comprida pára a emissão com um erro que indica o produto, antes de criar o que quer que seja no Moloni.
- A referência só interessa até o artigo existir no Moloni. Alterá-la, ou alterar o prefixo, mais tarde faz com que a venda seguinte crie um artigo novo no catálogo; o antigo fica no Moloni.
Categoria. Os artigos são criados em Pretix > nome do evento, uma árvore de categorias que
o plugin cria quando é preciso, para o catálogo ficar organizado por evento. Um artigo que já exista
fica na categoria onde está.
Tipo e unidade. Das definições Tipo de artigo e Unidade. O separador Faturação PT do produto tem um campo Tipo (Moloni) para criar esse produto como outra coisa (Produto, Serviço, Outro ou Impostos/taxas).
Eventos que partilham uma empresa no Moloni não partilham artigos por omissão, porque os ids dos produtos do pretix são únicos em toda a instalação. Se der a mesma referência e o mesmo prefixo a dois produtos de eventos diferentes, são faturados como um só artigo do catálogo; cabe-lhe evitá-lo, ou tirar partido disso.
IVA¶
Cada linha segue o IVA que o pretix efetivamente cobrou:
- Linha com IVA — enviada com a Taxa de IVA configurada. Se essa taxa não for a que o pretix
cobrou, a emissão pára com
Divergência de IVA: …antes de criar o que quer que seja no Moloni. Caso contrário, o documento teria um valor diferente do que o comprador pagou. - Linha a 0% — enviada sem IVA, com o Motivo de isenção. O Moloni exige um, por isso uma encomenda com linhas a 0% e sem motivo de isenção definido pára com um erro explícito.
Preços unitários no PDF
O Moloni guarda os preços unitários com 5 casas decimais e imprime o preço unitário com IVA a partir deles. Um preço com IVA de 35,00 € a 23% sai por isso como 34,99999, na melhor das hipóteses, porque 35 / 1,23 não acaba. A incidência, o IVA e o total estão certos (28,46 + 6,54 = 35,00, a mesma divisão que a fatura do próprio pretix mostra). Só preços cujo valor sem IVA são cêntimos inteiros ("preço inclui IVA" desligado no pretix) saem limpos.
Clientes¶
Um comprador com NIF é associado a um cliente existente no Moloni quando há exatamente um com esse
NIF. Se houver vários, a emissão pára (O Moloni tem N clientes com o NIF X. Junte-os no Moloni e
tente novamente.). Caso contrário, é criado um cliente a partir da morada de faturação da
encomenda. Compradores sem NIF partilham um cliente consumidor final (999999990), associado pelo
nome.
Um cliente reutilizado nunca é alterado. Quando a morada da encomenda difere da que o Moloni tem na ficha, o documento é emitido com uma morada alternativa, para o PDF mostrar a morada que o comprador deu nesta encomenda. Os países são procurados no Moloni pelo código ISO.
Proteção contra duplicados e novas tentativas¶
O Moloni não tem nenhum campo em que recuse duplicados, por isso um pedido que expirou pode ou não
ter criado um documento. Por isso o plugin pergunta primeiro ao Moloni: antes de cada tentativa
procura um documento fechado com a referência da encomenda (pretix-<evento>-<código da
encomenda>, guardada no campo Nossa referência do Moloni) e, se existir, associa-o à encomenda em
vez de emitir outro.
É isso que torna as novas tentativas seguras. Uma falha de rede (timeout, Moloni inacessível) é repetida automaticamente, até três vezes com uns minutos de intervalo; entretanto a linha diz nova tentativa automática dentro de alguns minutos, e desistiu ao fim de várias tentativas se todas falharem. Carregar em Tentar novamente à mão passa pela mesma procura.
Uma recusa (dados inválidos, divergência de IVA, ligação expirada) nunca é repetida automaticamente: corrija a causa e carregue em Tentar novamente.
Notas de crédito¶
Construídas a partir das linhas do documento original e associadas a ele, creditando-o na totalidade. Usam a Série de notas de crédito.
Documentos e números¶
O número mostrado no pretix (por exemplo FR M2026/20, NC M2026/6) é lido do Moloni logo depois
da emissão: o código SAF-T do tipo de documento, o nome da série e o número.