Assinaturas por TAG

Posicione assinaturas e rubricas automaticamente marcando o PDF com tags textuais.

Em vez de definir coordenadas X/Y manualmente em signatures[].positions[], você marca o próprio PDF com tags textuais (#assinatura, #rubrica, {{ASSINA-CLIENTE}}...) e a ForSign localiza essas tags durante o processamento, plotando a assinatura exatamente onde elas aparecem.

String customizável

Qualquer texto. Múltiplas tags separadas por |.

Busca em todas as páginas

Varre o PDF inteiro — não precisa indicar página.

Múltiplas ocorrências

Cada match recebe uma assinatura/rubrica.

Texto extraível

Só funciona com PDFs cujo texto é selecionável.

Exclusivo via API. A funcionalidade de tags não está disponível no painel web — só configurável no payload de Criar operação.

Quando usar

Você gera PDFs dinamicamente (template engine, mail merge) e prefere marcar a posição no template do que calcular coordenadas.
O documento muda de tamanho/layout entre operações e coordenadas absolutas não servem.
Você quer suportar múltiplas páginas sem enumerar manualmente.

Como funciona

Prepare o PDF com as tags onde a assinatura/rubrica deve aparecer. Pode ser texto literal: #assinatura, #rubrica, ou qualquer string que você definir.
No payload da operação, marque o membro com:
- hasSignatureTag: true + signPositionTag: "#assinatura"
- hasRubricTag: true + rubricTag: "#rubrica" (opcional)
Após criar, a ForSign processa as tags em background: abre cada arquivo do membro, varre página a página e cria as posições de assinatura correspondentes com coordenadas em percentual da página.

Comportamento detalhado

Varre todas as páginas do PDF — sem precisar indicar página.
Cada ocorrência da tag gera uma posição. Repetir #assinatura 5x no PDF produz 5 assinaturas.
Múltiplas tags num mesmo campo: separe com |. signPositionTag: "#assinaCliente|#rubricaCliente" busca as duas.
Sanitização: converte para UPPER, normaliza espaços (incluindo \r, \n, \t) em um único espaço, e faz Trim(). Resultado:
- case-insensitive — #assinatura e #ASSINATURA casam.
- Tolera espaços extras dentro da tag.
- Não tolera quebras de linha no meio da tag — se o PDF quebra #assina
  - linha + tura, não casa. Coloque a tag inteira em uma linha só.
Validação de caracteres (em workflows): permite apenas letras, números, hífen e underscore. Use prefixos como #assina-cliente (válido), evite símbolos como { } @ em alguns contextos.

Exemplo de payload

{
  "name": "Contrato com tags",
  "files": [
    { "id": "d25058de-259a-4543-98f0-e1c4fb52ba0e", "description": "contrato.pdf" }
  ],
  "members": [
    {
      "name": "Bryan Silveira",
      "email": "[email protected]",
      "phone": "55119854324",
      "role": "Comprador",
      "orderPosition": 1,
      "notificationChannel": "Email",
      "doubleAuthentication": false,
      "observer": false,
      "signatureType": "UserChoice",

      "hasSignatureTag": true,
      "signPositionTag": "#assinaCliente",
      "hasRubricTag": true,
      "rubricTag": "#rubricaCliente",

      "signatures": [
        {
          "documentId": "d25058de-259a-4543-98f0-e1c4fb52ba0e",
          "printSignature": true,
          "positions": []
        }
      ]
    }
  ],
  "language": "pt-BR",
  "order": false
}

Combinando tag + coordenadas

Você pode usar ambos. Se passar positions[] E hasSignatureTag: true, a ForSign plota nas duas formas — útil quando você quer uma assinatura visual fixa (capa, coordenada) + várias rubricas por tag (corpo do documento).

Comportamento esperado

Cenário	Resultado
Tag presente no PDF	Assinatura/rubrica plotada no local da tag (cada ocorrência).
Tag não presente	Nenhuma assinatura/rubrica gerada — sem erro, sem assinatura visual.
Múltiplas tags via `\|`	Cada tag é buscada separadamente; todas as ocorrências geram posição.
Tag em duas linhas (quebra)	Não casa — a busca de texto não atravessa quebras de linha.
`hasSignatureTag` + `positions[]`	Ambos são aplicados, somando assinaturas.
Mesma posição duplicada	Deduplicada por `(página, X, Y)` — não cria duas assinaturas idênticas.

Tag vs `positions[]` — quando usar cada

Critério	Tag (`signPositionTag`)	Coordenadas (`positions[]`)
PDFs gerados dinamicamente	Ideal	Trabalhoso (precisa recalcular)
Layout fixo, conhecido	Funciona, mas é overkill	Ideal
PDFs escaneados sem OCR	Não funciona	Funciona
Múltiplas rubricas em páginas variáveis	Ideal	Custoso
Performance (operação enorme, 100+ páginas)	Mais lento (extrai texto)	Mais rápido
Controle pixel-perfect	Não — segue onde a tag estiver	Sim

Limitações

PDF precisa ter texto extraível. Imagens com texto não funcionam. Documentos escaneados sem OCR não terão as tags localizadas — rode OCR antes.
Tags muito curtas (1-2 caracteres) podem gerar falsos positivos em qualquer ocorrência da string no documento. Use prefixos inequívocos como #assina-cliente, ##rubrica, {{TAG_X}}.
Quebra de linha invalida a tag. Se o template engine quebrar #assinatura em duas linhas, o match falha. Use estilos nowrap ou tags curtas.
Operação é processada em background. Após POST /operation, a varredura de tags acontece de forma assíncrona — pode haver alguns segundos até as posições aparecerem.

On this page