Como Enviar um PDF para Assinatura Sem Criar um Modelo

A maioria das APIs de assinatura eletrónica obriga a criar um modelo antes de poder enviar qualquer coisa para assinatura. Carrega o teu PDF, define os teus campos, guarda-o como um modelo e, depois, cria uma solicitação de assinatura a partir desse modelo.

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

Mas às vezes só precisas de enviar um documento único. Uma proposta personalizada. Um acordo legal que é diferente a cada vez. Uma aprovação interna rápida que nunca vais repetir. Criar um modelo para um documento que só vais usar uma vez adiciona atrito e enche de desordem o teu espaço de trabalho.

A Firma.dev agora suporta solicitações de assinatura pontuais. Podes carregar um PDF diretamente, definir os teus destinatários e campos imediatamente e enviá-lo para assinatura sem jamais criar um modelo. Este post explica como funciona.

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

Os modelos são a escolha certa quando estás a enviar a mesma estrutura de documento repetidamente. Se tens uma carta de oferta que vai para cada novo contratado, ou um NDA que cada fornecedor assina, ou uma fatura mensal que sempre tem os mesmos campos nos mesmos lugares, os modelos poupam-te tempo. Configuras uma vez e reutilizas para sempre.

Mas os modelos tornam-se sobrecarga quando o documento é único. Uma proposta personalizada com preços que mudam para cada prospecto. Um acordo de resolução que é negociado e revisto antes da assinatura. Um formulário de aprovação interno que é diferente dependendo da situação.

Para estes casos, criar um modelo apenas para usá-lo uma vez é trabalho em vão. Acabas com um espaço de trabalho cheio de modelos de uso único que nunca mais tocarás.

O Workflow de Solicitação de Assinatura Única

O fluxo de trabalho único pula completamente a etapa do modelo. Veja como ele parece:

1. Pega no teu PDF e codifica-o em base64

2. Define os teus destinatários imediatamente (nome, e-mail, se são assinantes ou em cópia, ordem de assinatura se aplicável)

3. Define os teus campos imediatamente (caixas de assinatura, campos de texto, datas, caixas de seleção, o que precisares) com suas posições na página

4. Chama o endpoint de criação ou o endpoint atómico de criar e enviar

5. Feito. Nenhum modelo necessário.

A solicitação de assinatura funciona exatamente como uma baseada em modelo. Os teus destinatários são notificados, eles assinam, tu obténs o documento concluído e o trilho de auditoria. A única diferença é que não precisaste criar um modelo primeiro.

Exemplo: Enviando uma Proposta Personalizada

Vamos supor que és uma empresa SaaS enviando uma proposta de preços personalizada a um prospecto. A proposta é um PDF de uma página com o nome da empresa deles, o preço que negociaste e uma linha de assinatura.

Veja como a chamada de API se parece usando o endpoint atómico de criar e enviar:

{
  "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 teu PDF codificado em base64. O array recipients define quem precisa assinar. O array fields coloca uma caixa de assinatura e um campo de data na página 1 nas coordenadas que especificares.

Uma chamada de API, e Jane recebe um e-mail pedindo sua assinatura. Nenhuma criação de modelo é necessária.

Nota o padrão temp_signer_1 no ID de destinatário. Quando estás a criar destinatários e campos na mesma solicitação, usas IDs temporários para ligá-los. A API resolve estes para UUIDs reais após a criação.

Definindo Campos Sem o Editor de Modelos

Quando usas modelos, podes colocar campos visualmente usando o editor de modelos embutido. Com solicitações únicas, estás a definir as posições dos campos na própria chamada de API, o que significa que precisas saber as coordenadas.

Cada campo precisa de:

• page – qual página do PDF (indexado 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 tens certeza de onde colocar os campos, abre o teu PDF num visualizador que mostra as coordenadas (a maioria o faz), ou só estima e ajusta. A experiência de assinatura é tolerante o suficiente para que não precises de um posicionamento exato de pixels.

Tipos de campo disponíveis para solicitações únicas:

• signature – captura de assinatura

• initials – captura de iniciais

• text – entrada de texto livre

• date – seletor de data

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

Também podes marcar campos de texto como read_only se quiseres pré-preencher um valor que o assinante pode ver, mas não pode editar. Isso é ú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

As solicitações únicas são ótimas para documentos ad hoc, mas os modelos ainda são a melhor escolha quando estás a enviar a mesma estrutura de documento mais de algumas vezes.

Os modelos permitem utilizar o editor de modelos embutido para colocar campos visualmente em vez de calcular coordenadas. Eles também funcionam com o editor de solicitações de assinatura embutido, que permite a utilizadores não técnicos preencher detalhes de destinatários e enviar documentos sem mexer na API.

A regra prática: se vais enviar um documento mais de duas ou três vezes, cria um modelo. Se é uma coisa única, pula o modelo e usa uma solicitação única.

Conclusão

As solicitações de assinatura únicas removem a fricção de documentos ad hoc. Não precisas criar modelos que nunca mais irás reutilizar, e não precisas de encher o teu espaço de trabalho com estruturas de documento de uma só vez.

Os modelos ainda estão lá quando precisas deles. Ambos os workflows usam os mesmos tipos de campo, as mesmas opções de destinatário e os mesmos rastreamento e trilhas de auditoria. Estás apenas a escolher o caminho que melhor se adapta à situação.

Se queres experimentar, o endpoint de criação de solicitação de assinatura tem documentação completa sobre o fluxo de trabalho único. Ou usa o endpoint atómico para criar e enviar numa única chamada.

Começa a usar a Firma.dev de graça – não é necessário cartão de crédito.