Requisição de assinatura

Parâmetros para compor uma solicitação de assinatura

Tipos de assinatura por tipo de arquivo

Assinatura CMS - Internacional

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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
    }
  }]
}

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)

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.

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

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

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.

Parâmetro	Descrição
visibleSignImg	Link de uma imagem (em PNG)

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.

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.

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

Configurações de usabilidade durante a assinatura

Configuração de UI (User interface)

{
    "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)

{
    "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.

{
  "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": "[email protected]", //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": [...]
}

Filtro (Rule)	Descrição
validity	"now" ou datetime do momento (Y-m-d H:i:s)
subjectAltName=>rfc822Name	E-mail que será filtrado
issuer=>organizationName	"ICP-Brasil", caso não seja enviado poderão ser listados de outras cadeias de confiança ou certificados auto-assinados
subjectAltName=>otherName=>2.16.76.1.3.1	Filtro pelo OID 2.16.76.1.3.1, usar * (wildcard) para qualquer valor, Ex: Para filtro de CPF: "*******04660457192******************" Também pode ser realizados outros filtros pelo OID: - Nas primeiras 8 (oito) posições, a data de nascimento do titular, no formato ddmmaaaa; - Nas 11 (onze) posições subseqüentes, o Cadastro de Pessoa Física (CPF) do titular - Nas 11 (onze) posições subseqüentes, o número de inscrição do titular no PIS/PASEP - 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.
subjectAltName=>otherName=>2.16.76.1.3.3	Filtro pelo OID 2.16.76.1.3.3 nesse campo está previsto o valor do CNPJ