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

1. Criar o cenário no Make e ligá-lo à 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. 3No Make, o webhook fica a conhecer os campos da venda: type, test, e em data o produto, o cliente (buyer), os valores (amount) e o pagamento (payment).

2. Deixar passar só as vendas pagas

1. 1Clica na ligação a seguir ao webhook e escolhe Set up a filter.
2. 2Primeira condição: type, Text operators: Equal to, sale.paid. A Shelf envia sale.paid nas vendas pagas e lead.created nos produtos gratuitos, que não levam fatura.
3. 3Clica em Add AND rule. Segunda condição: data → amount → total, Numeric operators: Greater than, 0. Uma venda com cupão de 100% chega com total 0.00. Clica em Save.

3. Primeiro teste: uma fatura em modo de testes

1. 1Clica no + à direita do filtro, pesquisa HTTP e escolhe Make a request. Preenche: URL https://www.vendus.pt/ws/v1.1/documents, Method POST, um cabeçalho com Name Authorization e Value Bearer A_TUA_CHAVE (a palavra Bearer, um espaço e a tua chave), Body type Raw e Content type JSON (application/json).
2. 2Em 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. Troca ID_DO_METODO pelo id do método de cartão.
3. 3Só para este teste, troca o {{1.data.buyer.nif}} pelo teu próprio NIF: o evento de teste da Shelf traz o NIF de exemplo 123456789, que a Vendus recusa. Depois do teste, volta a pôr o campo.
4. 4Clica em Run once no Make e, na Shelf, outra vez em Enviar evento de teste. Na Vendus aparece um documento de teste, sem validade fiscal (é o "mode": "tests").

{
  "type": "FR",
  "mode": "tests",
  "external_reference": "{{1.data.order_id}}",
  "client": {
    "name": "{{1.data.buyer.name}}",
    "fiscal_id": "{{1.data.buyer.nif}}",
    "email": "{{1.data.buyer.email}}",
    "send_email": "yes"
  },
  "items": [
    {
      "reference": "{{1.data.product.id}}",
      "title": "{{1.data.product.title}}",
      "qty": 1,
      "gross_price": "{{1.data.amount.original}}",
      "discount_amount": "{{1.data.amount.discount}}",
      "type_id": "S",
      "tax_id": "NOR"
    }
  ],
  "payments": [
    {
      "id": "ID_DO_METODO",
      "amount": "{{1.data.amount.total}}"
    }
  ]
}

O artigo vai com o preço antes do cupão (data.amount.original) e o desconto do cupão (data.amount.discount), por isso a fatura mostra, por exemplo, 15,00 − 1,50 = 13,50. O pagamento é o que o cliente pagou (data.amount.total). Sem cupão, o desconto vem a 0.00.

4. Vendas sem NIF

1. 1A Vendus pede que não se envie o cliente sem NIF (e nunca com 999999990). Entre o filtro e o módulo HTTP, adiciona um Router (em Flow Control) com duas saídas.
2. 2Na ligação da primeira saída, Set up a filter: data → buyer → nif, Basic operators: Exists. Liga aqui o módulo HTTP do passo 3.
3. 3Na segunda saída, o mesmo campo com Basic operators: Does not exist. Adiciona outro módulo HTTP igual, mas apaga do corpo o bloco client (de "client" até à chaveta que o fecha, com a vírgula a seguir): a fatura fica para consumidor final.

5. O método certo em cada fatura (opcional)

O método de pagamento chega em data.payment.method: card (cartão, incluindo Apple Pay e Google Pay), mb_way (MB WAY) ou revolut_pay (Revolut Pay, se o ligares). A Vendus quer o id do método da tua conta, por isso faz a correspondência no lugar do ID_DO_METODO, com os teus ids:

{{switch(1.data.payment.method; mb_way; ID_MBWAY; ID_CARTAO)}}

Se for MB WAY, usa o id de MB WAY da Vendus; em todos os outros casos, o de cartão. Se preferires, usa sempre o mesmo id: é o mais simples.

6. Passar a sério

1. 1No filtro do passo 2, 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 módulos HTTP, troca "tests" por "normal" e confirma que o NIF voltou a ser {{1.data.buyer.nif}}.
3. 3Liga o cenário no interruptor em baixo, com Immediately as data arrives. A partir daqui, cada venda paga emite a fatura-recibo na Vendus.

1. 1No Zapier, cria um Zap novo com o gatilho Webhooks by Zapier → Catch Hook e copia o URL (começa por https://hooks.zapier.com/hooks/catch/).
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. No Zapier, clica em Test trigger para ver a venda de exemplo.
3. 3Adiciona 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%.
4. 4Adiciona a ação Webhooks by Zapier → Custom Request: Method POST, URL https://www.vendus.pt/ws/v1.1/documents, e em Headers duas linhas: Authorization com Bearer A_TUA_CHAVE, e Content-Type com application/json.
5. 5Em Data, cola o corpo abaixo. Apaga cada {{…}} e, no mesmo sítio, insere o campo com o mesmo nome do passo Catch Hook (por exemplo {{data.buyer.name}} é Data Buyer Name). Troca ID_DO_METODO pelo id do método de cartão.
6. 6Só para o teste, escreve o teu próprio NIF no lugar do campo do NIF (a Vendus recusa o NIF de exemplo 123456789) e testa o passo: na Vendus aparece um documento de teste, sem validade fiscal.

{
  "type": "FR",
  "mode": "tests",
  "external_reference": "{{data.order_id}}",
  "client": {
    "name": "{{data.buyer.name}}",
    "fiscal_id": "{{data.buyer.nif}}",
    "email": "{{data.buyer.email}}",
    "send_email": "yes"
  },
  "items": [
    {
      "reference": "{{data.product.id}}",
      "title": "{{data.product.title}}",
      "qty": 1,
      "gross_price": "{{data.amount.original}}",
      "discount_amount": "{{data.amount.discount}}",
      "type_id": "S",
      "tax_id": "NOR"
    }
  ],
  "payments": [
    {
      "id": "ID_DO_METODO",
      "amount": "{{data.amount.total}}"
    }
  ]
}

Vendas sem NIF e passar a sério (Zapier)

1. 1Para as vendas sem NIF, a Vendus quer o pedido sem o bloco client. Usa Paths by Zapier com dois caminhos (Data Buyer Nif Exists / Does not exist) e, no segundo, o mesmo pedido sem o bloco client.
2. 2No filtro, junta uma terceira condição: Test Does not exist. Assim, o botão de teste da Shelf nunca emite uma fatura verdadeira.
3. 3Volta a pôr o campo do NIF, troca "tests" por "normal" e publica o Zap.

1. 1No n8n, cria um workflow com o nó Webhook: HTTP Method POST. Copia o Production URL.
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://www.vendus.pt/ws/v1.1/documents, Send Headers com Authorization = Bearer A_TUA_CHAVE, Send Body com Body Content Type JSON e Using JSON. Cola o corpo abaixo com o campo em modo Expression e troca ID_DO_METODO pelo id do método de cartão.
5. 5Só para o teste, troca a expressão do NIF pelo teu próprio NIF (a Vendus recusa o NIF de exemplo 123456789). Na Vendus aparece um documento de teste.

{
  "type": "FR",
  "mode": "tests",
  "external_reference": "{{ $json.body.data.order_id }}",
  "client": {
    "name": "{{ $json.body.data.buyer.name }}",
    "fiscal_id": "{{ $json.body.data.buyer.nif }}",
    "email": "{{ $json.body.data.buyer.email }}",
    "send_email": "yes"
  },
  "items": [
    {
      "reference": "{{ $json.body.data.product.id }}",
      "title": "{{ $json.body.data.product.title }}",
      "qty": 1,
      "gross_price": "{{ $json.body.data.amount.original }}",
      "discount_amount": "{{ $json.body.data.amount.discount }}",
      "type_id": "S",
      "tax_id": "NOR"
    }
  ],
  "payments": [
    {
      "id": "ID_DO_METODO",
      "amount": "{{ $json.body.data.amount.total }}"
    }
  ]
}

Vendas sem NIF e passar a sério (n8n)

1. 1Para as vendas sem NIF, junta antes do pedido outro nó If ({{ $json.body.data.buyer.nif }} is not empty) e, na saída false, um segundo HTTP Request igual, sem o bloco client.
2. 2No 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.
3. 3Volta a pôr a expressão do NIF, troca "tests" por "normal" e ativa 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. 2Emite o documento: POST https://www.vendus.pt/ws/v1.1/documents com o cabeçalho Authorization: Bearer A_TUA_CHAVE e o corpo do separador Make, com os valores da venda. Sem NIF, envia o pedido sem o bloco client.
3. 3Testa com "mode": "tests" (um documento sem validade fiscal) e passa a "normal" quando estiver certo. O external_reference leva o data.order_id.
4. 4O mesmo evento pode, raramente, chegar duas vezes: guarda o data.order_id de cada venda já faturada e ignora repetidos.