Esta guía le mostrará cómo inscribir un pedido de certificado de firma de documentos con SSL.com firmante electrónico servicio y utilice la API de Cloud Signature Consortium (CSC) para firmar digitalmente un hash de documento y un archivo PDF. Puede utilizar esta guía con cURL or Cartero. Recomendamos que los usuarios de Postman instalen aplicación de escritorio por trabajar con los ejemplos. Los ejemplos de esta guía se aplican a los entornos de eSigner y eSealing de producción y prueba de SSL.com. Las diferencias en los comandos entre los modos de producción y prueba se explican en las siguientes secciones.
Para seguir estas instrucciones necesitará:
- Una orden de certificado de firma de documento validado. Por favor lee este tutorial para obtener instrucciones completas sobre pedidos y validación.
- A 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).
Solicite su certificado de firma de documentos SSL.com
Cómo solicitar un certificado en el entorno de producción
Consulte este artículo de la guía para obtener instrucciones sobre cómo solicitar un certificado de firma de documentos de producción: Proceso de pedido de certificados de firma de códigos y documentos
Cómo solicitar un certificado de prueba en el Sandbox de SSL.com
SSL.com ofrece un entorno Sandbox dedicado, que refleja nuestro portal SSL.com en vivo y la API SWS, para un espacio de experimentación sin riesgos. Esta configuración de "laboratorio" permite a los usuarios explorar y probar los servicios de SSL.com sin la preocupación de causar interrupciones o incurrir en costos reales.
El artículo, Uso de SSL.com Sandbox para pruebas e integración, lo ayudará a navegar el proceso de establecer una cuenta de Sandbox, iniciar un pedido de prueba e integrar Sandbox con la API de SWS.
Una vez que haya creado su certificado de prueba, comuníquese con el equipo de soporte de SSL.com para validarlo. Puede hacerlo haciendo clic en el botón de chat en línea en la esquina inferior derecha de la SSL.com sitio web o enviando un correo electrónico a soporte@ssl.com.
Inscríbase en eSigner y configure la autenticación de dos factores
Antes de poder comenzar a utilizar la API de CSC, deberá inscribirse en el servicio de firma en la nube eSigner de SSL.com. Los pedidos validados se pueden inscribir en eSigner siguiendo las instrucciones a continuación:
- . Navega hacia el Mis Pedidos en su cuenta de SSL.com y localice su pedido.
- Haga clic en el pedido detalles .
- 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. - 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. - Escanee el código en una aplicación de autenticación de 2 factores en su dispositivo móvil, como google Authenticator or 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.
Opcional: convierta su certificado de firma de documentos OV en un certificado de sellado
Nota: Esta sección es sólo para usuarios que quieran realizar eselling.. Para automatizar la firma de documentos y no recibir solicitudes de contraseñas de un solo uso (OTP), los usuarios autoconvierten su certificado de firma de documentos de Validación de organización (OV) en un certificado de sellado en sus cuentas SSL.com. Tenga en cuenta que un certificado de firma de documento de Validación Individual (IV) no se puede convertir para sellar. Las instrucciones para la conversión de sellado se detallan a continuación:
- Haga clic en Mis Pedidos en el menú superior de su cuenta SSL.com.
- Localice su certificado y haga clic en descarga / detalles .
- Haz clic en el botón QUITAR 2FA del botón.
Instalar Postman e Importar colecciones de API
Las instrucciones de esta sección son solo para usuarios de Postman. Si está utilizando cURL con la API de CSC, puede pasar a la siguiente sección.
- Descargue y descomprima el Colección CSC API Postman y Colección Postman de la API de firma de documentos (consulta: https://www.postman.com/sslcom para recopilaciones API de SSL.com en línea).
- Descargue e instale el Cliente REST de cartero.
- Inicie Postman, luego cree una nueva cuenta de Postman o inicie sesión en una existente.
- Haz clic en el botón Importar del botón.
- Haz clic en el botón Agregar archivo/s , navegue hasta los archivos de colección de API descomprimidos (
csc-api-prod.postman_collection.json
ydocument-signing-api-prod.postman_collection.json
) y ábralos.
- Haz clic en el botón Importar del botón.
- Las solicitudes de API con las que trabajará ahora están disponibles en el Colecciones pestaña en el lado izquierdo de la ventana Postman.
Recuperar token de acceso
El siguiente paso es recuperar un token de acceso de SSL.com. Necesitarás tu ID de cliente disponible, así como el nombre de usuario y la contraseña de su cuenta SSL.com. Los tokens de acceso son válidos durante una hora después de su emisión.
Utilice las pestañas en las que se puede hacer clic a continuación para elegir las instrucciones para Postman o cURL:
- Seleccione una solicitud de API de la colección de API de CSC.
- Seleccione el botón Autorización pestaña y seleccione OAuth 2.0 de la Type .
- Ingrese la siguiente información en el formulario:
- Prefijo de encabezado:
Bearer
- Nombre del token:
SSLCOM CSC
(o cualquier otro nombre fácil de recordar que prefiera) - Tipo de subvención:
Authorization Code
- URL de devolución de llamada:
https://upload.esigner.com
- Autorizar usando el navegador: desenfrenado
- URL de autenticación:
https://login.ssl.com/oauth2/authorize
para el entorno de producción;https://oauth-sandbox.ssl.com/oauth2/authorize
para el entorno Sandbox. - URL del token de acceso:
https://login.ssl.com/oauth2/token
para el entorno de producción;https://oauth-sandbox.ssl.com/oauth2/token
para el entorno Sandbox. - Identificación del cliente: [Su ID de cliente]
- Secreto del cliente: [Su secreto de cliente]
- Alcance:
service
- Localidad: [dejar en blanco]
- Autenticación del cliente:
Send as Basic Auth header
Cuando haya terminado, haga clic en el Obtener un nuevo token de acceso del botón.
- Prefijo de encabezado:
- Aparecerá un formulario de inicio de sesión. 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.
- 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 las solicitudes de Postman, pero hemos descubierto que es más confiable copiar y pegar el token directamente en cada solicitud.
- Utilice el siguiente comando para solicitar un token de acceso. Reemplace los valores mostrados en MAYÚSCULAS con sus valores reales:
curl --ubicación --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id" : "TU -ID-CLIENTE", "secret_cliente" : "TU-SECRETO-CLIENTE", "tipo_concesión" : "contraseña", "nombre de usuario" : "TU NOMBRE-USUARIO", "contraseña" : "TU-CONTRASEÑA" }'
- Debería recibir un objeto JSON que contiene un token de acceso y un token de actualización. Copie el valor del token de acceso para pegarlo en sus solicitudes de API. No necesitará el token de actualización para estos ejemplos.
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 la colección Postman CSC, lo que resulta en la creación de una firma digital a partir de un hash de documento.
- Se necesita una biblioteca PDF para manipular el PDF para la entrada hash y luego incrustar el PKCS#7 en el documento PDF. (por ejemplo, ApachePDFBox en Java).
- Una biblioteca Crypto para crear PKCS#7 a partir de firmas sin procesar recibidas de la API de eSigner (por ejemplo, BouncyCastle en Java).
Obtener información de CSC (opcional)
- 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 de la API de CSC colección, luego haga clic en el Enviar del botón.
- La información sobre el servicio de firma en la nube aparecerá en un objeto JSON en Postman. Respuesta campo.
- Utilice el siguiente comando para obtener información sobre el servicio API CSC de SSL.com. Si estás en un entorno sandbox, usa
https://cs-try.ssl.com/csc/v0/info
preferiblemente.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Tipo de contenido: application / json" \ --data-raw "{}"
- Recibirás un objeto JSON con detalles sobre el servicio:
Lista de credenciales de CSC
El Lista de credenciales de CSC request recuperará una credencial que utilizará en solicitudes de API posteriores.
- Seleccionar Lista de credenciales de CSC Y haga clic en el Autorización .
- Elegir Token de portador de la Type menú, pegue su token de acceso en el Token campo, luego haga clic en el Enviar del botón.
- 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.
- Ingrese el siguiente comando. (Reemplace MY-ACCESS-TOKEN con su token de acceso real). Si está en un entorno de sandbox, use
https://cs-try.ssl.com/csc/v0/credentials/list
en lugar:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Tipo de contenido: application / json" \ --header "Autorización: Portador MY- 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 --ubicación --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Autorización: Bearer MY- ACCESO-TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}'
- Debería recibir un objeto JSON con una lista de ID de credenciales asociados con el usuario. Su lista probablemente contendrá un valor. Copie y pegue su ID de credencial en un editor de texto para usar en solicitudes posteriores.
Información de credenciales de CSC (opcional)
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 .
- Elegir Token de portador de la Type menú, luego pegue su token de acceso en el Token campo.
- Seleccione el botón Cuerpo pestaña, luego pegue su ID de credencial como el valor para
credentialID
.
- Haz clic en el botón Enviar del botón.
- Un objeto JSON con su cadena de certificados de firma y otra información aparecerá en el Respuesta campo.
- Ingrese el siguiente comando. Si está en el entorno de la caja de arena, use
https://cs-try.ssl.com/csc/v0/credentials/info
ReemplazaMY-ACCESS-TOKEN
yMY-CREDENTIAL-ID
con su información real:
curl --ubicación --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Autorización: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": true, "authInfo": true }'
- Debería recibir un objeto JSON con su cadena de certificados de firma y otra información:
Autorización de credenciales
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 .
- Elegir Token de portador de la Type menú, luego pegue su token de acceso en el Token campo.
- Seleccione el botón Cuerpo lengüeta. Pegue su ID de credencial como
credentialID
valor y un hash del documento que desea firmar como elhash
valor. Recupere e ingrese una OTP desde su aplicación de autenticación e introdúzcala como valor paraOTP
, A continuación, haga clic en el Enviar botón. Nota: No se requiere OTP para sellar certificados.
- 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.
- Utilice el siguiente comando. Reemplazar
MY-ACCESS-TOKEN
,MY-CREDENTIAL-ID
yMY-HASH
con su información real. Obtenga una contraseña de un solo uso de su aplicación 2FA y utilícela como valor paraMY-OTP
. Nota: No se requiere OTP para sellar certificados.
curl --ubicación --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Autorización: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP "}'
- Debería recibir un objeto JSON con sus datos de activación de firma (SAD). Copie y pegue este valor en un editor de texto para usarlo en la solicitud de firma hash.
Signo hash
Ahora está listo para firmar el hash del documento.
- Seleccionar Signo hash de la colección, luego seleccione el Autorización .
- Elegir Token de portador de la Type menú, luego pegue su token de acceso en el Token campo.
- Seleccione el botón Cuerpo lengüeta. Pegue su ID de credencial como
credentialID
valor, sus Datos de activación de firma como elSAD
valor y un hash del documento que desea firmar como elhash
valor, luego haga clic en el Enviar del botón.
- Un objeto JSON con su firma aparecerá en el Respuesta campo.
- Ingrese el siguiente comando. Reemplazar
MY-ACCESS-TOKEN
,MY-CREDENTIAL-ID
,MY-SAD
yMY-HASH
con su información real:
curl --ubicación --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Autorización: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }'
- Debería recibir un objeto JSON que contenga su firma.
Firmar un PDF
Además de firmar hashes de documentos, también puede cargar y firmar un archivo PDF.
Al firmar un PDF, trabajará con dos solicitudes POST:
- 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
- Seleccione el botón Cargar documento PDF solicitud y haga clic en el Autorización .
- Elegir Token de portador de la Type menú, luego pegue su token de acceso en el Token campo.
- Seleccione el botón Cabezales pestaña y pegue su ID de credencial en la Value alto columna.
- Seleccione el botón Cuerpo ficha y haga clic en el × al lado de
hello.pdf
para eliminar este nombre de archivo de marcador de posición.
- Haz clic en el botón Seleccione Archivo , luego navegue hasta el archivo que desea cargar.
- Haz clic en el botón Enviar del botón.
- Seleccione y copie el
id
valor en la respuesta para usar en la próxima solicitud.
- Utilice el siguiente comando. Reemplazar
MY-CREDENTIAL-ID
,MY-ACCESS-TOKEN
y/PATH/TO/FILE.pdf
con su información real:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Autorización: Portador MY- TOKEN DE ACCESO "\ --header" Tipo de contenido: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
- Recibirás un objeto JSON con un valor de
id
. Copie este valor para usarlo en la siguiente solicitud.
Nota: Para ver las firmas visibles, consulte los siguientes encabezados de solicitud HTTP (/v1/pdf/upload):
Encabezado de solicitud |
Descripción |
---|---|
ID de credencial |
ID de credencial único asignado a la clave: obligatorio |
Motivo de la firma |
Agregue el motivo de la firma para agregar la apariencia de la firma y también en el diccionario de firmas: opcional, por ejemplo, apruebo este documento |
Firma-Ubicación |
Agregar ubicación de firma en el diccionario de firmas: opcional, por ejemplo, Houston, Texas |
Datos de contacto |
Agregue información de contacto en el diccionario de firmas: opcional, por ejemplo, número de teléfono |
Firma-Campo-Posición |
Posición del campo de firma donde se muestra la firma visual. el formato es “x,y,ancho,alto“ - Opcional |
Número de página |
Número de página donde dibujar la firma – Opcional |
Firma a mano |
Imagen PNG codificada en Base64 de la firma de la mano - Opcional |
Firmar documento PDF
Ahora puede firmar el PDF.
- Seleccione el botón Cargar documento PDF solicitud y haga clic en el Autorización .
- Elegir Token de portador de la Type menú, luego pegue su token de acceso en el Token campo.
- Seleccione la pestaña Cuerpo, pegue el
id
valor del paso anterior y una OTP de su aplicación de autenticación, luego haga clic en el Enviar del botón.
- Los datos PDF aparecerán a continuación en el Respuesta campo. Escoger Guardar en un archivo de la Guardar respuesta menú, luego asigne un nombre al archivo.
- Abra el archivo en Acrobat para confirmar que se ha firmado.
- Ingrese el siguiente comando. Reemplazar
MY-CREDENTIAL-ID
,MY-FILE-ID
yOUTPUT-FILENAME
con su información real. Obtenga una contraseña de un solo uso (OTP) de su aplicación 2FA e introdúzcala comoMY-OTP
. Nota: No se requiere OTP para sellar certificados:
curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Content-Transfer-Encoding: application / json' \ --header 'Content-Type: aplicación / json '\ --header' Autorización: Portador MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -salida OUTPUT-FILENAME
- cURL descargará el archivo firmado y lo guardará con el nombre de archivo que especificó:
- Abra el PDF en Acrobat o Acrobat Reader para verificar que la firma sea válida.