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

O n8n é o local onde muitas equipas já executam a sua lógica de contratos: um formulário entra, um negócio avança de fase, chega uma data de renovação e um fluxo de trabalho é acionado. A peça em falta é normalmente a assinatura em si. Com o Firma.dev, basta arrastar um nó HTTP Request para qualquer fluxo de trabalho, guardar a sua chave de API uma vez e enviar assinaturas eletrónicas legalmente vinculativas sem sair do n8n.

Como o Firma.dev fatura por envelope a €0.049 (~5¢ USD), sem custos por utilizador e sem consumos 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 onde acabou por entrar. Essa é a diferença entre a automatização que poupa dinheiro e a automatização que discretamente aumenta a fatura.

Este artigo aborda três formas de ligar o Firma.dev ao n8n: o nó HTTP Request para envio, um acionador Webhook para reagir a documentos assinados e o Firma.dev como ferramenta para o AI Agent do n8n.

Caminho 1: enviar com o nó HTTP Request

Este é o caminho que a maioria dos fluxos de trabalho necessita. Guarda a sua chave de API do Firma.dev uma vez como credencial e, em seguida, qualquer nó HTTP Request em qualquer fluxo de trabalho pode reutilizá-la.

Primeiro, crie a credencial. No editor do n8n, abra Credentials, clique em Add Credential e escolha Header Auth. Dê o nome Firma API à credencial, defina o Name do cabeçalho como Authorization e cole a sua chave de API do Firma.dev no campo Value. O n8n encripta as credenciais com a chave da sua instância, pelo que referenciar a credencial mantém a sua chave fora do JSON do fluxo de trabalho exportado. Nunca cole a chave diretamente num campo de um nó.

Agora adicione um nó HTTP Request e aponte-o para o endpoint de criação e envio, que cria um pedido de assinatura a partir de um modelo e o envia numa única chamada:

• Method: POST

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

• Authentication: Generic Credential Type, Header Auth, utilizando a credencial Firma API

• Send Body: Ligado, JSON

O corpo extrai valores de nós anteriores utilizando expressões do n8n:

{
  "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
    }
  ]
}

Ligue esse nó ao que quer que impulsione o fluxo de trabalho. Um Form Trigger envia um contrato no momento em que um cliente o submete. Um Webhook Trigger aciona o pedido quando a sua aplicação reporta que um negócio mudou de fase. Um Schedule Trigger executa um lote noturno de renovações a partir de uma consulta à base de dados. A resposta inclui o id do novo pedido de assinatura, para que o possa registar, armazenar ou referenciar mais tarde.

Se precisar de um passo de revisão humana antes de enviar qualquer documento, crie um rascunho com POST /signing-requests, coloque um nó de aprovação (Approval) a meio do fluxo de trabalho e, em seguida, chame POST /signing-requests/{id}/send assim que o mesmo for aprovado.

Caminho 2: reagir a documentos assinados com um acionador Webhook

O envio é apenas metade do processo. A outra metade é fazer algo no momento em que um documento é assinado. Adicione um nó Webhook como acionador, defina o seu método para POST e copie o URL de produção. No painel de controlo do Firma.dev em Settings → Webhooks, adicione esse URL e subscreva os eventos pretendidos, começando por signing_request.completed.

De volta ao n8n, adicione um nó Switch após o acionador e encaminhe com base em {{ $json.body.type }}. Uma assinatura concluída pode atualizar o seu CRM e iniciar o aprovisionamento. Uma assinatura recusada pode notificar a equipa de vendas. Uma expirada pode reenviar o documento ou mover o negócio para perdido. O documento assinado encontra-se em {{ $json.body.data.signing_request.signed_document_url }}, pelo que pode enviá-lo diretamente para um nó do Google Drive, S3 ou Notion e arquivá-lo sem passos adicionais.

Caminho 3: Firma.dev como ferramenta para o AI Agent do n8n

Se utiliza o nó AI Agent, pode disponibilizar-lhe o Firma.dev como uma ferramenta que ele pode chamar e deixar que ele decida quando a deve enviar. Adicione um nó HTTP Request Tool como entrada de ferramenta, configure-o exatamente como no Caminho 1 e dê à ferramenta o nome send_signing_request. Forneça-lhe uma descrição que indique ao agente quando deve recorrer à mesma e defina um esquema de entrada com template_id, signer_email, signer_first_name e signer_last_name. O agente passará agora a enviar contratos diretamente a partir de uma instrução em linguagem natural. Associe-o a uma segunda ferramenta que aponte para GET /templates se pretender que o agente escolha o modelo correto por si próprio.

Assinatura dentro de outra aplicação

Se o seu fluxo terminar com o signatário a preencher o documento dentro da sua própria aplicação em vez de o fazer por e-mail, extraia o signing_request_user_id do destinatário a partir da resposta da API e incorpore a interface de assinatura do 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 funciona numa infraestrutura alojada na UE e gera um registo de auditoria completo, para que a automatização que criar permaneça juridicamente protegida.

📘 Leia o guia completo de integração do n8n
A configuração completa, incluindo todos os campos de nós, detalhes das credenciais e eventos de webhook, encontra-se na documentação: https://docs.firma.dev/guides/n8n-integration

Começar

Pode colocar o primeiro caminho a funcionar no tempo que demora a criar uma credencial e um nó. Comece a utilizar o Firma.dev gratuitamente, sem necessidade de cartão de crédito, e adicione assinaturas eletrónicas aos fluxos de trabalho que já executa.