Integração Moloni: faturas automáticas a cada venda na Shelf

1. A ligação OAuth à Moloni

1. 1No Make, cria um cenário novo e adiciona o módulo HTTP → Make an OAuth 2.0 request. Em Connection, clica em Create a connection.
2. 2Flow type Authorization Code. Authorize URI https://www.moloni.pt/ac/root/oauth/, Token URI https://api.moloni.pt/v1/grant/, Client ID o teu Developer ID e Client Secret o teu Client Secret.
3. 3Clica em Save: abre-se a Moloni, entras e autorizas. O Make guarda a ligação e renova o acesso sozinho (o acesso dura 1 hora e a renovação 14 dias).

2. Os ids da tua conta

Com o mesmo módulo, faz uma vez cada um destes pedidos (Method POST) e anota os ids da resposta. Os URLs levam ?json=true, para a Moloni aceitar o corpo em JSON (Body type Raw, JSON).

• https://api.moloni.pt/v1/companies/getAll/?json=true, sem corpo: o company_id da tua empresa.
• https://api.moloni.pt/v1/documentSets/getAll/?json=true com {"company_id": ID_DA_EMPRESA}: o document_set_id da série.
• https://api.moloni.pt/v1/paymentMethods/getAll/?json=true: o payment_method_id do cartão (e do MB WAY, se o tiveres).
• https://api.moloni.pt/v1/products/getAll/?json=true: o product_id do artigo para as vendas online.
• https://api.moloni.pt/v1/customers/getByVat/?json=true com {"company_id": ID_DA_EMPRESA, "vat": "999999990"}: o customer_id do consumidor final.

3. O cenário das vendas

1. 1Num cenário novo, começa com Webhooks → Custom webhook: clica em Add e copia o URL (começa por https://hook.).
2. 2Na Shelf, vai a Definições → Integrações → Webhooks, cola o URL e clica em Ligar webhook. Depois clica em Enviar evento de teste.
3. 3Clica na ligação a seguir ao webhook e escolhe Set up a filter. Primeira condição: type, Text operators: Equal to, sale.paid. Clica em Add AND rule; segunda condição: data → amount → total, Numeric operators: Greater than, 0. Assim ficam de fora os produtos gratuitos (lead.created) e as vendas com cupão de 100%.
4. 4Junta um Router com duas saídas. Na primeira, filtro data → buyer → nif Exists, e um módulo HTTP → Make an OAuth 2.0 request (módulo 3) para https://api.moloni.pt/v1/customers/getByVat/?json=true, Method POST, com {"company_id": ID_DA_EMPRESA, "vat": "{{1.data.buyer.nif}}"}. Na segunda saída não há pedido: a fatura vai para o consumidor final.
5. 5No fim de cada saída, um módulo HTTP → Make an OAuth 2.0 request para https://api.moloni.pt/v1/invoiceReceipts/insert/?json=true, Method POST, Body type Raw, JSON, com o corpo abaixo e os teus ids. Na saída sem NIF, troca o customer_id pelo id do consumidor final.
6. 6Clica em Run once e envia o evento de teste da Shelf. Na Moloni aparece um rascunho ("status": 0): confirma o cliente, o valor e o IVA, e apaga-o.

{
  "company_id": "ID_DA_EMPRESA",
  "date": "{{formatDate(now; YYYY-MM-DD)}}",
  "expiration_date": "{{formatDate(now; YYYY-MM-DD)}}",
  "document_set_id": "ID_DA_SERIE",
  "customer_id": "{{ifempty(3.data.customer_id; ID_CONSUMIDOR_FINAL)}}",
  "our_reference": "{{1.data.order_id}}",
  "products": [
    {
      "product_id": "ID_DO_ARTIGO",
      "name": "{{1.data.product.title}}",
      "qty": 1,
      "price": "{{1.data.amount.total}}",
      "exemption_reason": "M10"
    }
  ],
  "payments": [
    {
      "payment_method_id": "ID_DO_METODO",
      "date": "{{formatDate(now; YYYY-MM-DD)}}",
      "value": "{{1.data.amount.total}}"
    }
  ],
  "status": 0
}

Se o cliente com aquele NIF ainda não existir na Moloni, o getByVat não devolve nenhum id e a fatura vai para o consumidor final. Para criar a ficha do cliente nesses casos, junta um pedido a customers/insert: a Moloni pede vários campos (morada, país, idioma, prazo de pagamento), descritos na documentação da Moloni.

4. Passar a sério

1. 1No filtro, clica em Add AND rule e junta uma terceira condição: test, Basic operators: Does not exist. Assim, o botão de teste da Shelf nunca emite uma fatura verdadeira.
2. 2Nos dois pedidos invoiceReceipts/insert, troca "status": 0 por "status": 1: a fatura-recibo fica fechada (emitida).
3. 3Liga o cenário no interruptor em baixo, com Immediately as data arrives.

No Zapier, a app da Moloni trata de clientes e do envio de documentos, mas não cria faturas. E o pedido HTTP do Zapier não renova sozinho a autorização da Moloni, que dura 1 hora. Para a Moloni, usa o Make (é o primeiro separador e tem plano gratuito).

1. 1No n8n, cria uma credencial OAuth2 API: Grant Type Authorization Code, Authorization URL https://www.moloni.pt/ac/root/oauth/, Access Token URL https://api.moloni.pt/v1/grant/, o teu Developer ID e Client Secret. Na Moloni, usa como Redirect URI o OAuth Redirect URL que o n8n mostra.
2. 2Cria o workflow com o nó Webhook (POST), liga o Production URL na Shelf e junta o filtro: Junta um nó If com duas condições: {{ $json.body.type }} (String) is equal to sale.paid, e {{ $json.body.data.amount.total }} (Number) is greater than 0. Continua pela saída true.
3. 3Nos nós HTTP Request, escolhe Authentication Generic Credential Type → OAuth2 API e faz os mesmos pedidos do separador Make (customers/getByVat e invoiceReceipts/insert, com ?json=true), trocando {{1.data…}} por {{ $json.body.data… }}.
4. 4O primeiro teste vai com "status": 0 (rascunho). Para passar a sério: a condição test no filtro, "status": 1 e ativar o workflow.

1. 1Recebe o POST da Shelf num endereço https:// teu e responde 2xx em menos de 10 segundos. Confirma o cabeçalho Shelf-Signature (o código está em Webhooks da Shelf) e trata só os eventos com type igual a sale.paid, data.amount.total maior que 0 e sem test.
2. 2Autoriza a tua aplicação uma vez (https://www.moloni.pt/ac/root/oauth/?response_type=code&client_id=…&redirect_uri=…) e troca o código por tokens em GET https://api.moloni.pt/v1/grant/?grant_type=authorization_code&client_id=…&client_secret=…&redirect_uri=…&code=…. O acesso dura 1 hora; renova-o com grant_type=refresh_token antes de passarem 14 dias.
3. 3Cria a fatura-recibo: POST https://api.moloni.pt/v1/invoiceReceipts/insert/?access_token=…&json=true com o corpo do separador Make. status 0 é rascunho, 1 é fechada.
4. 4O mesmo evento pode, raramente, chegar duas vezes: guarda o data.order_id de cada venda já faturada e ignora repetidos.