Posicionar campos por texto âncora

Em vez de calcular x e y de cada campo, você pode marcar no próprio documento onde a assinatura deve cair - com um texto - e pedir à SuperSign que encontre esse texto e devolva as coordenadas. Isso é posicionamento por âncora.

Disponibilidade. A busca por âncora é liberada por ambiente. Onde ainda não estiver liberada, a operação responde 503 ANCHOR_SEARCH_UNAVAILABLE ("busca por âncora indisponível neste ambiente"); posicione os campos por coordenadas, como sempre. Trate esse 503 na integração.

A operação só lê o documento: ela não grava campos e não altera o PDF. Você recebe as coordenadas e decide o que fazer com elas - normalmente, enviá-las em PUT .../fields, como em qualquer outro posicionamento. O contrato dos campos não muda.

Quando usar

O documento é gerado pelo seu sistema (contrato, proposta, termo) e o lugar da assinatura muda conforme o conteúdo: mais cláusulas empurram a assinatura para baixo ou para outra página.

Você quer manter um modelo de documento sem precisar remedir coordenadas a cada alteração de layout.

Marcadores recomendados

Use um texto curto e único, que não apareça por acaso no documento. Uma convenção comum (a mesma recomendada pela DocuSign para "auto-place") é um marcador entre barras invertidas, um por papel:

\s1\ - assinatura do 1º signatário; \s2\ - do 2º;

\i1\ - rubrica do 1º signatário.

Escreva o marcador na cor do fundo (branco sobre branco), com fonte pequena: ele continua sendo texto para a busca, mas não aparece para quem lê. O campo de assinatura é desenhado por cima no lugar indicado.

Evite palavras comuns como âncora (Assinatura, Nome): elas costumam aparecer mais de uma vez, e cada ocorrência vira uma posição.

Fluxo

Envie o documento (POST /v4/api/envelopes/{envelopeId}/documents e upload).

Aguarde o documento ficar pronto (GET .../documents mostra o status). Antes disso a busca responde 409 DOCUMENT_NOT_READY.

Chame POST .../documents/{documentId}/anchors:find com as âncoras.

Monte os campos com page, x e y de cada ocorrência devolvida e o tamanho que quiser, e envie em PUT .../documents/{documentId}/fields.

Para modelos, o fluxo é o mesmo com POST /v4/api/templates/{templateId}/documents/{documentId}/anchors:find (escopo templates:read) e PUT dos campos do modelo.

Requisição

Escopo exigido: envelopes:read. Por ser só leitura, a operação não exige Idempotency-Key; repetir a chamada é seguro.

Cada âncora aceita:

Campo	Padrão	Descrição
`key`	-	Identificador seu (até 100 caracteres, único na chamada). Volta em cada ocorrência achada
`text`	-	Texto a procurar (1 a 200 caracteres). Espaços repetidos contam como um só
`occurrence`	`"all"`	`"all"` (todas), `"first"` (a primeira) ou um número N (a N-ésima no documento inteiro, na ordem das páginas)
`caseSensitive`	`false`	Diferenciar maiúsculas de minúsculas
`matchWholeWord`	`false`	Só aceitar o texto como palavra inteira (sem letra ou número colado antes ou depois)
`offset`	`{ "x": 0, "y": 0 }`	Deslocamento em pontos somado ao canto superior esquerdo do texto achado (`x` para a direita, `y` para baixo; negativos valem)

Até 20 âncoras por chamada.

Resposta `200`

{
  "pages": [
    { "page": 1, "width": 595, "height": 842, "rotate": 0 },
    { "page": 2, "width": 595, "height": 842, "rotate": 0 }
  ],
  "truncated": false,
  "matches": [
    { "key": "assinatura-cliente", "page": 2, "x": 72, "y": 598.4, "width": 18.67, "height": 10 },
    { "key": "rubrica-cliente", "page": 1, "x": 500, "y": 790, "width": 13.89, "height": 10 },
    { "key": "rubrica-cliente", "page": 2, "x": 500, "y": 790, "width": 13.89, "height": 10 }
  ]
}

x, y: canto superior esquerdo do texto achado, já com o offset, em pontos de PDF, no mesmo sistema de coordenadas de PUT .../fields (origem no canto superior esquerdo da página como ela aparece na tela, rotação já aplicada).

width, height: tamanho aproximado do texto achado. Servem de referência; o tamanho do campo é você quem define.

truncated: true quando o documento tem mais de 500 páginas; as páginas além do limite não foram procuradas.

pages: o tamanho de cada página lida, para você conferir que x + largura do campo e y + altura do campo cabem na página.

Âncora não encontrada não é erro: a key simplesmente não aparece em matches. Confira isso antes de enviar o envelope.

Os campos aceitam coordenadas em pontos inteiros: valores fracionários são arredondados no PUT .../fields.

Do match ao campo

Direto no PUT: `anchor` no campo

Em vez de chamar anchors:find e montar as coordenadas, você pode mandar a âncora no próprio campo em PUT .../documents/{documentId}/fields (envelope ou modelo). A SuperSign procura o texto e grava o campo com a página e a posição achadas.

Cada campo traz exatamente um dos dois: pages + position (como sempre) ou anchor. Mandar os dois, ou nenhum, responde 400. size continua obrigatório. Campos sem anchor não disparam busca nenhuma: um PUT só com coordenadas funciona exatamente como antes.

{
  "fields": [
    {
      "id": "3f1c2a7e-5b4d-4c8e-9f10-2a3b4c5d6e7f",
      "participantId": "7a9e6679-7425-40de-944b-e07fc1f90ae7",
      "type": "SIGNATURE",
      "anchor": { "text": "\\s1\\", "offset": { "x": 0, "y": -40 } },
      "size": { "width": 180, "height": 50 },
      "properties": {}
    }
  ]
}

Campo de `anchor`	Padrão	Descrição
`text`	-	Texto a procurar (1 a 200 caracteres)
`occurrence`	`"first"`	`"first"`, um número N (a N-ésima no documento) ou `"all"` (um campo por ocorrência)
`caseSensitive`	`false`	Diferenciar maiúsculas de minúsculas
`matchWholeWord`	`false`	Só aceitar palavra inteira
`offset`	`{ "x": 0, "y": 0 }`	Deslocamento em pontos somado ao canto superior esquerdo do texto achado
`ifNotFound`	`"error"`	`"error"`: o PUT inteiro é recusado com `422 ANCHOR_NOT_FOUND` e nada é gravado. `"ignore"`: o campo é omitido e os demais são gravados (veja o aviso abaixo)

Regras:

Uma busca por documento: todas as âncoras do PUT são procuradas juntas, antes de qualquer gravação. Até 20 campos com anchor por chamada.

occurrence: "all" gera um campo por ocorrência. O primeiro usa o id que você enviou; os demais recebem um id derivado (UUID v5), o mesmo a cada PUT repetido sobre o mesmo documento - então repetir o PUT atualiza esses campos em vez de duplicá-los. O GET .../fields mostra esses ids, e eles são aceitos de volta num PUT. No máximo 200 campos gerados por âncoras num PUT (422 ANCHOR_TOO_MANY_MATCHES).

ifNotFound: "ignore" e campo já existente: o campo é omitido do PUT e, como o PUT substitui todos os campos do documento, um campo que JÁ EXISTE com aquele id é removido. Use "ignore" só para campos novos; para manter um campo existente cujo texto sumiu, reenvie-o com pages + position.

422 ANCHOR_NOT_FOUND lista todas: details.anchors traz todas as âncoras não achadas (fieldId e text), não só a primeira, e details.truncated indica se a leitura parou no teto de páginas.

A âncora não é guardada: o GET .../fields devolve as coordenadas resolvidas (pontos inteiros). Um PUT posterior só com coordenadas não refaz a busca.

O campo precisa caber na página: se a posição achada + offset + size sair da página, a resposta é 400 FIELD_GEOMETRY_INVALID e nada é gravado.

CHECKBOX_GROUP e RADIO_GROUP não aceitam anchor (cada opção tem posição própria): use coordenadas.

Os erros da busca valem aqui também, e só quando há anchor: 409 DOCUMENT_NOT_READY, 422 DOCUMENT_HAS_NO_TEXT / DOCUMENT_TEXT_UNREADABLE / DOCUMENT_TOO_LARGE_FOR_ANCHOR, 503 ANCHOR_SEARCH_BUSY / ANCHOR_SEARCH_UNAVAILABLE com Retry-After. Em todos eles nada é gravado.

Idempotência: o PUT continua sem Idempotency-Key. Com o mesmo corpo e o mesmo documento, o resultado é o mesmo. Com anchor, o resultado depende do texto do documento: se o documento for substituído, o mesmo PUT pode posicionar os campos em outro lugar.

send-now aceita anchor, com comportamento assíncrono: veja a seção Âncora no send-now abaixo.

Âncora no `send-now` (assíncrona)

POST /v4/api/envelopes/send-now aceita anchor em cada campo, no lugar de pageNumber + position, com size obrigatório (a posição vem do texto, o tamanho vem de você):

{
  "fields": [
    {
      "type": "SIGNATURE",
      "documentRef": "contrato",
      "signatoryRef": "contratante",
      "anchor": { "text": "\\s1\\", "offset": { "x": 0, "y": -40 } },
      "size": { "width": 180, "height": 50 },
      "properties": {}
    }
  ]
}

O anchor tem as mesmas opções do PUT .../fields (text, occurrence, caseSensitive, matchWholeWord, offset, ifNotFound). Cada campo traz exatamente um entre pageNumber + position e anchor (os dois, ou nenhum, é 400); com anchor, size é obrigatório; CHECKBOX_GROUP e RADIO_GROUP não aceitam anchor; no máximo 20 campos com anchor por chamada. Campos sem anchor seguem exatamente como antes.

É assíncrono. O 201 volta antes de o PDF existir (você ainda vai subir o arquivo), então a busca não acontece na resposta. Ela roda no servidor depois que todos os documentos terminam de processar e antes do envio aos participantes:

Você recebe 201 com as URLs de upload; os campos com anchor ficam guardados como pendentes.

Você sobe os arquivos. Quando todos terminam de processar, a SuperSign procura os textos, grava os campos nas posições achadas e só então envia o envelope.

Se não for possível posicionar, o envelope não é enviado: ele é anulado e você recebe o webhook ENVELOPE_VOIDED. O motivo fica em cancellationReason (e no histórico do envelope) e traz a causa: texto não encontrado (com os textos), PDF sem texto, PDF grande demais, campo que sairia da página, mais de 200 campos gerados, ou busca indisponível. Nenhuma mensagem é enviada aos participantes. Para tentar de novo, crie outro envelope.

Falha temporária da busca (servidor ocupado, por exemplo) é repetida automaticamente; não anula.

Erro no próprio POST: se a busca por âncora está desligada no ambiente, o POST responde 503 ANCHOR_SEARCH_UNAVAILABLE e nenhum envelope é criado. Não há 422 ANCHOR_NOT_FOUND nem os demais erros da busca na resposta do POST: eles chegam pelo ENVELOPE_VOIDED.

ifNotFound: "ignore" omite o campo cujo texto não foi achado e envia o envelope com os demais; um envelope sem nenhum campo de assinatura segue as regras de sempre. A Idempotency-Key continua valendo como no restante do send-now.

Se você precisa saber o resultado da busca antes de enviar, use o fluxo em etapas (criar, enviar o documento, PUT .../fields com anchor, enviar).

Precisão

A posição vem do texto que o PDF declara, não de uma imagem da página. A caixa do texto é aproximada: em geral fica a 1-3 pontos da posição real numa fonte de 12 pt. Um marcador sozinho na linha (como \s1\) é o caso mais preciso; um trecho no meio de uma frase pode deslocar alguns pontos na horizontal. Use o offset para dar folga e posicionar o campo acima, abaixo ou ao lado do marcador.

Limites e casos que não funcionam

PDF escaneado (só imagem, sem texto): não há o que procurar. Se nenhuma página tem texto, a resposta é 422 DOCUMENT_HAS_NO_TEXT; posicione os campos por coordenadas.

Fontes sem mapeamento de caracteres (alguns PDFs gerados por impressoras virtuais ou com fontes embutidas incompletas) podem extrair texto ilegível; a âncora não é encontrada.

Ligaduras (fi, fl desenhados como um só glifo) podem impedir que um texto com essas letras seja encontrado. Marcadores como \s1\ não têm esse problema.

Arquivos acima de 30 MiB: 422 DOCUMENT_TOO_LARGE_FOR_ANCHOR, sem leitura.

Documentos longos: são lidas no máximo 500 páginas (truncated: true avisa), com limite de tempo. Se a leitura não terminar, a resposta é 422 DOCUMENT_TEXT_UNREADABLE.

A busca tem capacidade limitada por servidor. Quando está ocupada, ou numa falha temporária, a resposta é 503 (ANCHOR_SEARCH_BUSY ou ANCHOR_SEARCH_UNAVAILABLE) com o cabeçalho Retry-After: aguarde esses segundos e repita. Não dispare muitas buscas em paralelo; faça uma por documento.

Documento ainda em processamento: 409 DOCUMENT_NOT_READY. Aguarde e tente de novo.

Envelope ou documento de outra conta, fora da pasta do usuário responsável pela chave, ou inexistente: 404.

Quando usar#

Marcadores recomendados#

Fluxo#

Requisição#

Resposta 200#

Do match ao campo#

Direto no PUT: anchor no campo#

Âncora no send-now (assíncrona)#

Precisão#

Limites e casos que não funcionam#