> For the complete documentation index, see [llms.txt](https://docs.gocrypto.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gocrypto.com.br/requisicao-de-assinatura.md).

# Requisição de assinatura

## Tipos de assinatura por tipo de arquivo

### Assinatura CMS - Internacional

```json
{
  "callbackUrl": "...", //URL de callback (página que será retornado ao assinar)
  "webhookUrl": "...", //URL de webhook (opcional)
  "security": {...}, //Array da configuração de segurança (na UI)
  "ui": {...}, //Configuração de UI
  "files": [{
    "id": "idsample1@xpto",
    "name": "Assinando conteudo attached", //Nome/Descrição do arquivo
    "description": "<h2> HTML sample <\/h2> Assinatura de conte\u00fado (CMS) .txt remoto https:\/\/gist.githubusercontent.com\/apipemc\/6047552\/raw\/5cf8793e00d569de4f1ee8c125648ee5e0b6e2de\/links.txt", //Descrição completa (que será exibida para o usuário) na hora da assinatura
    "src": "https:\/\/gist.githubusercontent.com\/apipemc\/6047552\/raw\/5cf8793e00d569de4f1ee8c125648ee5e0b6e2de\/links.txt", //Link do conteúdo que será assinado
    "signatureSetting": { //Configurações da assinatura
      "type": "hash", //Tipo hash/CMS (assina utilizando o hash do arquivo)
      "detached": false //Quando detached: o conteúdo assinado precisa ser mantido/armazenado para utilização da assinatura; quando attached: o conteúdo/arquivo fica embutido na assinatura bastando o arquivo de assinatura para validação e geração(extração) do arquivo original
    }
  }]
}
```

### Assinatura CAdES AD\_RB - ICP Brasil

```json
{
  "callbackUrl": "...", //URL de callback (página que será retornado ao assinar)
  "webhookUrl": "...", //URL de webhook (opcional)
  "security": {...}, //Array da configuração de segurança (na UI)
  "ui": {...}, //Configuração de UI
  "files": [{
    "id": "idsample3@xpto",
    "name": "Assinando conteudo attached", //Nome/Descrição do arquivo
    "description": "<h2> HTML sample <\/h2> Assinatura de conte\u00fado (CMS/CADES) .txt remoto https:\/\/gist.githubusercontent.com\/apipemc\/6047552\/raw\/5cf8793e00d569de4f1ee8c125648ee5e0b6e2de\/links.txt", //Descrição completa (que será exibida para o usuário) na hora da assinatura
    "src": "https:\/\/gist.githubusercontent.com\/apipemc\/6047552\/raw\/5cf8793e00d569de4f1ee8c125648ee5e0b6e2de\/links.txt", //Link do conteúdo que será assinado
    "signatureSetting": { //Configurações da assinatura
      "type": "hash", //Tipo hash/CMS (assina utilizando o hash do arquivo)
      "policy": "CAdES-AD_RB", //Indica que será utilizado a politica CAdES 
      "detached": false //Quando detached: o conteúdo assinado precisa ser mantido/armazenado para utilização da assinatura; quando attached: o conteúdo/arquivo fica embutido na assinatura bastando o arquivo de assinatura para validação e geração(extração) do arquivo original
    }
  }]
}
```

### Assinatura CAdES AD\_RT - ICP Brasil

```json
{
  "callbackUrl": "...", //URL de callback (página que será retornado ao assinar)
  "webhookUrl": "...", //URL de webhook (opcional)
  "security": {...}, //Array da configuração de segurança (na UI)
  "ui": {...}, //Configuração de UI
  "files": [{
    "id": "idsample1@xpto",
    "name": "Assinando conteudo attached", //Nome/Descrição do arquivo
    "description": "<h2> HTML sample <\/h2> Assinatura de conte\u00fado (CMS/CADES) .txt remoto https:\/\/gist.githubusercontent.com\/apipemc\/6047552\/raw\/5cf8793e00d569de4f1ee8c125648ee5e0b6e2de\/links.txt", //Descrição completa (que será exibida para o usuário) na hora da assinatura
    "src": "https:\/\/gist.githubusercontent.com\/apipemc\/6047552\/raw\/5cf8793e00d569de4f1ee8c125648ee5e0b6e2de\/links.txt", //Link do conteúdo que será assinado
    "signatureSetting": { //Configurações da assinatura
      "type": "hash", //Tipo hash/CMS (assina utilizando o hash do arquivo)
      "policy": "CAdES-AD_RT", //Indica que será utilizado a politica CAdES com uso do carimbo do tempo
      "detached": false //Quando detached: o conteúdo assinado precisa ser mantido/armazenado para utilização da assinatura; quando attached: o conteúdo/arquivo fica embutido na assinatura bastando o arquivo de assinatura para validação e geração(extração) do arquivo original
    }
  }]
}
```

### Assinatura PDFSignature - Internacional

```json
{
  "callbackUrl": "...", //URL de callback (página que será retornado ao assinar)
  "webhookUrl": "...", //URL de webhook (opcional)
  "security": {...}, //Array da configuração de segurança (na UI)
  "ui": {...}, //Configuração de UI
  "files": [{
    "id": "idsample7@xpto",
    "name": "Assinando PDFSignature", //Nome/Descrição do arquivo
    "description": "<h2>HTML que pode aparecer no lugar do arquivo, aceita bootstrap</h2>", //Caso seja uma assinatura de PDF, só exibe se o "preferPreview" for preenchido com "description"
    "src": "https:\/\/api-sandbox-assinatura.gestao.plus\/resolve?download-without-cors=https:\/\/api-sandbox-assinatura.gestao.plus\/gocrypto.pdf", //Link do PDF que será assinado
    "signatureSetting": { //Configurações da assinatura
      "type": "DOC-pdf", //Tipo doc-PDF 
      "visibleSignImg": "https:\/\/api-sandbox-assinatura.gestao.plus\/fixed-signature.png", //Link da imagem de assinatura visivel (opcional, veja todas as outras opções de layout)
      "visibleSignPage": 1, //Página que o field será colocado (quando houver assinatura visivel) 
      "visibleSignX": 390, //Posição do eixo X do field (quando houver assinatura visivel) 
      "visibleSignY": 10, //Posição do eixo Y do field (quando houver assinatura visivel) 
      "visibleSignWidth": 200, //Largura do field (quando houver assinatura visivel)
      "visibleSignHeight": 28 //Altura do field (quando houver assinatura visivel) 
    }
  }]
}
```

### Assinatura PAdES AD\_RB - ICP Brasil

```json
{
  "callbackUrl": "...", //URL de callback (página que será retornado ao assinar)
  "webhookUrl": "...", //URL de webhook (opcional)
  "security": {...}, //Array da configuração de segurança (na UI)
  "ui": {...}, //Configuração de UI
  "files": [{
    "id": "idsample7@xpto",
    "name": "Assinando PDFSignature", //Nome/Descrição do arquivo
    "src": "https:\/\/api-sandbox-assinatura.gestao.plus\/resolve?download-without-cors=https:\/\/api-sandbox-assinatura.gestao.plus\/gocrypto.pdf", //Link do PDF que será assinado
    "signatureSetting": { //Configurações da assinatura
      "type": "DOC-pdf", //Tipo doc-PDF 
      "policy": "PAdES-AD_RB" //Indica a Policita PaDES - AD_RB
    }
  }]
}
```

### Assinatura PAdES AD\_RT - ICP Brasil

```json
{
  "callbackUrl": "...", //URL de callback (página que será retornado ao assinar)
  "webhookUrl": "...", //URL de webhook (opcional)
  "security": {...}, //Array da configuração de segurança (na UI)
  "ui": {...}, //Configuração de UI
  "files": [{
    "id": "idsample7@xpto",
    "name": "Assinando PDFSignature", //Nome/Descrição do arquivo
    "src": "https:\/\/api-sandbox-assinatura.gestao.plus\/resolve?download-without-cors=https:\/\/api-sandbox-assinatura.gestao.plus\/gocrypto.pdf", //Link do PDF que será assinado
    "signatureSetting": { //Configurações da assinatura
      "type": "DOC-pdf", //Tipo doc-PDF 
      "policy": "PAdES-AD_RT" //Indica a Policita PaDES - AD_RT
    }
  }]
}
```

{% hint style="warning" %}
A aplicação GOCrypto abstrai o uso da carimbadora do tempo e inclusão do carimbo nas assinaturas;  Bastando incluir a politica no payload

Para uso da política (P/C)AdES\_RT é necessário incluir esse produto em contrato para bilhetagem (cobrança)
{% endhint %}

## Assinatura PDF com elementos gráficos

### Configuração de layout de assinatura visível (PDF)

#### Opção 1 (Default) - Geração de uma imagem/layout automático

A aplicação GOCrypto gera uma imagem para ser plotada no local de assinatura indicado, a imagem é gerado com base em um layout padrão e com os dados do certificado que está sendo utilizado para realizar a assinatura. &#x20;

Nessa modalidade é possível enviar parâmetros opcionais no array "signatureSetting" para realizar customização na imagem que será gerada&#x20;

<table><thead><tr><th width="322">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td>visibleSignatureGeneratorName</td><td>(opcional) Nome de quem está assinando (se não enviado, obtém do certificado)</td></tr><tr><td>visibleSignatureGeneratorDocument</td><td>(opcional) Documento de quem está assinando (Sufixo adicionado após o nome)</td></tr><tr><td>visibleSignatureGeneratorFooter</td><td>(opcional) Texto do rodapé da imagem</td></tr><tr><td>visibleSignatureGeneratorHeader</td><td>(opcional) Texto do cabeçalho da imagem</td></tr><tr><td>visibleSignatureGeneratorMarkerSrc</td><td>(opcional) Link de uma imagem de marcador (canto superior esquerdo)</td></tr><tr><td>visibleSignatureGeneratorBackgroundSrc</td><td>(opcional) Link de uma imagem que será utilizada como fundo (background)</td></tr><tr><td>visibleSignatureDateFormat</td><td>(opcional) Formato de data em texto<br><br>Ex1: d/m/Y\nH:i:s|TZ|America/Sao_Paulo<br><br>Ex2: d-m-Y H:i|TZ|America/Sao_Paulo</td></tr></tbody></table>

#### Opção 2 - Envio de uma imagem pronta para ser plotada

Nessa modalidade a aplicação cliente pode utilizar uma imagem fixa para todas as assinaturas, ou ficar responsável para gerar uma imagem PNG a cada assinatura, já enviando um link dessa imagem gerada.&#x20;

<table><thead><tr><th width="324">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td>visibleSignImg</td><td>Link de uma imagem (em PNG)</td></tr></tbody></table>

#### Opção 3 - Envio de um layout em HTML para geração de uma imagem customizada

Nessa modalidade a aplicação cliente tem total autonomia para fazer alterações de layout gerando um HTML único para todas assinaturas, trocando somente informações que são dinâmicas como (Data/hora, assinante etc) via parâmetro no layout.&#x20;

Também é possível a aplicação cliente gerar um layout diferente a cada assinante, podendo ou não usar os parâmetros disponíveis.

<table><thead><tr><th width="331">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td>visibleSignatureCustomTemplateSrc</td><td><p>Link do HTML que será utilizado para gerar a imagem.</p><p></p><p>As palavras chaves: <br>$P{name} - Será substituída pelo nome do assinante<br>$P{document} - Será substituída pelo documento do assinante (CPF/CNPJ)<br>$P{dateTime} - Será substituída pela data/hora do momento exato da assinatura<br><br>Ex: <a href="https://cdn.gestao.plus/gocrypto.com.br/assets/tests/template.html">https://cdn.gestao.plus/gocrypto.com.br/assets/tests/template.html</a></p></td></tr><tr><td>visibleSignatureDateFormat</td><td>(opcional) Formato de data em texto<br><br>Ex1: d/m/Y\nH:i:s|TZ|America/Sao_Paulo<br><br>Ex2: d-m-Y H:i|TZ|America/Sao_Paulo</td></tr></tbody></table>

## Configurações de usabilidade durante a assinatura

### Configuração de UI (User interface)

```json
{
    "callbackUrl": "...", //URL de callback (página que será retornado ao assinar)
    "webhookUrl": "...", //URL de webhook (opcional)
    "security": {...}, //Array da configuração de segurança (na UI)
    "ui": {
      "username": "04660457192", //CPF/CNPJ que será preenchido no username (para provedores de certificado em nuvem/PSC) 
      "scope": "signature_session", //Tipo de escopo do usuário (single_signature, multi_signature ou signature_session) 
      "lifetime": 86400, //Tempo de vida (caso use o scope: signature_session)
      "button": "Prosseguir", //Nomenclatura que será exibida no botão de "Assinar"
      "bg": "#f9f9f9", //Utiliza cor em hexadecimal (opcional)
      "color": "#f9f9f9", //Utiliza cor em hexadecimal (opcional)
      "callback": "https:\/\/gestao-online.com", //Cria o botão "Voltar" apontando para o link (para o caso de desistência da assinatura)
      "preferPreview": "file", //Default é "file" opcional enviar valor "description"
    },
    "files": [...] //Array de arquivos que serão assinados
  }
```

### Configuração de segurança de UI (User interface)

```json
{
    "callbackUrl": "...", //URL de callback (página que será retornado ao assinar)
    "webhookUrl": "...", //URL de webhook (opcional)
    "security": {
      "allowAddNewDocument": false, //Flag de adição de PDFs por parte do usuário (default: false)
      "allowChangeUsername": false, //Flag de trava do input de username (para provedores de certificado em nuvem/PSC) valor padrão (default: true)
      "allowDocumentType": false, //Flag de troca do tipo de assinatura (default: false)
      "payloadCallbackUrl": false, //Flag de permitir ou não o retorno dos links temporários do arquivo assinado na URL de callback (default: true), esse parâmetro deve ser sinalizado como falso quando se utiliza os Webhooks
      "allowEditScope": false, //Flag para permitir o usuário alterar o escopo
      "allowEditLifetime": false //Flag para permitir o usuário alterar o TTL (tempo de vida) da sessão
    },
    "ui": {..}, //Configuração de UI
    "files": [...] //Array de arquivos que serão assinados
}
```

### Configuração de certificados (Filtros de certificados)

O array de filtros, recebe N objetos de filtro. Cada objeto (filtro) é tratado as suas condições internas como uma condição (AND).  E cada objeto (filtro) são tratados entre si com a condição (OR).

Exemplo 1:  (Filtro 1) OR (Filtro 2) OR (Filtro 3). Se o certificado atender uma das condições de filtro, ele será listado.

Exemplo 2: Filtro 1 = { (Condição A) AND (Condição B) AND (Condição N) }.  O certificado deve atender todas as condições do filtro para que o filtro seja válido.

```json
{
  "callbackUrl": "...", //URL de callback (página que será retornado ao assinar)
  "webhookUrl": "...", //URL de webhook (opcional)
  "security": {...}, //Array da configuração de segurança (na UI)
  "ui": {..}, //Configuração de UI
  "certificates": { //Configuração de uso de certificados
    "filters": [ //Array de filtros (Filtro 1) OR (Filtro 2) OR (Filtro 3)
        { //Certificado é válido AND cadeia icpbr AND dá o match no CPF
          "validity": "now", //Se o certificado é válido agora (ou o momento Y-m-d H:i:s)
          "issuer=>organizationName": "ICP-Brasil", //Filtro da raiz ICP BR
          "subjectAltName=>otherName=>2.16.76.1.3.1": "********04660457192**************************" CPF filtro (deixe os *)
        },
        { //Certificado é válido AND cadeia icpbr AND dá o match no e-mail AND dá o match no cnpj
          "validity": "now", //Se o certificado é válido agora 
          "issuer=>organizationName": "ICP-Brasil", //Filtro da raiz ICP BR
          "subjectAltName=>rfc822Name": "paulo@gestao-online.com", //Filtro de e-mail no certificado
          "subjectAltName=>otherName=>2.16.76.1.3.3": "22361741000130" //Filtro de CNPJ
        },
        { //Certificado é válido AND cadeia icpbr AND dá o match no cn
          "validity": "now", //Se o certificado é válido agora 
          "issuer=>organizationName": "ICP-Brasil", //Filtro da raiz ICP BR
          "cn": "PAULO FILIPE MACEDO DOS SANTOS:04660457192" //Filtro por CN
        }
    ]
  },
  "files": [...]
}
```

<table><thead><tr><th width="290">Filtro (Rule)</th><th>Descrição</th></tr></thead><tbody><tr><td>validity</td><td>"now" ou datetime do momento (Y-m-d H:i:s) </td></tr><tr><td>subjectAltName=>rfc822Name</td><td>E-mail que será filtrado</td></tr><tr><td>issuer=>organizationName</td><td>"ICP-Brasil", caso não seja enviado poderão ser listados de outras cadeias de confiança ou certificados auto-assinados</td></tr><tr><td>subjectAltName=>otherName=>2.16.76.1.3.1</td><td>Filtro pelo OID 2.16.76.1.3.1, usar * (wildcard) para qualquer valor, <br><br>Ex: Para filtro de CPF: <br><br>"*******04660457192******************"<br><br>Também pode ser realizados outros filtros pelo OID:<br>- Nas primeiras 8 (oito) posições, a data de nascimento do titular, no formato ddmmaaaa; <br>- Nas 11 (onze) posições subseqüentes, o Cadastro de Pessoa Física (CPF) do titular<br>- Nas 11 (onze) posições subseqüentes, o número de inscrição do titular no PIS/PASEP<br>- Nas 11 (onze) posições subseqüentes, o número do Registro Geral - RG do titular; nas 6 (seis) posições subseqüentes, as siglas do órgão expedidor do RG e respectiva UF.</td></tr><tr><td>subjectAltName=>otherName=>2.16.76.1.3.3</td><td>Filtro pelo OID 2.16.76.1.3.3 nesse campo está previsto o valor do CNPJ</td></tr></tbody></table>

####