Ir para o conteúdo

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

  1. Na área de programador do Moloni, crie uma aplicação. Anote o seu ID de programador (client_id) e o Segredo do cliente.
  2. 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/.
  3. 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.

A secção Moloni depois de ligada: estado da ligação, redirect URI, ID de programador e segredo do cliente, e as listas da empresa à forma de pagamento

  1. Preencha o ID de programador (client_id) e o Segredo do cliente.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.

    As listas da secção Moloni, das séries de documentos ao prazo de vencimento

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

    O fim da secção Moloni na página de um evento: unidade, limite da referência, prazo de vencimento e a tabela de formas de pagamento, com o botão de guardar

  8. 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:

A secção Moloni de um evento com "Ligado através das definições do organizador" e o botão "Ligar este evento em separado"

  • 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. VIP nesse campo dá a referência de catálogo pretix-VIP. Dois produtos do mesmo evento não podem ter a mesma referência, e as formas item-<número> e fee-… estão reservadas.

    O separador Faturação PT da página de um produto do pretix, com os campos Referência do produto e Tipo (Moloni)

  • 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.