Marcas de referência

É possível configurar marcas de referência, adicionadas aos documentos de um envelope. As marcas pertencem ao envelope, e não a um signatário, e são configuradas pelo parâmetro linkMark.

O parâmetro linkMark possui quatro opções, que podem ser utilizadas separadamente ou em conjunto:

id: Identificador, escrito no documento.
tag: Etiquetas, cada uma com a sua própria imagem e posição.
qrCode: QR Codes, com conteúdo livre ou com o endereço de validação do documento.
text: Textos livres, escritos a partir das posições informadas.

Parâmetro required

Todas as opções de linkMark possuem o parâmetro required, que define o comportamento para documentos que já possuem assinaturas. Não é possível adicionar marcas de referência em documentos já assinados.

true: A requisição de criação do envelope irá falhar caso algum documento com a marca possua assinaturas. Padrão para tag, qrCode e text.
false: A marca não será adicionada aos documentos que já possuam assinaturas, e o envelope é criado normalmente.

Para a opção id, o parâmetro required é obrigatório.

Configuração das posições

As opções tag, qrCode e text são posicionadas por documento. Em cada posição é possível definir o documento (parâmetro documentNonce, que deve corresponder ao nonce de um dos documentos do envelope) e a página (parâmetro page) em que a marca será adicionada, assim como a posição inicial (parâmetros x e y). A origem da coordenada x é o canto esquerdo do documento e a origem da coordenada y é o canto inferior do documento.

É possível adicionar mais de uma marca no mesmo documento e na mesma página.

Adiciona o identificador de cada documento do envelope. A opção possui apenas o parâmetro required.

"linkMark": {
  "id": {
    "required": false
  }
}

Tag

Adiciona etiquetas aos documentos do envelope. Cada posição é uma etiqueta independente, com a sua própria imagem e o seu próprio posicionamento. As etiquetas são enviadas pelo parâmetro positions.

A imagem de cada etiqueta é configurada pelo parâmetro imageNonce, que deve corresponder ao nonce de uma das imagens enviadas no parâmetro images do envelope. É possível reutilizar uma mesma imagem em diversas etiquetas utilizando o nonce da imagem.

Além da posição inicial, cada etiqueta define as suas dimensões (parâmetros width e height, com as dimensões em milímetros).

As etiquetas são aceitas pela API apenas na criação do envelope. Enquanto o envelope não possuir assinaturas, as etiquetas podem ser alteradas pela página de configuração do envelope.

"images": [
  {
    "imageNonce": "img1",
    "image": "iVBORw0KGgoAAAANSUhEUgAA..."
  }
],
"linkMark": {
  "tag": {
    "required": false,
    "positions": [
      {
        "documentNonce": "documento1",
        "imageNonce": "img1",
        "x": 10,
        "y": 10,
        "width": 30,
        "height": 20,
        "page": "LAST"
      }
    ]
  }
}

QrCode

Adiciona QR Codes aos documentos do envelope. Os QR Codes são enviados pelo parâmetro entries, em que cada item define um conteúdo (parâmetro value) e as posições em que ele é adicionado (parâmetro positions). Cada item deve possuir ao menos uma posição.

Com value: O QR Code contém o conteúdo informado, com no máximo 1000 caracteres.
Sem value (ausente ou vazio): O QR Code contém o endereço para a tela de validação do documento em que é adicionado. Cada documento recebe o seu próprio endereço, o que permite validar o documento escaneando o QR Code.

O QR Code é sempre quadrado: o parâmetro width define o lado do QR Code, em milímetros.

Na consulta do envelope, os QR Codes são devolvidos pelo parâmetro positions, um item por posição, com o value como foi enviado na criação do envelope (vazio quando o QR Code contém o endereço da tela de validação).

"linkMark": {
  "qrCode": {
    "required": false,
    "entries": [
      {
        "positions": [
          {
            "documentNonce": "documento1",
            "x": 150,
            "y": 10,
            "width": 45,
            "page": "1"
          }
        ]
      },
      {
        "value": "https://www.bry.com.br",
        "positions": [
          {
            "documentNonce": "documento1",
            "x": 150,
            "y": 50,
            "width": 30,
            "page": "LAST"
          }
        ]
      }
    ]
  }
}

Text

Escreve textos nos documentos do envelope. Os textos são enviados pelo parâmetro entries, em que cada item define um texto (parâmetro value) e as posições em que ele é escrito (parâmetro positions). Cada item deve possuir um texto e ao menos uma posição.

O texto deve conter ao menos um caractere além de espaços e quebras de linha. As quebras \n e <br> iniciam uma nova linha; não há quebra de linha automática. A fonte, o tamanho e a cor do texto são fixos.

O texto não possui largura nem altura: ele é escrito a partir das coordenadas iniciais (parâmetros x e y), que devem estar dentro da área da página indicada.

Na consulta do envelope, os textos são devolvidos pelo parâmetro positions, um item por posição, com o value como foi enviado na criação do envelope.

"linkMark": {
  "text": {
    "required": false,
    "entries": [
      {
        "value": "Texto customizado\nSegunda linha",
        "positions": [
          {
            "documentNonce": "documento1",
            "x": 10,
            "y": 50,
            "page": "1"
          }
        ]
      }
    ]
  }
}

Alteração dos documentos

Os QR Codes e os textos de um documento são removidos quando o documento é excluído do envelope, ou quando o conteúdo do documento é substituído, pois foram posicionados para o conteúdo anterior.