Este guia mostrará como inscrever um pedido de certificado de assinatura de documento com SSL.com's Assinatura eletrônica serviço e usar a API Cloud Signature Consortium (CSC) para assinar digitalmente um hash de documento e um arquivo PDF. Você pode usar este guia com qualquer cURL or Postman. Recomendamos que os usuários do Postman instalem o aplicativo de desktop para trabalhar com os exemplos. Os exemplos neste guia são aplicáveis aos ambientes de produção e teste eSigner e eSealing do SSL.com. As diferenças nos comandos entre os modos de produção e teste são explicadas nas seções a seguir.
Para seguir essas instruções, você precisará de:
- Um pedido de certificado de assinatura de documento validado. Por favor leia este tutorial para obter instruções completas sobre pedido e validação.
- A ID do cliente (também conhecido como ID do aplicativo. Por favor, consulte este tutorial para obter instruções sobre como gerar essa credencial).
Solicite seu certificado de assinatura de documento SSL.com
Como solicitar um certificado no ambiente de produção
Consulte este artigo do guia para obter instruções sobre como solicitar um certificado de assinatura de documento de produção: Processo de Pedido de Certificados de Assinatura de Código e Documento
Como solicitar um certificado de teste no Sandbox do SSL.com
SSL.com oferece um ambiente Sandbox dedicado, espelhando nosso portal SSL.com ativo e API SWS, para um espaço de experimentação sem riscos. Esta configuração de “laboratório” permite aos usuários explorar e testar os serviços do SSL.com sem a preocupação de causar interrupções ou incorrer em custos reais.
O artigo, Usando o SSL.com Sandbox para teste e integração, irá ajudá-lo a navegar no processo de estabelecimento de uma conta Sandbox, iniciando um pedido de teste e integrando o Sandbox com a API SWS.
Depois de criar seu certificado de teste, entre em contato com a equipe de suporte SSL.com para validá-lo. Você pode fazer isso clicando no botão de bate-papo on-line no canto inferior direito do SSL.com site ou enviando um e-mail para support@ssl.com.
Inscreva-se no eSigner e configure a autenticação de dois fatores
Antes de começar a usar a API CSC, você precisará se inscrever no serviço de assinatura em nuvem eSigner de SSL.com. Pedidos validados podem ser inscritos no eSigner seguindo as instruções abaixo:
- . Navegue até o Encomendas em sua conta SSL.com e localize seu pedido.
- Clique no pedido detalhes link.
- 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.
- 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.
- Digitalize o código em um aplicativo de autenticação de dois fatores em seu dispositivo móvel, como Google Authenticator or Authy. O aplicativo fornecerá senhas de uso único (OTPs) para usar ao assinar. Cada OTP é válido por 30 segundos.
Opcional: Converta seu certificado de assinatura de documento OV em um certificado de selagem
Observação: Esta seção é apenas para usuários que desejam fazer selagem. Para automatizar a assinatura de documentos e não serem solicitados por senhas de uso único (OTP), os usuários convertem automaticamente seu certificado de assinatura de documento de validação da organização (OV) em um certificado esealing em suas contas SSL.com. Observe que um certificado de assinatura de documento de Validação Individual (IV) não pode ser convertido para selo eletrônico. As instruções para conversão de vedação são detalhadas abaixo:
- Clique Encomendas no menu superior da sua conta SSL.com.
- Localize seu certificado e clique no botão download / detalhes link.
- Clique na REMOVER 2FA botão.
Instalar Postman e importar coleções de API
As instruções nesta seção são apenas para usuários do Postman. Se estiver usando cURL com a API CSC, você pode seguir para a próxima seção.
- Baixe e descompacte o Coleção CSC API Postman e a Coleção Postman da Document Signing API (Vejo https://www.postman.com/sslcom para coleções de API SSL.com online).
- Baixe e instale o Cliente Postman REST.
- Inicie o Postman e, em seguida, crie uma nova conta do Postman ou entre em uma existente.
- Clique na Importar botão.
- Clique na Fazer upload de arquivos botão, navegue até os arquivos de coleção de API descompactados (
csc-api-prod.postman_collection.jsone adocument-signing-api-prod.postman_collection.json) e abri-los.
- Clique na Importar botão.
- As solicitações de API com as quais você trabalhará agora estão disponíveis no Coleções guia no lado esquerdo da janela do Postman.
Recuperar token de acesso
A próxima etapa é recuperar um token de acesso de SSL.com. Você vai precisar do seu ID do cliente disponível, bem como o nome de usuário e a senha da sua conta SSL.com. Os tokens de acesso são válidos por uma hora após sua emissão.
Use as guias clicáveis abaixo para escolher as instruções para Postman ou cURL:
- Selecione uma solicitação de API da coleção CSC API.
- Selecione os Autorização Guia e selecione OAuth2.0 do Formato menu.
- Insira as seguintes informações no formulário:
- Prefixo do cabeçalho:
Bearer - Nome do Token:
SSLCOM CSC(ou qualquer outro nome fácil de lembrar de sua preferência) - Tipo de concessão:
Authorization Code - URL de retorno de chamada:
https://upload.esigner.com - Autorizar usando o navegador: não verificado
- URL de autenticação:
https://login.ssl.com/oauth2/authorizepara ambiente de Produção;https://oauth-sandbox.ssl.com/oauth2/authorizepara ambiente Sandbox. - URL do token de acesso:
https://login.ssl.com/oauth2/tokenpara ambiente de Produção;https://oauth-sandbox.ssl.com/oauth2/tokenpara ambiente Sandbox. - ID do Cliente: [Seu ID de cliente]
- Segredo do Cliente: [Seu segredo de cliente]
- Escopo:
service - Estado: [deixe em branco]
- Autenticação de cliente:
Send as Basic Auth header
Quando terminar, clique no Obtenha um novo token de acesso botão.
- Prefixo do cabeçalho:
- Um formulário de login aparecerá. Digite seu nome de usuário e senha SSL.com e clique no botão Acesso de Membros botão.
- 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 reutilizá-lo em solicitações do Postman, mas descobrimos que é mais confiável copiar e colar o token diretamente em cada solicitação.
- Use o seguinte comando para solicitar um token de acesso. Substitua os valores mostrados em MAIÚSCULAS pelos seus valores reais:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id" : "SEU -CLIENT-ID", "client_secret" : "SEU-CLIENTE-SECRET", "grant_type" : "senha", "username" : "SEU-USERNAME", "senha" : "SUA-SENHA" }' - Você deve receber um objeto JSON contendo um token de acesso e um token de atualização. Copie o valor do token de acesso para colar em suas solicitações de API. Você não precisará do token de atualização para esses exemplos.
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 conduzirá pelas cinco solicitações disponíveis na coleção Postman CSC, resultando na criação de uma assinatura digital a partir de um hash de documento.
- Uma biblioteca PDF é necessária para manipular o PDF para entrada de hash e posteriormente incorporar o PKCS#7 no documento PDF. (ex. ApachePDFBox em Java).
- Uma biblioteca Crypto para criar PKCS#7 a partir de assinaturas brutas recebidas da API eSigner (ex. BouncyCastle em Java).
Obtenha informações do CSC (opcional)
- 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.
- As informações sobre o serviço de assinatura em nuvem aparecerão em um objeto JSON no Postman's Resposta campo.
- Use o seguinte comando para obter informações sobre o serviço CSC API do SSL.com. Se você estiver em um ambiente sandbox, use
https://cs-try.ssl.com/csc/v0/infoao invés.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}" - Você receberá um objeto JSON com detalhes sobre o serviço:
Lista de Credenciais CSC
O Plano de Ação Global para Saúde Mental XNUMX-XNUMX da Lista de Credenciais CSC request irá recuperar uma credencial que você usará em solicitações de API posteriores.
- Selecionar Lista de Credenciais CSC E clique no Autorização aba.
- Escolha Símbolo do portador do Formato menu, cole seu token de acesso no Token campo e clique no ENVIAR botão.
- 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.
- Digite o seguinte comando. (Substitua MY-ACCESS-TOKEN pelo seu token de acesso real). Se você estiver em um ambiente sandbox, use
https://cs-try.ssl.com/csc/v0/credentials/listem vez de:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Autorização: Bearer MY- TOKEN DE ACESSO "\ --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.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Autorização: Portador MY- ACCESS-TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}' - Você deve receber um objeto JSON com uma lista de IDs de credenciais associados ao usuário. Sua lista provavelmente conterá um valor. Copie e cole seu ID de credencial em um editor de texto para uso em solicitações posteriores.
Informações de credenciais do CSC (opcional)
O Plano de Ação Global para Saúde Mental XNUMX-XNUMX 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.
- Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
- Selecione os Corpo guia e cole seu ID de credencial como o valor para
credentialID.
- Clique na ENVIAR botão.
- Um objeto JSON com sua cadeia de certificados de assinatura e outras informações aparecerão no Resposta campo.
- Digite o seguinte comando. Se você estiver no ambiente sandbox, use
https://cs-try.ssl.com/csc/v0/credentials/infoSubstituirMY-ACCESS-TOKENe aMY-CREDENTIAL-IDcom suas informações reais:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Autorização: Portador MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": true, "authInfo": true }' - Você deve receber um objeto JSON com sua cadeia de certificados de assinatura e outras informações:
Autorizar credenciais
O Plano de Ação Global para Saúde Mental XNUMX-XNUMX 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.
- Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
- Selecione os Corpo aba. Cole seu ID de credencial como o
credentialIDvalor e um hash do documento que você deseja assinar como ohashvalor. Recupere e insira um OTP de seu aplicativo de autenticação e insira-o como o valor paraOTP, Então clique no ENVIAR botão. Nota: OTP não é necessário para certificados de selagem.
- 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.
- Use o seguinte comando. Substituir
MY-ACCESS-TOKEN,MY-CREDENTIAL-IDeMY-HASHcom suas informações reais. Obtenha uma senha única de seu aplicativo 2FA e use-a como o valor paraMY-OTP. Nota: OTP não é necessário para certificados de selagem.
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP " }' - Você deve receber um objeto JSON com seus Dados de Ativação de Assinatura (SAD). Copie e cole esse valor em um editor de texto para usar na solicitação de assinatura hash.
Assinar Hash
Agora você está pronto para assinar o hash do documento.
- Selecionar Assinar Hash da coleção e, em seguida, selecione o Autorização aba.
- Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
- Selecione os Corpo aba. Cole seu ID de credencial como o
credentialIDvalor, seus dados de ativação de assinatura como oSADvalor, e um hash do documento que você deseja assinar como ohashvalor e clique no ENVIAR botão.
- Um objeto JSON com sua assinatura aparecerá no Resposta campo.
- Digite o seguinte comando. Substituir
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SADeMY-HASHcom suas informações reais:
curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Autorização: Portador MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }' - Você deve receber um objeto JSON contendo sua assinatura.
Assine um PDF
Além de assinar hashes de documentos, você também pode fazer upload e assinar um arquivo PDF.
Ao assinar um PDF, você trabalhará com duas solicitações POST:
- 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
- Selecione os Carregar documento PDF solicitar e clicar no Autorização aba.
- Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
- Selecione os Cabeçalhos guia e cole seu ID de credencial no Valor coluna.
- Selecione os Corpo guia e clique no × próximo de
hello.pdfpara remover este nome de arquivo de espaço reservado.
- Clique na Selecione o arquivo e navegue até o arquivo que deseja enviar.
- Clique na ENVIAR botão.
- Selecione e copie o
idvalor na resposta para usar na próxima solicitação.
- Use o seguinte comando. Substituir
MY-CREDENTIAL-ID,MY-ACCESS-TOKENe/PATH/TO/FILE.pdfcom suas informações reais:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Autorização: Bearer MY- ACCESS-TOKEN "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
- Você receberá um objeto JSON com um valor para
id. Copie este valor para usar na próxima solicitação.
Observação: para assinaturas visíveis, consulte os seguintes cabeçalhos de solicitação HTTP (/v1/pdf/upload):
|
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
Agora você pode assinar o PDF.
- Selecione os Carregar documento PDF solicitar e clicar no Autorização aba.
- Escolha Símbolo do portador do Formato menu e cole seu token de acesso no Token campo.
- Selecione a guia Corpo, cole no
idvalor da etapa anterior e um OTP do seu aplicativo de autenticação, em seguida, clique no ENVIAR botão.
- 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.
- Abra o arquivo no Acrobat para confirmar se o arquivo foi assinado.
- Digite o seguinte comando. Substituir
MY-CREDENTIAL-ID,MY-FILE-IDeOUTPUT-FILENAMEcom suas informações reais. Obtenha uma senha única (OTP) de seu aplicativo 2FA e insira-a comoMY-OTP. Nota: OTP não é necessário para certificados de selagem:
curl --location --request POST 'https://ds.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"} '\ - -output OUTPUT-FILENAME - cURL irá baixar o arquivo assinado e salvá-lo com o nome de arquivo que você especificou:
- Abra o PDF no Acrobat ou Acrobat Reader para verificar se a assinatura é válida.
