Como Enviar um PDF para Assinatura Sem Criar um Modelo

A maioria das APIs de assinatura eletrónica obriga-o a criar um modelo antes de poder enviar qualquer coisa para assinatura. Carrega o seu PDF, define os seus campos, guarda-o como modelo e, em seguida, cria um pedido de assinatura a partir desse modelo.

Esse fluxo faz sentido quando está a enviar o mesmo documento repetidamente. Contratos de trabalho, NDAs, acordos com fornecedores. Qualquer coisa que vá usar mais do que algumas vezes merece um modelo.

Mas, por vezes, só precisa de enviar um documento pontual. Uma proposta personalizada. Um acordo jurídico que é diferente de cada vez. Uma aprovação interna rápida que nunca irá repetir. Criar um modelo para um documento que só vai usar uma vez acrescenta atrito e sobrecarrega o seu espaço de trabalho.

Firma.dev agora suporta pedidos de assinatura pontuais. Pode carregar um PDF diretamente, definir os seus destinatários e campos no próprio pedido e enviá-lo para assinatura sem nunca criar um modelo. Este artigo explica como funciona.

Quando os Modelos Fazem Sentido (E Quando Não Fazem)

Os modelos são a escolha certa quando está a enviar repetidamente a mesma estrutura de documento. Se tem uma carta de oferta que é enviada a cada novo colaborador, ou um NDA que todos os fornecedores assinam, ou uma fatura mensal que tem sempre os mesmos campos nos mesmos lugares, os modelos poupam-lhe tempo. Configura-os uma vez e reutiliza-os para sempre.

Mas os modelos tornam-se um encargo quando o documento é único. Uma proposta personalizada com preços que mudam para cada potencial cliente. Um acordo de transação que é negociado e revisto antes da assinatura. Um formulário interno de aprovação que é diferente consoante a situação.

Nestes casos, criar um modelo apenas para o usar uma vez é trabalho desnecessário. Acaba com um espaço de trabalho cheio de modelos de utilização única a que nunca voltará a tocar.

O Fluxo de Trabalho de Pedido de Assinatura Pontual

O fluxo pontual ignora por completo a etapa do modelo. Eis como funciona:

1. Pegue no seu PDF e codifique-o em base64

2. Defina os seus destinatários no próprio pedido (nome, email, se são signatários ou em cópia, ordem de assinatura se aplicável)

3. Defina os seus campos no próprio pedido (caixas de assinatura, campos de texto, datas, caixas de verificação, o que precisar) com as respetivas posições na página

4. Chame o endpoint de criação ou o endpoint atómico de criação e envio

5. Feito. Não é necessário modelo.

O pedido de assinatura funciona exatamente como um baseado em modelo. Os seus destinatários são notificados, assinam e você recebe o documento concluído e o registo de auditoria. A única diferença é que não teve de criar primeiro um modelo.

Exemplo: Enviar uma Proposta Personalizada

Imagine que é uma empresa SaaS a enviar uma proposta de preços personalizada a um potencial cliente. A proposta é um PDF de uma página com o nome da empresa dele, os preços que negociou e uma linha de assinatura.

Eis como fica a chamada à API ao usar o endpoint atómico de criação e envio:

{
  "name": "Proposal - Acme Corp",
  "document": "JVBERi0xLjQK...",
  "recipients": [
    {
      "id": "temp_signer_1",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@acmecorp.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "recipient_id": "temp_signer_1",
      "type": "signature",
      "page": 1,
      "x": 100,
      "y": 650,
      "width": 200,
      "height": 50
    },
    {
      "recipient_id": "temp_signer_1",
      "type": "date",
      "page": 1,
      "x": 320,
      "y": 650,
      "width": 100,
      "height": 30
    }
  ],
  "settings": {
    "send_signing_email": true
  }
}

{
  "name": "Proposal - Acme Corp",
  "document": "JVBERi0xLjQK...",
  "recipients": [
    {
      "id": "temp_signer_1",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@acmecorp.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "recipient_id": "temp_signer_1",
      "type": "signature",
      "page": 1,
      "x": 100,
      "y": 650,
      "width": 200,
      "height": 50
    },
    {
      "recipient_id": "temp_signer_1",
      "type": "date",
      "page": 1,
      "x": 320,
      "y": 650,
      "width": 100,
      "height": 30
    }
  ],
  "settings": {
    "send_signing_email": true
  }
}

{
  "name": "Proposal - Acme Corp",
  "document": "JVBERi0xLjQK...",
  "recipients": [
    {
      "id": "temp_signer_1",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@acmecorp.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "recipient_id": "temp_signer_1",
      "type": "signature",
      "page": 1,
      "x": 100,
      "y": 650,
      "width": 200,
      "height": 50
    },
    {
      "recipient_id": "temp_signer_1",
      "type": "date",
      "page": 1,
      "x": 320,
      "y": 650,
      "width": 100,
      "height": 30
    }
  ],
  "settings": {
    "send_signing_email": true
  }
}

O campo document contém o seu PDF codificado em base64. O array recipients define quem tem de assinar. O array fields coloca uma caixa de assinatura e um campo de data na página 1 nas coordenadas que especificar.

Uma chamada à API e a Jane recebe um email a pedir-lhe que assine. Não é necessária a criação de um modelo.

Repare no padrão temp_signer_1 no ID do destinatário. Quando está a criar destinatários e campos no mesmo pedido, usa IDs temporários para os ligar entre si. A API converte-os em UUIDs reais após a criação.

Definir Campos Sem o Editor de Modelos

Quando usa modelos, pode colocar campos visualmente usando o editor de modelos incorporado. Com pedidos pontuais, está a definir as posições dos campos na própria chamada à API, o que significa que precisa de conhecer as coordenadas.

Cada campo precisa de:

• page – que página do PDF (indexada a partir de 1)

• x e y – posição a partir do canto inferior esquerdo da página, em pontos

• width e height – dimensões do campo, em pontos

Se não tiver a certeza de onde colocar os campos, abra o seu PDF num visualizador que mostre coordenadas (a maioria mostra), ou simplesmente estime e ajuste. A experiência de assinatura é suficientemente tolerante para que não precise de um posicionamento perfeito ao píxel.

Tipos de campos disponíveis para pedidos pontuais:

• signature – captura de assinatura

• initials – captura de iniciais

• text – entrada de texto livre

• date – seletor de data

• checkbox – caixa de verificação sim/não

Também pode marcar campos de texto como read_only se quiser pré-preencher um valor que o signatário pode ver mas não editar. Isto é útil para coisas como valores de contrato, números de referência ou quaisquer dados que já tenham sido acordados.

Quando Usar Modelos em Vez Disso

Os pedidos pontuais são ótimos para documentos ad hoc, mas os modelos continuam a ser a melhor escolha quando está a enviar a mesma estrutura de documento mais do que duas ou três vezes.

Os modelos permitem-lhe usar o editor de modelos incorporado para colocar campos visualmente em vez de calcular coordenadas. Também funcionam com o editor de pedidos de assinatura incorporado, que permite a utilizadores sem conhecimentos técnicos preencher os detalhes dos destinatários e enviar documentos sem tocar na API.

Regra geral: se vai enviar um documento mais do que duas ou três vezes, crie um modelo. Se for algo de utilização única, salte o modelo e use um pedido pontual.

Em Resumo

Os pedidos de assinatura pontuais removem o atrito dos documentos ad hoc. Não tem de criar modelos que nunca irá reutilizar, nem de sobrecarregar o seu espaço de trabalho com estruturas de documentos de utilização única.

Os modelos continuam disponíveis quando precisa deles. Ambos os fluxos de trabalho usam os mesmos tipos de campos, as mesmas opções de destinatários e os mesmos registos de acompanhamento e auditoria. Está apenas a escolher o caminho que se adequa à situação.

Se quiser experimentar, o endpoint de criação de pedidos de assinatura tem documentação completa sobre o fluxo pontual. Ou use o endpoint atómico para criar e enviar numa única chamada.

Comece a usar a Firma.dev gratuitamente – não é necessário cartão de crédito.