Guias
Adicionar automaticamente campos de assinatura com etiquetas âncora: Posicionamento de campos baseado em texto
Escrito por

Se alguma vez posicionou campos de assinatura calculando coordenadas x/y num PDF, sabe o quão enfadonho isso se torna em escala. Altere o esquema do documento e todas as coordenadas deixam de funcionar. Adicione uma segunda página e terá de recalcular os desvios para metade dos seus campos.
As anchor tags resolvem isto. Incorpore marcadores de texto como {{SIGN_HERE}} ou {{DATE}} diretamente no seu modelo de PDF, e o Firma.dev deteta-os automaticamente e coloca os tipos de campo corretos nesses locais. Os marcadores são removidos do documento final, para que os signatários nunca os vejam. Uma única chamada de API, sem cálculos matemáticos de coordenadas.
As anchor tags foram lançadas na v1.11.0 e suportam todos os tipos de campo, regras de correspondência flexíveis e até 100 etiquetas por pedido de assinatura.
Início Rápido
A forma mais rápida de colocar as anchor tags a funcionar: incorpore um marcador no seu PDF e, em seguida, crie um pedido de assinatura com um array anchor_tags.
Passo 1: Adicione o texto {{SIGN_HERE}} num local do seu PDF onde pretende que o campo de assinatura apareça. Pode fazê-lo em qualquer ferramenta que utilize para gerar os seus documentos, quer seja um modelo do Word, uma biblioteca de PDF ou um serviço de geração de documentos.
Passo 2: Crie um pedido de assinatura baseado em documentos com a definição de anchor tag:
O Firma.dev analisa o PDF em busca de {{SIGN_HERE}}, posiciona um campo de assinatura nesse local, atribui-o ao destinatário e remove o texto do marcador do documento. É apenas isso.
Tenha em atenção que as anchor tags só funcionam com a criação de pedidos de assinatura baseados em documentos, e não baseados em modelos. Envia o PDF não processado e deixa o sistema de âncoras tratar do posicionamento dos campos.
Tipos de Campos Suportados
As anchor tags suportam todos os tipos de campos disponíveis no Firma.dev. Defina a propriedade type em cada anchor tag para um destes valores:
signature para campos de assinatura, initials para campos de rubrica, text para introdução de texto numa única linha, textarea para introdução de texto em várias linhas, date para campos de data, checkbox para caixas de seleção, radio para grupos de botões de opção, dropdown para menus pendentes de seleção, url para campos de URL, stamp para campos de carimbo e file para campos de carregamento de ficheiros.
Cada tipo apresenta o widget de campo adequado na experiência de assinatura. Uma anchor tag date cria um seletor de data, um dropdown cria um menu de seleção e assim sucessivamente.
Opções de Correspondência e Posicionamento
O comportamento predefinido de correspondência funciona para a maioria dos casos, mas pode ajustar com precisão a forma como o Firma.dev encontra e posiciona campos criados por âncoras.
Sensibilidade a maiúsculas e minúsculas: Defina case_sensitive como true ou false (a predefinição é false). Com a correspondência insensível a maiúsculas e minúsculas, tanto {{sign_here}} como {{SIGN_HERE}} correspondem.
Correspondência de palavras inteiras: Defina whole_word como true para evitar correspondências parciais. Se a sua cadeia de âncora for SIGN e whole_word for false, também corresponderia a SIGNATURE ou COSIGN. Defini-lo como true garante que apenas corresponde à palavra exata.
Visar ocorrências específicas: Se o seu PDF contiver a mesma cadeia de âncora várias vezes, pode visar ocorrências específicas com occurrence. Defina como 1 para a primeira ocorrência, 2 para a segunda e assim por diante. Omita ou defina match_all como true para colocar campos em todas as ocorrências.
Posicionamento com desvio: Ajuste com precisão onde o campo fica situado em relação ao texto da âncora usando offset_x e offset_y. Pode especificar os desvios em percentagens (relativas às dimensões da página) ou em píxeis. Isto é útil quando pretende que o campo seja posicionado ligeiramente abaixo ou à direita do marcador, em vez de diretamente por cima dele.
Gestão suave de âncoras em falta: Defina ignore_if_not_present como true se a cadeia de âncora puder não existir em todos os documentos. Sem isto, uma âncora em falta devolve um erro. Com esta opção ativada, o Firma.dev ignora discretamente essa etiqueta e processa o restante.
Configuração Avançada
Aqui está um exemplo mais completo que combina múltiplas anchor tags com diferentes tipos de campo, dimensões personalizadas e desvios de posicionamento:
Alguns aspetos a ter em conta neste exemplo: a etiqueta {{EMPLOYEE_INITIALS}} utiliza match_all: true, portanto, se o PDF tiver marcadores de rubricas nas páginas 1, 5 e 12, as três recebem campos. A caixa de seleção {{BENEFITS_OPT_IN}} utiliza ignore_if_not_present: true porque nem todas as versões do contrato de trabalho incluem essa secção. E o offset_y: 2 no campo de assinatura desloca-o ligeiramente para baixo em relação à posição do texto da âncora.
As dimensões (width e height) seguem o mesmo sistema de coordenadas baseado em percentagens utilizado por campos posicionados manualmente. As anchor tags e os campos manuais funcionam em conjunto, pelo que pode usar âncoras para a maioria dos seus campos e continuar a adicionar campos baseados em coordenadas manuais no mesmo pedido para casos específicos.
Migração a Partir de Outras Plataformas
Se estiver a migrar a partir de outro fornecedor de assinatura eletrónica que utilize o posicionamento de campos baseado em texto, os conceitos mapeiam-se diretamente. A sintaxe da cadeia de âncora e os nomes das propriedades diferem, mas o mecanismo subjacente é o mesmo: incorporar um marcador, definir o tipo de campo, deixar a API tratar do posicionamento.
A partir do DocuSign Auto-Place: O DocuSign utiliza anchorString, anchorXOffset, anchorYOffset e tipos específicos de separador como signHereTabs. No Firma.dev, isto passa a ser anchor_string, offset_x, offset_y e o campo universal type. O anchorIgnoreIfNotPresent do DocuSign corresponde a ignore_if_not_present. O anchorCaseSensitive do DocuSign corresponde a case_sensitive. A principal diferença estrutural é que o Firma.dev utiliza um único array anchor_tags com uma propriedade type, em vez de arrays separados para cada tipo de separador.
A partir do Yousign Smart Anchors: O conceito de "smart anchors" do Yousign com deteção do tipo de campo traduz-se diretamente. As opções de correspondência e posicionamento são comparáveis, embora os nomes das propriedades utilizem a convenção snake_case do Firma.dev.
O limite é de 100 anchor tags por pedido de assinatura, o que cobre confortavelmente a maioria dos fluxos de trabalho de documentos. Se estiver a processar documentos que necessitem genuinamente de mais de 100 campos, considere dividir por vários pedidos de assinatura ou utilizar uma combinação de anchor tags e definições de campos baseadas em modelos.
Referência da API
O array anchor_tags está disponível no endpoint de criação de pedidos de assinatura baseados em documentos (POST /signing-requests). Cada item no array é um objeto AnchorTag com cerca de 25 propriedades configuráveis.
As propriedades principais:
anchor_string (obrigatório) é o marcador de texto a procurar no PDF. type (obrigatório) é o tipo de campo a criar. recipient_id atribui o campo a um destinatário específico usando o respetivo ID ou ID temporário. required marca o campo como obrigatório ou opcional. offset_x e offset_y ajustam a posição do campo relativamente à localização da âncora. width e height definem dimensões personalizadas para o campo. case_sensitive controla se a correspondência é sensível a maiúsculas e minúsculas. whole_word impede correspondências parciais de cadeias. occurrence visa uma instância específica quando a âncora aparece várias vezes. match_all coloca campos em todas as ocorrências. ignore_if_not_present ignora a etiqueta sem erro se o texto da âncora não for encontrado no documento.
Para o esquema completo com todas as propriedades e os respetivos tipos, consulte o registo de alterações da API da v1.11.0.
Passos Seguintes
As anchor tags combinam bem com a geração programática de documentos. Se a sua aplicação gera contratos, acordos de confidencialidade (NDAs) ou documentos de integração a partir de modelos, pode incorporar cadeias de âncora durante a geração e deixar que o Firma.dev trate do posicionamento dos campos automaticamente em cada pedido.
Comece a utilizar o Firma.dev gratuitamente, sem necessidade de cartão de crédito.
Artigos relacionados
A nossa plataforma foi projetada para capacitar empresas de todos os tamanhos a trabalhar de forma mais inteligente e alcançar seus objetivos com confiança.







