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

Atualizado a 21 de outubro de 2026

Um webhook envia cada venda paga da tua loja para um endereço teu, em segundos: produto, cliente (nome, email e NIF quando o indica), valor, cupão e método de pagamento. Com o Make (tem plano gratuito) e a API da Vendus, isso chega para emitir a fatura-recibo (FR) a cada venda. Não precisas de saber programar: é copiar, colar e mapear campos.

1. Gerar a chave da API na Vendus

1. 1No backoffice da Vendus, no canto inferior esquerdo, abre Configuração → Integrações → API Vendus.
2. 2Confirma que Acesso API está ligado e copia o conteúdo do campo API key. A chave pertence a um utilizador da Vendus: as faturas emitidas pela API ficam em nome dele.

2. Criar o cenário no Make e copiar o URL

1. 1No Make, cria um cenário novo e adiciona o módulo Webhooks → Custom webhook.
2. 2Clica em Add, dá-lhe um nome (por exemplo «Vendas Shelf») e copia o URL que o Make mostra (começa por https://hook.).

3. Ligar à Shelf

1. 1No painel, vai a Definições → Integrações → Webhooks, cola o URL e clica em Ligar webhook.
2. 2Clica em Enviar evento de teste.
3. 3No Make, o webhook mostra que recebeu os dados: uma venda de exemplo (Cliente Teste, NIF 123456789) com todos os campos para mapear.

4. Deixar passar só as vendas pagas

1. 1Clica na ligação a seguir ao webhook e escolhe Set up a filter: continua só se type for igual a sale.paid, se test não existir e se data.amount.total for maior que 0. Uma venda com cupão de 100% chega com total 0.00 e coupon_full: true; o evento de teste traz test: true.

5. Saber o ID do método de pagamento na Vendus

A fatura-recibo regista o pagamento com o ID de um método de pagamento da tua conta Vendus. Só precisas de o ver uma vez:

1. 1Adiciona, só por agora, um módulo HTTP → Make a request: URL https://www.vendus.pt/ws/v1.1/documents/paymentmethods, método GET e um cabeçalho Authorization com o valor Bearer A_TUA_CHAVE.
2. 2Corre-o com Run once e, na resposta, copia o id do método que queres usar (o de cartão ou de pagamento online, por exemplo). Depois apaga este módulo.

6. Emitir a fatura-recibo na Vendus

1. 1A seguir ao filtro, adiciona um Router com duas rotas: Com NIF (filtro: data.buyer.nif existe) e Sem NIF (filtro: data.buyer.nif não existe). A Vendus pede que não se envie o cliente sem NIF, e nunca com 999999990.
2. 2Em cada rota, adiciona HTTP → Make a request: URL https://www.vendus.pt/ws/v1.1/documents, método POST, cabeçalho Authorization com Bearer A_TUA_CHAVE, Body type Raw e Content type JSON (application/json).
3. 3Cola o corpo abaixo. No Make, os campos do webhook aparecem como {{1.data…}} (o 1 é o número do módulo do webhook): escolhe-os na lista para os inserir. Troca ID_DO_METODO pelo ID do passo 5. Na rota Sem NIF, apaga o bloco client.
4. 4O 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. Se quiseres o código do cupão na fatura, junta ao artigo "text": "Cupão {{1.data.amount.coupon}}" (deixa-o só numa rota para vendas com cupão, para não aparecer «Cupão» vazio).
5. 5Faz o primeiro teste com "mode": "tests", o modo de testes da API da Vendus, e confirma o documento na Vendus. Quando estiver certo, muda para "normal" e liga o cenário com Scheduling: Immediately.

{
  "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 evento

• sale.paid: uma venda paga. O data.amount.total é o que o cliente pagou, com IVA e com os order bumps incluídos (cada order bump vem também em data.bumps, com título e valor). Uma venda com cupão de 100% chega com total 0.00 e coupon_full: true.
• lead.created (alguém recebe um produto gratuito) também chega ao webhook: o filtro do passo 4 deixa-o de fora.