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

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.

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.

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": "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": [...]
}

PreviousGetting startedNextRequisição de validação

Last updated