Guía de integración para probar la firma remota de documentos con eSigner CSC API

Esta guía lo guiará a través de la firma de un documento hash y un archivo PDF con SSL.com firmante electrónico servicio de firma en la nube y la API Cloud Signature Consortium (CSC). Todos los ejemplos de solicitud de API se mostrarán con Cartero, y recomendamos instalar el Aplicación de escritorio Postman en su computadora si desea trabajar con los ejemplos. También se incluyen ejemplos de comandos cURL de las solicitudes de API.

Crear una orden de prueba

1. Primero, deberá crear una orden de firma de documentos en el Sandbox. Empiece por iniciar sesión en su cuenta de Sandbox y vaya al Panel De Control .
   
2. Haga Clic en herramientas para desarrolladores.
   
3. Seleccione Firma de documentos eSigner, A continuación, haga clic en el Crear orden de prueba del botón.
   
4. Un cuadro de diálogo aparecerá. Haga clic en el OK del botón.
   
5. Busque su pedido de prueba, luego haga clic en el detalles .
   
6. Haga Clic en editar registrante para comenzar a ingresar la información del solicitante y el destinatario para su pedido de prueba. Tenga en cuenta que, dado que esta información no se utilizará para emitir un certificado de firma de documento válido, puede ingresar información ficticia si lo desea.
   
7. Agregue la información del solicitante para el certificado de prueba, luego haga clic en el Siguiente >> del botón.
   
8. Ingrese la información del destinatario, luego haga clic en el Siguiente >> del botón.
   
9. Haga clic en el omitir para omitir la carga de documentos de validación para el certificado de prueba.
   
10. Su pedido de prueba ahora debería tener un estado de Validación pendiente. Póngase en contacto con el equipo de soporte de SSL.com en Support@SSL.com para que su certificado de prueba sea validado.
    

Inscríbase en eSigner y configure la autenticación de dos factores

1. Una vez que su pedido de prueba haya sido validado por el personal de soporte de SSL.com, puede inscribirlo en eSigner. Navega al Mis Pedidos pestaña en su cuenta de zona de pruebas de SSL.com y localice su pedido de prueba.
   
2. Haga clic en el pedido detalles .
   
3. Cree y confirme un PIN de 4 dígitos, luego haga clic en el crear PIN del botón.
   
   Si necesita restablecer su PIN de eSigner, lea este tutorial.
   
4. Aparecerá un código QR.
   
   La próxima vez que vuelva a cargar la página, el código QR no será visible. Si necesita ver o restablecer su código QR de eSigner, lea este tutorial.
   
5. Escanee el código en una aplicación de autenticación de 2 factores en su dispositivo móvil, como Google Authenticator o Authy. La aplicación le proporcionará contraseñas de un solo uso (OTP) para usar al firmar. Cada OTP es válida por 30 segundos.
   

Instalar Cartero e importar colección de API de CSC

1. Descargue y descomprima el Colección CSC API Postman (consulta: https://www.postman.com/sslcom/workspace/public/collection/3420801-f2df0995-1293-45da-8719-73467c9f0ca7?ctx=documentation para obtener los últimos puntos finales de API o descargas de colecciones).
   
2. Descargue e instale el Cliente REST de cartero.
   
3. Inicie Postman, luego cree una nueva cuenta de Postman o inicie sesión en una existente.
   
4. Haga clic en el Importa del botón.
   
5. Haga clic en el Cargar archivos , navegue hasta el archivo de recopilación de API descomprimido (CSC-API.postman_collection.json) y ábralo.
   
6. Haga clic en el Importa del botón.
   
7. Haga clic en el Colecciones pestaña en Postman y expanda la colección de API de CSC para ver las cinco solicitudes POST con las que trabajará:
   • Información CSC
   • Lista de credenciales de CSC
   • Información de credenciales de CSC
   • Autorización de credenciales
   • Signo hash

   

Recuperar token de acceso

1. El siguiente paso es recuperar un token de acceso de SSL.com. Antes de solicitar su token de acceso, necesitará un ID de cliente (también conocido como ID de aplicación. Por favor refiérase a este tutorial para obtener instrucciones sobre cómo generar esta credencial).
2. Seleccione Autorización seleccione OAuth 2.0 del desplegable Tipo de Propiedad menú y haga clic en el Obtener un nuevo token de acceso del botón.
   
3. Ingrese la siguiente información en el formulario:
   • Nombre del token: SandBox CSC (o cualquier otro nombre fácil de recordar que prefiera)
   • Tipo de subvención: Código de Autorización
   • URL de devolución de llamada: [dejar en blanco]
   • Autorizar usando el navegador: comprobado
   • URL de autenticación: https://oauth-sandbox.ssl.com/oauth2/authorize
   • URL del token de acceso: https://oauth-sandbox.ssl.com/oauth2/token
   • Identificación del cliente: [Su ID de cliente]
   • Secreto del cliente: [Su secreto de cliente]
   • Alcance: de coches
   • Localidad: [dejar en blanco]
   • Autenticación del cliente: Enviar como encabezado de autenticación básica

   Cuando haya terminado, haga clic en el Token de solicitud del botón.
   

4. Aparecerá un formulario de inicio de sesión en su navegador web. Ingrese su nombre de usuario y contraseña de SSL.com, luego haga clic en el Inicio de Sesión para Miembros del botón.
   
5. Su nuevo token de acceso debería aparecer en Postman. Seleccione el texto del token de acceso y cópielo en el portapapeles, luego cierre el Administrar tokens de acceso caja de diálogo. Pegue su token de acceso en un editor de texto donde pueda acceder a él fácilmente. Cada token de acceso caducará después de una hora.
   
   También puede guardar su token para reutilizarlo en Cartero solicitudes, pero hemos descubierto que es más confiable copiar y pegar el token directamente en cada solicitud.
   

Firmar un hash

Ahora que tiene un token de acceso, puede comenzar a realizar solicitudes de API y crear firmas. Esta sección lo guiará a través de las cinco solicitudes disponibles en el Colección Postman CSC, lo que da como resultado la creación de una firma digital a partir de un hash de documento.

Obtener información de CSC (opcional)

1. Puede utilizar el Información CSC Solicite obtener información sobre el servicio de firma en la nube de SSL.com. Tenga en cuenta que, a diferencia de los demás de la colección, esta solicitud no requiere su token de acceso. Para enviar la solicitud, seleccione Información CSC del desplegable API de CSC colección, luego haga clic en el Enviar del botón.
   
2. La información sobre el servicio de firma en la nube aparecerá en un objeto JSON en Postman. Respuesta campo.
   

Comando cURL

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

Lista de credenciales de CSC

1. El Lista de credenciales de CSC request recuperará una credencial que utilizará en solicitudes de API posteriores. Seleccione Lista de credenciales de CSC Y haga clic en el Autorización .
   
2. Elige Token de portador del desplegable Tipo de Propiedad menú, pegue su token de acceso en el Token campo, luego haga clic en el Enviar del botón.
   
3. Un objeto JSON con una lista de ID de credenciales asociados con el usuario aparecerá en el Respuesta campo. Su lista probablemente contendrá un valor. Copie y pegue su ID de credencial en un editor de texto para usarlo en solicitudes posteriores.
   

Comando cURL

Reemplaza MY-ACCESS-TOKEN con su token de acceso real:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Autorización: Portador MI TOKEN DE ACCESO "\ --data-raw" {} "

Si utiliza un certificado eseal (certificado de firma de documentos con solo información de la organización; incluido con su cuenta gratuita de esigner.com), incluya “clientData”: “DS_ESEAL” (nota: los eseals no requieren autenticación OTP). Otras opciones para "clientData" son "EVCS" para la firma de código EV y "DS" (predeterminado) para la firma de documentos IV o IV + OV:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Autorización: Portador MY-ACCESS-TOKEN "\ --data-raw" {\ "clientData \": \ "DS_ESEAL \"} "

Información de credenciales de CSC (opcional)

1. El Información de credenciales de CSC La solicitud devolverá certificados y otra información asociada con una identificación de credencial, y no es necesaria para firmar. Para utilizar esta solicitud, seleccione Información de credenciales de CSC de la colección y haga clic en el Autorización .
   
2. Elige Token de portador del desplegable Tipo de Propiedad menú, luego pegue su token de acceso en el Token campo.
   
3. Seleccione Cuerpo pestaña, luego pegue su ID de credencial como el valor para credentialID.
   
4. Haga clic en el Enviar del botón.
   
5. Un objeto JSON con su cadena de certificados de firma y otra información aparecerá en el Respuesta campo.
   

Comando cURL

Reemplaza MY-ACCESS-TOKEN y MY-CREDENTIAL-ID con su información real:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/info" \ --header "Tipo de contenido: application / json" \ --header "Autorización: Portador MY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \": \ "MI-ID-CREDENCIAL \", \ "certificados \": \ "cadena \", \ "certInfo \": verdadero, \ "authInfo \": verdadero} "

Autorización de credenciales

1. El Autorización de credenciales request recuperará la autorización para firmar un hash. Comience seleccionando Autorización de credenciales de la colección y haciendo clic en el Autorización .
   
2. Elige Token de portador del desplegable Tipo de Propiedad menú, luego pegue su token de acceso en el Token campo.
   
3. Seleccione Cuerpo lengüeta. Pegue su ID de credencial como credentialID valor y un hash del documento que desea firmar como el hash valor. Recupere e ingrese una OTP desde su aplicación de autenticación e introdúzcala como valor para OTP, A continuación, haga clic en el Enviar del botón.
   
4. Aparecerá un objeto JSON con sus datos de activación de firma (SAD) en el Respuesta campo. Copie y pegue este valor en un editor de texto para usarlo en la solicitud de firma hash.
   

Comando cURL

Reemplaza MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-HASHy MY-OTP con su información real:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/authorize" \ --header "Tipo de contenido: application / json" \ --header "Autorización: Portador MY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \": \ "MY-CREDENTIAL-ID \", \ "numSignatures \": 1, \ "hash \": [\ "MY-HASH \ "], \" OTP \ ": \" MI-OTP \ "}"

Signo hash

1. Ahora estamos listos para firmar el hash del documento. Seleccione Signo hash de la colección, luego seleccione el Autorización .
   
2. Elige Token de portador del desplegable Tipo de Propiedad menú, luego pegue su token de acceso en el Token campo.
   
3. Seleccione Cuerpo lengüeta. Pegue su ID de credencial como credentialID valor, sus Datos de activación de firma como el SAD valor y un hash del documento que desea firmar como el hash valor, luego haga clic en el Enviar del botón.
   
4. Un objeto JSON con su firma aparecerá en el Respuesta campo.
   

Comando cURL

Reemplaza MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SADy MY-HASH con su información real:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/signatures/signHash" \ --header "Tipo de contenido: application / json" \ --header "Autorización: Portador MY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \": \ "MI-ID-CREDENCIAL \", \ "TRISTE \": \ "MI-TRISTE \", \ "hash \": [\ "MY-HASH \"], \ "signAlgo \": \ "1.2.840.113549.1.1.11 \"} "

Firmar un PDF

Además de firmar hashes de documentos, también puede cargar y firmar un archivo PDF. Empiece por descargar e importar el Colección Postman de la API de firma de documentos (consulta: https://www.postman.com/sslcom/workspace/public/collection/3454644-277d8427-f749-4a94-93bf-c3478b79b999?ctx=documentation para los últimos puntos finales de API y descargas de colecciones), siguiendo el mismo Pasos de instalación que siguió anteriormente para la colección de API de CSC.

• Cargar documento PDF
• Firmar documento PDF

Puede reutilizar la credencial que recuperó anteriormente con el Lista de credenciales de CSC solicitud. Probablemente también necesitará recuperar un nuevo Token de acceso.

Cargar documento PDF

1. Seleccione Cargar documento PDF solicitud y haga clic en el Autorización .
   
2. Elige Token de portador del desplegable Tipo de Propiedad menú, luego pegue su token de acceso en el Token campo.
   
3. Seleccione Cabezales pestaña y pegue su ID de credencial en la Valor columna.
   
4. Seleccione Cuerpo ficha y haga clic en el × al lado de hello.pdf para eliminar este nombre de archivo de marcador de posición.
   
5. Haga clic en el Seleccione Archivo , luego navegue hasta el archivo que desea cargar.
   
6. Haga clic en el Enviar del botón.
   
7. Seleccione y copie el id valor en la respuesta para usar en la próxima solicitud.
   

comando cURL

Reemplaza MY-CREDENTIAL-ID, MY-ACCESS-TOKENy /PATH/TO/FILE.pdf con su información real:

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Autorización: Portador MY-ACCESS-TOKEN "\ --header" Tipo de contenido: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "

Nota: Para ver las firmas visibles, consulte los siguientes encabezados de solicitud HTTP (/v1/pdf/upload):

Firmar documento PDF

1. Ahora puede firmar el PDF. Selecciona el Cargar documento PDF solicitud y haga clic en el Autorización .
     
2. Elige Token de portador del desplegable Tipo de Propiedad menú, luego pegue su token de acceso en el Token campo.
   
3. Seleccione la pestaña Cuerpo y pegue el id valor del paso anterior.
   
4. Ingrese una OTP desde su aplicación de autenticación y haga clic en el Enviar del botón.
   
5. Los datos PDF aparecerán a continuación en el Respuesta campo. Escoger Guardar en un archivo del desplegable Guardar respuesta menú, luego asigne un nombre al archivo.
   
6. Abra el archivo en Acrobat para confirmar que se ha firmado. (Tenga en cuenta que en la captura de pantalla siguiente, la raíz de desarrollo RSA de SSL.com se ha confiado manualmente en Acrobat).
   

Comando cURL

Reemplaza MY-CREDENTIAL-ID, MY-FILE-IDy MY-OTP con su información real:

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/sign" \ --header "Content-Transfer-Encoding: application / json" \ --header "Tipo de contenido : application / json "\ --header" Autorización: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "id \": \ "MY-FILE-ID \", \ "otp \": \ "MI-OTP \"} "

 Puesta en marcha con producción

Para comenzar a funcionar, debe eliminar "-intentar" del subdominio. Por ejemplo, para poner en marcha ds-try.ssl.com, elimine "-try" para que el subdominio se convierta en ds.ssl.com.