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

1. 1No Make, cria um cenário novo e adiciona o módulo Webhooks → Custom webhook. Clica em Add, dá-lhe um nome (por exemplo «Vendas Shelf») e copia o URL que o Make mostra (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. 4Clica no + à direita do filtro, pesquisa HTTP e escolhe Make a request. URL: https://NOME.app.invoicexpress.com/invoice_receipts.json?api_key=A_TUA_CHAVE (com o nome da tua conta e a tua chave), Method POST, Body type Raw, Content type JSON (application/json). Liga Parse response.
5. 5Em Request content, cola o corpo abaixo. Os {{1.data…}} são os campos do webhook (o 1 é o número do módulo): se ficarem como texto simples, clica em cada um e escolhe o campo na lista.
6. 6Clica em Run once e, na Shelf, outra vez em Enviar evento de teste. No InvoiceXpress aparece uma fatura-recibo em rascunho: confirma o cliente, o valor e o IVA, e apaga o rascunho.

{
  "invoice": {
    "date": "{{formatDate(now; DD/MM/YYYY)}}",
    "due_date": "{{formatDate(now; DD/MM/YYYY)}}",
    "reference": "{{1.data.order_id}}",
    "client": {
      "name": "{{1.data.buyer.name}}",
      "code": "{{ifempty(1.data.buyer.nif; 1.data.buyer.email)}}",
      "email": "{{1.data.buyer.email}}",
      "fiscal_id": "{{1.data.buyer.nif}}",
      "country": "Portugal"
    },
    "items": [
      {
        "name": "{{1.data.product.title}}",
        "description": "Venda na Shelf",
        "unit_price": "{{1.data.amount.total}}",
        "quantity": "1",
        "tax": {
          "name": "IVA0"
        }
      }
    ],
    "tax_exemption": "M10"
  }
}

O code identifica o cliente no InvoiceXpress: o NIF, ou o email quando não há NIF. Se já existir um cliente com esse código, o InvoiceXpress usa a ficha dele.

Passar a sério (Make)

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. 2Para a fatura ficar emitida, junta outro módulo HTTP → Make a request depois do primeiro: Method PUT, URL https://NOME.app.invoicexpress.com/invoice_receipts/{{2.data.invoice_receipt.id}}/change-state.json?api_key=A_TUA_CHAVE (o 2 é o número do primeiro módulo HTTP; escolhe o id na lista), Body type Raw, JSON, e o corpo {"invoice": {"state": "finalized"}}.
3. 3Para o cliente receber a fatura por email (opcional), mais um módulo HTTP: Method PUT, URL https://NOME.app.invoicexpress.com/invoice_receipts/{{2.data.invoice_receipt.id}}/email-document.json?api_key=A_TUA_CHAVE e o corpo abaixo.
4. 4Liga o cenário no interruptor em baixo, com Immediately as data arrives. A partir daqui, cada venda paga emite a fatura-recibo.

{
  "message": {
    "client": {
      "email": "{{1.data.buyer.email}}",
      "save": "0"
    },
    "subject": "A tua fatura",
    "body": "Obrigado pela tua compra. Segue a fatura-recibo."
  }
}

1. 1No Zapier, cria um Zap novo e escolhe o gatilho Webhooks by Zapier → Catch Hook. Continua até o Zapier mostrar o URL do webhook (começa por https://hooks.zapier.com/hooks/catch/) e copia-o.
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. 3No Zapier, clica em Test trigger: aparece a venda de exemplo (Cliente Teste, NIF 123456789) com todos os campos para mapear.
4. 4Adiciona um passo Filter by Zapier: continua só se Type for exatamente sale.paid e se Data Amount Total for (Number) maior que 0. Assim ficam de fora os produtos gratuitos e as vendas com cupão de 100%.
5. 5Adiciona a ação InvoiceXpress → Create Invoice-Receipt, liga a tua conta InvoiceXpress e mapeia os campos (tabela abaixo). Escolhe a taxa de IVA ou o motivo de isenção que se aplica a ti.
6. 6Testa o passo: no InvoiceXpress aparece uma fatura-recibo em rascunho. Confirma o cliente, o valor e o IVA, e apaga o rascunho.

Passar a sério (Zapier)

1. 1No filtro, junta uma terceira condição: Test Does not exist. Assim, o botão de teste da Shelf nunca emite uma fatura verdadeira.
2. 2Adiciona InvoiceXpress → Finalize Invoice-Receipt para a fatura ficar emitida e, se quiseres, Sends Invoice by Email para o cliente a receber.
3. 3Publica o Zap.

1. 1No n8n, cria um workflow com o nó Webhook: HTTP Method POST. Copia o Production URL (o Test URL só funciona enquanto o n8n está à escuta).
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. Para o n8n receber o teste, clica antes em Listen for test event e usa, só para isso, o Test URL.
3. 3Junta 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.
4. 4Junta um nó HTTP Request: Method POST, URL https://NOME.app.invoicexpress.com/invoice_receipts.json?api_key=A_TUA_CHAVE, Send Body ligado, Body Content Type JSON, Using JSON, e cola o corpo abaixo com o campo em modo Expression.
5. 5Corre o teste: no InvoiceXpress aparece uma fatura-recibo em rascunho. Confirma-a e apaga o rascunho.

{
  "invoice": {
    "date": "{{ $now.toFormat('dd/MM/yyyy') }}",
    "due_date": "{{ $now.toFormat('dd/MM/yyyy') }}",
    "reference": "{{ $json.body.data.order_id }}",
    "client": {
      "name": "{{ $json.body.data.buyer.name }}",
      "code": "{{ $json.body.data.buyer.nif || $json.body.data.buyer.email }}",
      "email": "{{ $json.body.data.buyer.email }}",
      "fiscal_id": "{{ $json.body.data.buyer.nif }}",
      "country": "Portugal"
    },
    "items": [
      {
        "name": "{{ $json.body.data.product.title }}",
        "description": "Venda na Shelf",
        "unit_price": "{{ $json.body.data.amount.total }}",
        "quantity": "1",
        "tax": {
          "name": "IVA0"
        }
      }
    ],
    "tax_exemption": "M10"
  }
}

Passar a sério (n8n)

1. 1No nó If, junta uma terceira condição: {{ $json.body.test }} (Boolean) is not true. Assim, o botão de teste da Shelf nunca emite uma fatura verdadeira.
2. 2Junta outro nó HTTP Request: Method PUT, URL https://NOME.app.invoicexpress.com/invoice_receipts/{{ $json.invoice_receipt.id }}/change-state.json?api_key=A_TUA_CHAVE, corpo JSON {"invoice": {"state": "finalized"}}.
3. 3Ativa 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. 2Cria a fatura-recibo: POST https://NOME.app.invoicexpress.com/invoice_receipts.json?api_key=… com o corpo do separador Make (a raiz é invoice, as datas em dd/mm/aaaa, o unit_price sem IVA). Fica em rascunho; a resposta traz invoice_receipt.id.
3. 3Emite-a: PUT …/invoice_receipts/ID/change-state.json com {"invoice": {"state": "finalized"}}. Para testes, usa "deleted" em vez de "finalized": o rascunho é apagado.
4. 4Para a enviar ao cliente: PUT …/invoice_receipts/ID/email-document.json com {"message": {"client": {"email": "…", "save": "0"}}}.
5. 5O mesmo evento pode, raramente, chegar duas vezes: guarda o data.order_id de cada venda já faturada e ignora repetidos.