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.

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.
   
2. Clique 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.
   
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.
   
7. Adicione as informações do candidato para o certificado de teste e clique no botão Próxima >> botão.
   
8. Insira as informações do destinatário e clique no Próxima >> botão.
   
9. Clique na pular botão para pular o upload de documentos de validação para o certificado de teste.
   
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.
    

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 Encomendas guia em sua conta sandbox SSL.com e localize seu pedido de teste.
   
2. Clique no pedido detalhes link.
   
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.
   
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.
   
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.
   

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).
   
2. Baixe e instale o Cliente Postman REST.
   
3. Inicie o Postman e, em seguida, crie uma nova conta do Postman ou entre em uma existente.
   
4. Clique na Importar botão.
   
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.
   
6. Clique na Importar botão.
   
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

   

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

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

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.
   
2. As informações sobre o serviço de assinatura em nuvem aparecerão em um objeto JSON no Postman's Resposta campo.
   

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. O Plano de Ação Global para Saúde Mental da 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.
   
2. Escolha Símbolo do portador do Formato menu, cole seu token de acesso no Token campo e clique no ENVIAR botã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.
   

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. O Plano de Ação Global para Saúde Mental da 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.
   
2. Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
   
3. Selecione os Corpo guia e cole seu ID de credencial como o valor para credentialID.
   
4. Clique na ENVIAR botão.
   
5. Um objeto JSON com sua cadeia de certificados de assinatura e outras informações aparecerão no Resposta campo.
   

Comando cURL

Substituir MY-ACCESS-TOKEN e a 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. O Plano de Ação Global para Saúde Mental da 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.
   
2. Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
   
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.
   
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.
   

Comando cURL

Substituir MY-ACCESS-TOKEN,  MY-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.
   
2. Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
   
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.
   
4. Um objeto JSON com sua assinatura aparecerá no Resposta campo.
   

Comando cURL

Substituir MY-ACCESS-TOKEN,  MY-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.

• Carregar documento PDF
• Assinar documento PDF

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.
   
2. Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
   
3. Selecione os Cabeçalhos guia e cole seu ID de credencial no Valor coluna.
   
4. Selecione os Corpo guia e clique no × próximo de hello.pdf para remover este nome de arquivo de espaço reservado.
   
5. Clique na Selecione o arquivo e navegue até o arquivo que deseja enviar.
   
6. Clique na ENVIAR botão.
   
7. Selecione e copie o id valor na resposta para usar na próxima solicitação.
   

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):

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.
   
3. Selecione a guia Corpo e cole no id valor da etapa anterior.
   
4. Insira um OTP do seu aplicativo de autenticação e clique no ENVIAR botão.
   
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.
   
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.)
   

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.