Guias
Adicionar automaticamente campos de assinatura com etiquetas âncora: Posicionamento de campos baseado em texto
Se alguma vez posicionou campos de assinatura calculando coordenadas x/y num PDF, sabe o quão tedioso se torna em grande escala. Mude o layout do documento e cada coordenada desmorona. Adicione uma segunda página e está a recalcular offsets para metade dos seus campos.
As etiquetas de âncora resolvem isto. Incorpore marcadores de texto como {{SIGN_HERE}} ou {{DATE}} diretamente no seu modelo PDF, e a Firma.dev deteta automaticamente e coloca os tipos de campos corretos nessas localizações. Os marcadores são removidos do documento final, por isso os signatários nunca os veem. Uma chamada de API, sem matemática de coordenadas.
As etiquetas de âncora foram lançadas na versão 1.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 maneira mais rápida de colocar as etiquetas de âncora a funcionar: insira um marcador no seu PDF, depois crie um pedido de assinatura com um array anchor_tags.
Passo 1: Adicione o texto {{SIGN_HERE}} em algum lugar do seu PDF onde deseja que o campo de assinatura apareça. Pode fazer isto em qualquer ferramenta que gera os seus documentos, seja um modelo Word, uma biblioteca PDF ou um serviço de geração de documentos.
Passo 2: Crie um pedido de assinatura baseado no documento com a definição da etiqueta de âncora:
A Firma.dev examina o PDF para {{SIGN_HERE}}, coloca um campo de assinatura nesse local, atribui-o ao destinatário, e remove o texto do marcador do documento. É isso.
Note que as etiquetas de âncora só funcionam com a criação de pedidos de assinatura baseados em documentos, não com base em modelos. Está a enviar o PDF bruto e permitindo que o sistema de âncoras controle a colocação de campos.
Tipos de Campo Suportados
As etiquetas de âncora suportam todos os tipos de campo disponíveis no Firma.dev. Defina a propriedade type em cada etiqueta de âncora para um destes valores:
signature para campos de assinatura, initials para campos iniciais, text para entrada de texto de linha única, textarea para entrada de texto de várias linhas, date para campos de data, checkbox para caixas de seleção, radio para grupos de botões de rádio, dropdown para seleções suspensas, url para campos de URL, stamp para campos de selo, e file para campos de carregamento de ficheiros.
Cada tipo renderiza o widget de campo apropriado na experiência de assinatura. Uma etiqueta de âncora date cria um seletor de data, uma dropdown cria um menu de seleção, e assim por diante.
Opções de Correspondência e Posicionamento
O comportamento de correspondência padrão funciona para a maioria dos casos, mas pode ajustar como a Firma.dev encontra e posiciona campos criados por âncora.
Sensibilidade à caixa: Defina case_sensitive para true ou false (o padrão é false). Com a correspondência insensível à caixa, {{sign_here}} e {{SIGN_HERE}} correspondem ambos.
Correspondência de palavra inteira: Defina whole_word para true para impedir correspondências parciais. Se a sua string de âncora for SIGN e whole_word for false, também corresponderia a SIGNATURE ou COSIGN. Definindo para true garante que corresponde apenas à palavra exata.
Alvo de ocorrências específicas: Se o seu PDF contiver a mesma string de âncora várias vezes, pode direcionar específicas com occurrence. Defina para 1 para a primeira correspondência, 2 para a segunda, e assim por diante. Omita ou defina match_all para true para colocar campos em todas as ocorrências.
Posicionamento de offset: Ajuste onde o campo se situa em relação ao texto de âncora usando offset_x e offset_y. Pode especificar offsets em percentagens (relativas às dimensões da página) ou pixels. Isto é útil quando deseja que o campo esteja posicionado ligeiramente abaixo ou à direita do marcador, em vez de diretamente sobre ele.
Manuseio gracioso de âncoras ausentes: Defina ignore_if_not_present para true se a string de âncora pode não existir em cada documento. Sem isto, uma âncora ausente retorna um erro. Com isto ativado, a Firma.dev ignora silenciosamente essa etiqueta e processa o restante.
Configuração Avançada
Aqui está um exemplo mais completo que combina várias etiquetas de âncora com diferentes tipos de campo, dimensões personalizadas, e offsets de posicionamento:
Algumas coisas a notar neste exemplo. A etiqueta {{EMPLOYEE_INITIALS}} usa match_all: true, então se o PDF tiver marcadores de iniciais nas páginas 1, 5 e 12, todos os três recebem campos. A caixa de seleção {{BENEFITS_OPT_IN}} usa ignore_if_not_present: true porque nem todas as versões do acordo de trabalho incluem essa seção. E o offset_y: 2 no campo de assinatura desloca-o ligeiramente para baixo da posição do texto âncora.
As dimensões (width e height) seguem o mesmo sistema de coordenadas baseado em percentagens usado por campos posicionados manualmente. As etiquetas de âncora e os campos manuais funcionam juntos, então pode usar âncoras para a maioria dos seus campos e ainda adicionar campos manuais baseados em coordenadas no mesmo pedido para casos específicos.
Migração de Outras Plataformas
Se estiver a migrar de outro fornecedor de assinatura eletrónica que utiliza posicionamento de campo baseado em texto, os conceitos mapeiam-se diretamente. A sintaxe da string de âncora e os nomes das propriedades diferem, mas o mecanismo subjacente é o mesmo: insira um marcador, defina o tipo de campo, deixe a API tratar do posicionamento.
De DocuSign Auto-Place: A DocuSign usa anchorString, anchorXOffset, anchorYOffset, e tipos específicos de aba como signHereTabs. Na Firma.dev, isso torna-se anchor_string, offset_x, offset_y, e o campo universal type. O anchorIgnoreIfNotPresent da DocuSign mapeia para ignore_if_not_present. O anchorCaseSensitive da DocuSign mapeia para case_sensitive. A principal diferença estrutural é que a Firma.dev usa um único array anchor_tags com uma propriedade type, em vez de arrays separados para cada tipo de aba.
De Yousign Smart Anchors: O conceito de "âncoras inteligentes" da Yousign com deteção de tipo de campo traduz-se diretamente. As opções de correspondência e posicionamento são comparáveis, embora os nomes das propriedades usem a convenção snake_case da Firma.dev.
O limite é de 100 etiquetas de âncora por pedido de assinatura, o que cobre a maioria dos fluxos de documentos confortavelmente. Se estiver a processar documentos que genuinamente precisam de mais de 100 campos, considere dividi-los em vários pedidos de assinatura ou usar uma combinação de etiquetas de âncora e definições de campo baseadas em modelos.
Referência de API
O array anchor_tags está disponível no endpoint de criação de pedido de assinatura baseado em documento (POST /signing-requests). Cada item no array é um objeto AnchorTag com aproximadamente 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 seu 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 em relação à localização da âncora. width e height definem dimensões personalizadas de campo. case_sensitive controla se a correspondência é sensível à caixa. whole_word impede correspondências parciais de strings. occurrence direciona para 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 âncora não for encontrado no documento.
Para o esquema completo com todas as propriedades e seus tipos, veja o changelog da API para a versão 1.11.0.
Próximos Passos
As etiquetas de âncora combinam bem com a geração programática de documentos. Se a sua aplicação gera contratos, NDA's ou documentos de integração a partir de modelos, pode incorporar strings de âncora durante a geração e deixar a Firma.dev tratar da colocação de campos automaticamente em cada pedido.
Comece a usar a 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.
