Adicione Assinaturas Digitais a Qualquer Fluxo de Trabalho n8n com a Firma.dev

O n8n é o local onde muitas equipas já executam a lógica dos seus contratos: entra um formulário, um negócio avança de fase, chega uma data de renovação e um fluxo de trabalho (workflow) é ativado. A peça em falta é normalmente a própria assinatura. A Firma.dev disponibiliza agora um nó comunitário dedicado n8n-nodes-firma com 83 operações, um gatilho (trigger) que gere os seus próprios webhooks e uma ferramenta integrada para o Agente de IA do n8n, pelo que raramente precisará de ligar manualmente um nó de Pedido HTTP.

Como a Firma.dev fatura por envelope a 0,049 € (~5¢ USD) sem custos por utilizador e sem mínimos mensais, adapta-se especialmente bem ao envio automatizado. Quando um fluxo de trabalho envia cinquenta contratos de renovação durante a noite, paga por cinquenta envelopes, e não por um escalão para o qual cresceu. Essa é a diferença entre a automação que poupa dinheiro e a automação que, silenciosamente, aumenta a fatura.

Este artigo aborda quatro formas de ligar a Firma.dev ao n8n: o nó dedicado para enviar e gerir documentos, o nó de gatilho para reagir a contratos assinados, a Firma.dev como uma ferramenta para o Agente de IA e uma configuração manual de Webhook mais Pedido HTTP, caso prefira evitar completamente os nós comunitários.

Caminho 1: instalar o nó da Firma.dev

Esta é a forma mais rápida de colocar a Firma.dev a funcionar no n8n. O nó trata da autenticação, da formatação dos pedidos e da paginação por si, com campos de seleção em vez de JSON em bruto.

No editor de fluxos de trabalho, clique no + para adicionar um nó, pesquise por "Firma" e selecione Install em Community Nodes. O nó é instalado e colocado na sua área de trabalho num único passo. Se preferir instalar com antecedência, vá a Settings > Community Nodes, clique em Install e introduza n8n-nodes-firma. As instâncias auto-alojadas (self-hosted) também podem instalá-lo manualmente:

cd ~/.n8n/nodes && npm install n8n-nodes-firma

cd ~/.n8n/nodes && npm install n8n-nodes-firma

cd ~/.n8n/nodes && npm install n8n-nodes-firma

Reinicie o n8n após uma instalação manual.

Em seguida, configure as credenciais. Clique em Credentials na barra lateral, adicione uma nova e pesquise por Firma API. Irá precisar da sua chave de API em Workspace Settings > API e, opcionalmente, de um segredo de webhook em Workspace Settings > Webhooks, se planear validar eventos recebidos mais tarde. Deixe o campo Environment definido como Production.

O nó abrange 83 operações em recursos que incluem Signing Request, Template, Webhook, Workspace, Company, Domain e Email Template, pelo que a maioria dos fluxos de trabalho nunca precisará de sair dele. Um envio típico assemelha-se a isto:

1. Adicione um nó Firma e selecione a sua credencial da Firma API

2. Defina o Resource como Signing Request e a Operation como Create and Send

3. Defina o Document Source como Template e introduza o seu Template ID

4. Em Recipients, adicione o e-mail, primeiro nome, cargo e ordem do signatário utilizando expressões como {{ $json.signer_email }}

A resposta inclui o id do novo pedido de assinatura, que pode registar ou passar para as etapas seguintes. Para fluxos de aprovação, utilize a operação Create para guardar um rascunho, insira uma etapa de aprovação ou de espera e, em seguida, chame Send assim que for aprovado.

Algo que vale a pena assinalar antes de ligar isto a um fluxo de trabalho movimentado: as operações de escrita da Firma — Create, Create and Send, Send e Resend — não possuem uma chave de idempotência. Se um nó tentar novamente de forma automática após um tempo limite (timeout), poderá acabar por enviar o mesmo contrato duas vezes, sendo que ambas as cópias são legalmente vinculativas após assinadas. Desative a opção Retry On Fail nestas operações e gira as tentativas com a sua própria lógica, se precisar delas.

Caminho 2: reagir a documentos assinados com o nó Firma Trigger

O nó de gatilho (trigger) faz algo que um nó Webhook genérico não consegue: regista e desregista o webhook na Firma.dev automaticamente quando ativa ou desativa o fluxo de trabalho. Não há nenhum passo no painel de controlo para se lembrar e nada é deixado para trás se desativar um fluxo de trabalho.

Adicione um nó Firma Trigger a um novo fluxo de trabalho, selecione a sua credencial da Firma API e escolha quais os eventos a escutar em Events, tais como Signing Request Completed ou Signing Request Recipient Declined. Pode limitar o gatilho a um único ID de área de trabalho (workspace ID) se gerir várias. A ativação do fluxo de trabalho cria o webhook a apontar para a sua instância do n8n; a desativação remove-o, e os webhooks órfãos de execuções anteriores são detetados e reutilizados em vez de duplicados.

O gatilho abrange todos os 27 eventos de webhook da Firma.dev em pedidos de assinatura, destinatários, modelos, áreas de trabalho e domínios. Encaminhe-os com um nó Switch em {{ $json.type }}:

• signing_request.completed atualiza o seu CRM e inicia a disponibilização do serviço

• signing_request.recipient.declined notifica a equipa de vendas

• signing_request.expired reenvia ou move o negócio para perdido

Se adicionou um segredo de webhook à sua credencial, o gatilho valida o cabeçalho X-Firma-Signature com HMAC-SHA256 automaticamente, incluindo o cabeçalho de período de tolerância utilizado durante a rotação de segredos. Os pedidos que falhem na validação são rejeitados antes de chegarem à lógica do seu fluxo de trabalho. Para uma análise mais detalhada sobre como os eventos de webhook se mapeiam em áreas de trabalho multi-inquilino, consulte o guia de webhooks de área de trabalho.

Se a sua etapa seguinte for arquivar o documento finalizado automaticamente, o tutorial do Google Drive aborda exatamente essa construção de quatro etapas, desde o gatilho até ao carregamento, num guia dedicado.

A API de webhook da Firma.dev requer HTTPS. O n8n Cloud trata disso por si; as instâncias auto-alojadas necessitam de um proxy reverso com TLS, ou de um túnel como cloudflared tunnel --url http://localhost:5678 ou ngrok http 5678 durante o desenvolvimento. E os webhooks ainda precisam de ser ativados no painel de controlo da Firma.dev em Workspace Settings > Webhooks. O botão Test por webhook ignora esse interruptor geral, pelo que um teste bem-sucedido não garante que os eventos reais estejam a fluir.

Caminho 3: Firma.dev como uma ferramenta para o Agente de IA do n8n

O nó Firma também pode funcionar como uma ferramenta nativa para o nó do Agente de IA, sem necessidade de configuração HTTP personalizada. Num fluxo de trabalho de Agente de IA, adicione um nó Firma como entrada de ferramenta, selecione a sua credencial e escolha o recurso e a operação que deseja expor, como Signing Request > Create and Send.

Exponha mais do que uma operação se quiser que o agente tenha opções reais em vez de uma única ferramenta. Uma combinação comum é Template > List, para que o agente possa procurar o modelo correto por si próprio, juntamente com Signing Request > Create and Send para o enviar e Signing Request > Get para verificar o estado quando solicitado. O agente decide que ferramenta chamar com base na conversa, de modo que uma instrução como "enviar o NDA para jane@acme.com" é resolvida sem que tenha de escrever essa lógica manualmente.

Este caminho requer o n8n v1.47 ou posterior.

Configuração manual: Webhook mais Pedido HTTP

Se a sua equipa evita nós comunitários, ou se está numa versão do n8n anterior à existência dos mesmos, ainda pode ligar a Firma.dev diretamente à API. Esta é a mesma integração que a anterior, mas montada a partir dos nós genéricos do n8n em vez dos dedicados.

Para o envio, adicione um nó HTTP Request com uma credencial Header Auth chamada Firma API, cabeçalho Authorization, valor da sua chave de API, e aponte-o para o endpoint de criação e envio:

POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send

POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send

POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send

{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}

{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}

{
  "template_id": "{{ $json.template_id }}",
  "recipients": [
    {
      "first_name": "{{ $json.signer_first_name }}",
      "last_name": "{{ $json.signer_last_name }}",
      "email": "{{ $json.signer_email }}",
      "designation": "Signer",
      "order": 1
    }
  ]
}

Aplica-se o mesmo padrão de rascunho e posterior envio: POST /signing-requests para criar um rascunho, POST /signing-requests/{id}/send assim que estiver pronto para ser enviado.

Para reagir a documentos assinados, adicione um nó de gatilho Webhook, copie o seu URL de produção e cole-o no painel de controlo da Firma.dev em Settings > Webhooks, juntamente com os eventos que deseja. Encaminhe o payload com um nó Switch em {{ $json.body.type }} e obtenha o ficheiro assinado a partir de {{ $json.body.data.signing_request.signed_document_url }} para o arquivar no Google Drive, S3 ou Notion. Ao contrário do nó de gatilho, é responsável por registar e remover este webhook por si próprio quando um fluxo de trabalho for alterado.

Assinar dentro de outra aplicação

Se o seu fluxo terminar com o signatário a concluir o documento dentro do seu próprio produto, em vez de o fazer por e-mail, obtenha o signing_request_user_id do destinatário a partir da resposta da API e incorpore a interface de assinatura da Firma.dev:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Document Signing"
></iframe>

Tudo é executado em infraestrutura alojada na UE e produz um registo de auditoria completo, garantindo que a automação que constrói permanece juridicamente protegida.

📘 Leia o guia completo de integração do n8n
A configuração completa, incluindo cada campo de nó, detalhe de credencial e evento de webhook, encontra-se na documentação: https://docs.firma.dev/guides/n8n-integration

Começar

Pode ter o nó da Firma.dev instalado e o seu primeiro pedido de assinatura enviado no tempo que demora a criar uma única credencial. Comece a utilizar a Firma.dev gratuitamente, sem necessidade de cartão de crédito, e adicione assinaturas eletrónicas aos fluxos de trabalho que já executa.