Se você já usa n8n para automatizar fluxos — inscrições, disparos de email, notificações de WhatsApp — provavelmente tem pelo menos um caso onde seria útil gerar uma imagem personalizada para cada usuário ou participante, sem processo manual.
Este tutorial mostra como fazer isso do zero: criar um card personalizado via API da Vecsy dentro de um fluxo n8n e compartilhar a imagem gerada. O exemplo usa o cenário de inscrição em evento, mas a lógica se aplica a certificados, cards de boas-vindas, postagens de redes sociais e qualquer outro caso onde você precisa de imagem + dado de usuário.
O que você vai precisar
- Conta na Vecsy com acesso à API (acesse em Automation → API dentro da sua conta)
- Um template criado e em estado Ready na Vecsy, com os campos dinâmicos definidos
- n8n rodando — self-hosted ou via n8n Cloud
- Um token de API da Vecsy
Visão geral do fluxo
O fluxo que vamos construir tem três etapas:
- Trigger — um webhook recebe os dados do participante (nome, foto, e-mail)
- Gerar o card — um nó HTTP Request chama a API da Vecsy e recebe a URL da imagem
- Compartilhar — um nó de email ou mensageria envia a imagem para o participante
Passo 1 — Configure o template na Vecsy
Antes de qualquer coisa, o template precisa estar pronto. No editor da Vecsy, crie um template com os campos dinâmicos que vão variar por participante. No nosso exemplo:
name — nome do participante (campo de texto)photo — foto do participante (campo de imagem)
Anote o UUID do template — você vai precisar dele na chamada de API. Ele aparece na URL do template ou na seção de API dentro da plataforma.
Passo 2 — Crie o Webhook Trigger no n8n
No n8n, crie um novo workflow e adicione o nó Webhook como trigger.
Configure assim:
- HTTP Method: POST
- Path:
/inscricao (ou qualquer nome que faça sentido para o seu fluxo) - Response Mode: Respond with another node (se quiser retornar algo para quem chamou) ou Last node
Ative o webhook e copie a URL gerada. Ela terá o formato:
https://seu-n8n.com/webhook/inscricao
Essa URL é o ponto de entrada do fluxo. No seu site ou plataforma de inscrição, configure para enviar um POST com os dados do participante ao concluir o cadastro.
Exemplo de payload esperado:
json
{
"name": "Ana Souza",
"photo": "https://exemplo.com/fotos/ana.jpg",
"email": "ana@exemplo.com"
}
Passo 3 — Chame a API da Vecsy com HTTP Request
Adicione um nó HTTP Request após o webhook.
Configure os campos:
CampoValorMethodPOSTURLhttps://www.vecsy.co/api/generate-imageAuthenticationHeader AuthHeader nameAuthorizationHeader valueBearer SEU_TOKEN_AQUIBody Content TypeJSON
No corpo da requisição, mapeie os valores dinâmicos vindos do webhook:
json
{
"template_uuid": "18cc03b9-68c9-4aaf-ad74-17c8c76e0827",
"file_format": "png",
"name": "{{ $json.name }}",
"photo": "{{ $json.photo }}"
}
Substitua template_uuid pelo UUID do seu template e os nomes dos campos (name, photo) pelos campos que você configurou no editor da Vecsy.
Resposta esperada da API:
json
{
"url": "https://…",
"key": "uploads/api/generate-image/…",
"format": "png"
}
O campo url contém o link temporário para download da imagem gerada. Use esse valor nos próximos nós do fluxo.
Atenção: o link retornado é temporário. Se o seu fluxo precisar armazenar a imagem por mais tempo, faça o download e salve em um storage próprio (S3, Google Drive, etc.) antes de prosseguir.
Passo 4 — Compartilhe a imagem
Com a URL da imagem em mãos, o próximo passo é enviar para o participante. Aqui vão as duas abordagens mais comuns.
Opção A — Envio por e-mail
Adicione o nó Send Email (ou Gmail, se preferir) e configure:
- To:
{{ $('Webhook').item.json.email }} - Subject:
Seu card está pronto, {{ $('Webhook').item.json.name }}! - Body (HTML):
html
<p>Olá, {{ $('Webhook').item.json.name }}!</p>
<p>Seu card foi gerado. Clique no link abaixo para baixar:</p>
<p><a href="{{ $json.url }}">Baixar meu card</a></p>
<img src="{{ $json.url }}" alt="Seu card" style="max-width: 600px;" />
Opção B — Envio por WhatsApp (via Evolution API ou Twilio)
Se o seu fluxo inclui WhatsApp, adicione outro nó HTTP Request apontando para a sua instância de WhatsApp e passe a URL da imagem como mídia:
json
{
"number": "{{ $('Webhook').item.json.phone }}",
"mediaUrl": "{{ $json.url }}",
"caption": "Aqui está o seu card, {{ $('Webhook').item.json.name }}! 🎉"
}
Tratamento de erros
A API da Vecsy retorna erros padronizados em JSON. Os mais comuns que você pode encontrar:
- 401 — Token inválido ou ausente. Verifique se o header
Authorization está correto. - 400 — Algum campo dinâmico do template está faltando ou com formato inválido. Confira se todos os campos do template estão sendo enviados na requisição.
- 404 — O template não foi encontrado ou não está em estado Ready. Verifique o UUID e o status do template na Vecsy.
Para lidar com isso no n8n, adicione um nó IF após o HTTP Request verificando o status code:
- Se
{{ $json.url }} existe → siga para o envio - Se não → dispare um alerta para o time ou registre o erro num log
Resultado final do fluxo
[Webhook] → [HTTP Request: Vecsy API] → [IF: sucesso?]
↓ sim
[Send Email / WhatsApp]
↓ não
[Log de erro / Alerta]
Com esse fluxo, cada nova inscrição gera automaticamente um card personalizado e entrega para o participante sem nenhuma intervenção manual — independente do volume.
Próximos passos
Com a integração básica funcionando, algumas extensões naturais:
- Armazenar a imagem em Google Drive ou S3 antes de enviar, para ter um histórico
- Disparar em outros momentos — conclusão de curso, confirmação de presença, aniversário do usuário
- Adicionar aprovação humana — inserir um nó de espera para revisar o card antes do envio automático
Para qualquer um desses casos, a estrutura base é a mesma: trigger → chamada à API da Vecsy → ação com a URL retornada.
Quer testar a integração? Acesse a documentação completa da API ou fale com o time da Vecsy para configurar seu acesso. Solicite acesso à API →
