Guia de integração para testar a assinatura remota de documentos com a API eSigner CSC

Este guia irá guiá-lo através da assinatura de um hash de documento e arquivo PDF com SSL.com Assinatura eletrônica serviço de assinatura em nuvem e a API Cloud Signature Consortium (CSC). Todos os exemplos de solicitação de API serão mostrados com Postman, e recomendamos instalar o App de desktop Postman no seu computador se você quiser trabalhar com os exemplos. Exemplos de comandos cURL das solicitações de API também estão incluídos.

Este guia cobre o uso da API CSC em SSL.com's Sandbox ambiente de teste, para que você possa experimentar a API sem se preocupar em ser cobrado. Consulte nosso Guia sandbox para obter instruções sobre como configurar sua conta Sandbox.

Se você estiver pronto para trabalhar com a API CSC no ambiente eSigner de produção da SSLcom, leia Assinatura remota de documentos com eSigner CSC API.

Criar um pedido de teste

  1. Primeiro, você precisará criar um pedido de assinatura de documento no Sandbox. Comece fazendo login em sua conta do Sandbox e indo para o Painel aba.
    Painel Sandbox
  2. Clique ferramentas de desenvolvimento.
    ferramentas de desenvolvimento
  3. Selecionar Assinatura de documento eSigner, Então clique no Criar ordem de teste botão.
  4. Uma caixa de diálogo aparecerá. Clique no OK botão.
  5. Localize o seu pedido de teste e clique no botão detalhes link.
    link de detalhes
  6. Clique editar registrante para começar a inserir as informações do candidato e do destinatário para seu pedido de teste. Observe que, como essas informações não serão usadas para emitir um certificado de assinatura de documento válido, você pode inserir informações fictícias, se desejar.
    editar registrante
  7. Adicione as informações do candidato para o certificado de teste e clique no botão Próxima >> botão.
    Informação do Requerente
  8. Insira as informações do destinatário e clique no Próxima >> botão.
    Informações do destinatário
  9. Clique na pular botão para pular o upload de documentos de validação para o certificado de teste.
    Botão pular
  10. Seu pedido de teste agora deve ter um status de Validação pendente. Entre em contato com a equipe de suporte SSL.com em Support@SSL.com para ter seu certificado de teste validado.
    Validação pendente

Inscreva-se no eSigner e configure a autenticação de dois fatores

  1. Uma vez que seu pedido de teste foi validado pela equipe de suporte SSL.com, você pode inscrevê-lo no eSigner. Navegue até o Pedidos guia em sua conta sandbox SSL.com e localize seu pedido de teste.
    Navegue até o pedido
  2. Clique no pedido detalhes link.
    link de detalhes
  3. Crie e confirme um PIN de 4 dígitos e clique no botão criar PIN botão.
    Se você precisar redefinir seu PIN do eSigner, leia este tutorial.
    Criar PIN
  4. Um código QR aparecerá.
    Na próxima vez que você recarregar a página, o código QR não estará visível. Se você precisar visualizar ou redefinir seu código QR eSigner, leia este tutorial.
    QR Code
  5. Digitalize o código em um aplicativo de autenticação de dois fatores em seu dispositivo móvel, como Google Authenticator ou Authy. O aplicativo fornecerá senhas de uso único (OTPs) para uso ao assinar. Cada OTP é válido por 2 segundos.
    OTP em Authy

Instale Postman e Importar Coleção de API CSC

  1. Baixe e descompacte o Coleção CSC API Postman (Vejo https://www.postman.com/sslcom/workspace/public/collection/3420801-f2df0995-1293-45da-8719-73467c9f0ca7?ctx=documentation para os endpoints de API mais recentes ou downloads de coleção).
    Coleção de carteiro da API CSC
  2. Baixe e instale o Cliente Postman REST.
    Download do cliente Postman REST
  3. Inicie o Postman e, em seguida, crie uma nova conta do Postman ou entre em uma existente.
    Login do carteiro
  4. Clique na importação botão.
    Botão Importar
  5. Clique na Fazer upload de arquivos botão, navegue até o arquivo de coleção de API descompactado (CSC-API.postman_collection.json) e abra-o.
    Fazer upload de arquivos
  6. Clique na importação botão.
    Botão Importar
  7. Clique na Coleções guia no Postman e expanda a coleção de API CSC para visualizar as cinco solicitações POST com as quais você trabalhará:
    • Informações CSC
    • Lista de Credenciais CSC
    • Informações de credenciais do CSC
    • Autorizar credenciais
    • Assinar Hash

    Coleção CSC API

Recuperar token de acesso

  1. A próxima etapa é recuperar um token de acesso de SSL.com. Antes de solicitar seu token de acesso, você precisará de um ID do cliente (também conhecido como ID do aplicativo. Por favor, consulte este tutorial para obter instruções sobre como gerar essa credencial).
  2. Selecione os Autorização guia, selecione OAuth2.0 do Formato menu e clique no Obtenha um novo token de acesso botão.
    Obtenha um novo token de acesso
  3. Insira as seguintes informações no formulário:
    • Nome do Token: SandBox CSC (ou qualquer outro nome fácil de lembrar que você preferir)
    • Tipo de concessão: Código de autorização
    • URL de retorno de chamada: [deixe em branco]
    • Autorizar usando o navegador: verificado
    • URL de autenticação: https://oauth-sandbox.ssl.com/oauth2/authorize
    • URL do token de acesso: https://oauth-sandbox.ssl.com/oauth2/token
    • ID do Cliente: [Seu ID de cliente]
    • Segredo do Cliente: [Seu segredo de cliente]
    • Escopo: serviço
    • Estado: [deixe em branco]
    • Autenticação de cliente: Enviar como cabeçalho de autenticação básica

    Quando terminar, clique no Solicitar Token botão.
    Obtenha um novo token de acesso

  4. Um formulário de login aparecerá no seu navegador. Digite seu nome de usuário e senha SSL.com e clique no botão Acesso de Membros botão.
    Formulário de Login da Conta
  5. Seu novo token de acesso deve aparecer no Postman. Selecione o texto do token de acesso, copie-o para a área de transferência e feche o Gerenciar tokens de acesso caixa de diálogo. Cole seu token de acesso em um editor de texto onde você possa acessá-lo facilmente. Cada token de acesso expirará após uma hora.
    Você também pode salvar seu token para reutilização em Postman solicitações, mas descobrimos que é mais confiável copiar e colar o token diretamente em cada solicitação.
    token de acesso

Assine um Hash

Agora que você tem um token de acesso, pode começar a fazer solicitações de API e criar assinaturas. Esta seção o guiará pelas cinco solicitações disponíveis no coleção carteiro CSC, resultando na criação de uma assinatura digital a partir de um hash de documento.

Obtenha informações do CSC (opcional)

  1. Você pode usar o Informações CSC solicitação para obter informações sobre o serviço de assinatura em nuvem SSL.com. Observe que, ao contrário das outras na coleção, esta solicitação não requer seu token de acesso. Para enviar a solicitação, selecione Informações CSC do API CSC coleção e clique no ENVIAR botão.
    Solicitação de informações CSC
  2. As informações sobre o serviço de assinatura em nuvem aparecerão em um objeto JSON no Postman's Resposta campo.
    Informações CSC

Comando cURL

curl --location --request POST "https://cs-try.ssl.com/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}"

Lista de Credenciais CSC

  1. Lista de Credenciais CSC request irá recuperar uma credencial que você usará em solicitações de API posteriores. Selecione Lista de Credenciais CSC E clique no Autorização aba.
    Lista de Credenciais CSC
  2. Escolha Símbolo do portador do Formato menu, cole seu token de acesso no Token campo e clique no ENVIAR botão.
    Adicionar token e enviar solicitação
  3. Um objeto JSON com uma lista de IDs de credenciais associados ao usuário aparecerá no Resposta campo. Sua lista provavelmente conterá um valor. Copie e cole seu ID de credencial em um editor de texto para uso em solicitações posteriores.
    ID de credencial

Comando cURL

Substituir MY-ACCESS-TOKEN com seu token de acesso real:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Autorização: Bearer MY-ACCESS-TOKEN "\ --data-raw" {} "

Se estiver usando um certificado eseal (certificado de assinatura de documento apenas com informações da organização; incluído em sua conta esigner.com gratuita), inclua “clientData”: “DS_ESEAL” (observação: eseals não requerem autenticação OTP). Outras opções para “clientData” são “EVCS” para EV Code Signing e “DS” (padrão) para IV ou IV + OV Document Signing:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Autorização: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "clientData \": \ "DS_ESEAL \"} "

Informações de credenciais do CSC (opcional)

  1. A Informações de credenciais do CSC a solicitação retornará certificados e outras informações associadas a uma ID de credencial e não é necessária para assinatura. Para usar esta solicitação, selecione Informações de credenciais do CSC da coleção e clique no Autorização aba.
    Informações de credenciais do CSC
  2. Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
    colar token de autorização
  3. Selecione os Corpo guia e cole seu ID de credencial como o valor para credentialID.
    Insira o ID da credencial
  4. Clique na ENVIAR botão.
    Clique no botão enviar
  5. Um objeto JSON com sua cadeia de certificados de assinatura e outras informações aparecerão no Resposta campo.
    Informação de identificação de credencial

Comando cURL

Substituir MY-ACCESS-TOKEN e MY-CREDENTIAL-ID com suas informações reais:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application / json" \ --header "Autorização: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \": \ "MY-CREDENTIAL-ID \", \ "certificados \": \ "cadeia \", \ "certInfo \": verdadeiro, \ "authInfo \": true} "

Autorizar credenciais

  1. A Autorizar credenciais a solicitação recuperará a autorização para assinar um hash. Comece selecionando Autorizar credenciais da coleção e clicando no Autorização aba.
    Autorizar credenciais
  2. Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
    colar token
  3. Selecione os Corpo aba. Cole seu ID de credencial como o credentialID valor e um hash do documento que você deseja assinar como o hash valor. Recupere e insira um OTP de seu aplicativo de autenticação e insira-o como o valor para OTP, Então clique no ENVIAR botão.
    insira id de credencial, hash e OTP
  4. Um objeto JSON com seus Dados de Ativação de Assinatura (SAD) aparecerá no Resposta campo. Copie e cole esse valor em um editor de texto para usar na solicitação de assinatura hash.
    SAD

Comando cURL

Substituir MY-ACCESS-TOKENMY-CREDENTIAL-ID, MY-HASH e MY-OTP com suas informações reais:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/authorize" \ --header "Tipo de conteúdo: application / json" \ --header "Autorização: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \": \ "MY-CREDENTIAL-ID \", \ "numSignatures \": 1, \ "hash \": [\ "MY-HASH \ "], \" OTP \ ": \" MY-OTP \ "}"

Assinar Hash

  1. Agora estamos prontos para assinar o hash do documento. Selecione Assinar Hash da coleção e, em seguida, selecione o Autorização aba.
    Assinar Hash
  2. Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
    colar token
  3. Selecione os Corpo aba. Cole seu ID de credencial como o credentialID valor, seus dados de ativação de assinatura como o SAD valor, e um hash do documento que você deseja assinar como o hash valor e clique no ENVIAR botão.
    Cole SAD e hash, envie a solicitação
  4. Um objeto JSON com sua assinatura aparecerá no Resposta campo.
    assinatura

Comando cURL

Substituir MY-ACCESS-TOKENMY-CREDENTIAL-ID, MY-SAD e MY-HASH com suas informações reais:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application / json" \ --header "Autorização: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \": \ "MY-CREDENTIAL-ID \", \ "SAD \": \ "MY-SAD \", \ "hash \": [\ "MY-HASH \"], \ "signAlgo \": \ "1.2.840.113549.1.1.11 \"} "

Assine um PDF

Além de assinar hashes de documentos, você também pode fazer upload e assinar um arquivo PDF. Comece baixando e importando o Coleção Postman da Document Signing API (Vejo https://www.postman.com/sslcom/workspace/public/collection/3454644-277d8427-f749-4a94-93bf-c3478b79b999?ctx=documentation para os endpoints de API e downloads de coleção mais recentes), seguindo o mesmo etapas de instalação você seguiu acima para a coleção CSC API.

A autorização OTP não é necessária ao assinar usando um certificado de assinatura de documento esealing. Ignore todos os parâmetros OTP no guia a seguir se estiver usando um certificado de assinatura de documento com selo. (Clientes com um Certificado de assinatura do documento de validação da organização pode contatar support@ssl.com para convertê-lo em um certificado eSealing.)
Ao assinar um PDF, você trabalhará com duas solicitações POST:

  • Carregar documento PDF
  • Assinar documento PDF

Coleção da API de assinatura de documentos

Você pode reutilizar a credencial recuperada acima com o Lista de Credenciais CSC solicitação. Você provavelmente também precisará recuperar um novo token de acesso.

Carregar documento PDF

  1. Selecione os Carregar documento PDF solicitar e clicar no Autorização aba.
    Carregar documento PDF
  2. Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
    Colar token
  3. Selecione os Cabeçalhos guia e cole seu ID de credencial no Valor coluna.
    adicionar ID de credencial ao cabeçalho
  4. Selecione os Corpo guia e clique no × próximo de hello.pdf para remover este nome de arquivo de espaço reservado.
    remover arquivo de espaço reservado
  5. Clique na Selecione o arquivo e navegue até o arquivo que deseja enviar.
    Selecione o arquivo
  6. Clique na ENVIAR botão.
    Enviar solicitação
  7. Selecione e copie o id valor na resposta para usar na próxima solicitação.
    ID do arquivo

comando cURL

Substituir MY-CREDENTIAL-ID, MY-ACCESS-TOKEN e /PATH/TO/FILE.pdf com suas informações reais:

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Autorização: Portador MY-ACCESS-TOKEN "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "

Observação: para assinaturas visíveis, consulte os seguintes cabeçalhos de solicitação HTTP (/v1/pdf/upload):

Cabeçalho da solicitação

Descrição

ID da credencial

ID de credencial exclusivo atribuído à chave – Obrigatório

Razão de Assinatura

Adicionar motivo de assinatura para adicionar a aparência da assinatura e também no dicionário de assinaturas – Opcional, por exemplo, eu aprovo este documento

Local de assinatura

Adicionar local de assinatura no dicionário de assinaturas – Opcional, por exemplo, Houston, Texas

Informações de contato

Adicionar informações de contato no dicionário de assinaturas – Opcional, por exemplo, número de telefone

Assinatura-Campo-Posição

Posição do campo de assinatura onde a assinatura visual é exibida. O formato é "x,y,largura,altura" - opcional

Número de página

Número da página onde desenhar a assinatura – Opcional

Assinatura Manual

Imagem PNG codificada em Base64 de assinatura manual – Opcional




Assinar documento PDF

  1. Agora você pode assinar o PDF. Selecione os Carregar documento PDF solicitar e clicar no Autorização aba.
      
  2. Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
    colar token
  3. Selecione a guia Corpo e cole no id valor da etapa anterior.
    insira o ID
  4. Insira um OTP do seu aplicativo de autenticação e clique no ENVIAR botão.
    digite OTP e clique em Enviar
  5. Os dados do PDF aparecerão abaixo no Resposta campo. Escolher Salvar em um arquivo do Salvar resposta menu e, em seguida, dê um nome ao arquivo.
    Salvar em um arquivo
  6. Abra o arquivo no Acrobat para confirmar que o arquivo foi assinado. (Observe que na captura de tela abaixo, a raiz RSA Development de SSL.com foi confiada manualmente no Acrobat.)
    assinatura digital em Adobe Acrobat

Comando cURL

Substituir MY-CREDENTIAL-ID, MY-FILE-ID e MY-OTP com suas informações reais:

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/sign" \ --header "Content-Transfer-Encoding: application / json" \ --header "Content-Type : application / json "\ --header" Autorização: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "id \": \ "MY-FILE-ID \", \ "otp \": \ "MY-OTP \"} "

 Entrando em operação com a produção

Para entrar no ar, você precisa remover “-try” do subdomínio. Por exemplo, para ir ao ar com ds-try.ssl.com, remova “-try” para que o subdomínio se torne ds.ssl.com.

Os usuários podem assinar o código com o recurso de assinatura de código de validação estendida do eSigner. Clique abaixo para mais informações.

SAIBA MAIS

Twitter
Facebook
LinkedIn
Reddit
E-mail

Mantenha-se informado e seguro

SSL.com é líder global em segurança cibernética, PKI e certificados digitais. Inscreva-se para receber as últimas notícias do setor, dicas e anúncios de produtos da SSL.com.

Adoraríamos receber seu feedback

Responda à nossa pesquisa e deixe-nos saber sua opinião sobre sua compra recente.