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 utilizan el entorno de eSigner y eSealing de producción de SSL.com. Si desea experimentar con la API de CSC en el entorno de prueba Sandbox de SSL.com antes de trabajar con pedidos de certificados reales, lea Guía de integración para probar la firma remota con eSigner CSC API. Si desea probar eSigner Sandbox con una cuenta de demostración y un certificado, lea Certificados y credenciales de demostración de eSigner para obtener credenciales e información de configuración.
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).
Inscríbase en eSigner y configure la autenticación de dos factores
- Antes de que pueda comenzar a utilizar la API de CSC, deberá inscribirse en eSigner. Navega al Mis Pedidos en su cuenta de SSL.com y localice su pedido.
- Haga clic en el pedido detalles del enlace.
- 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.
Consejo: Puede utilizar eSigner para compartir certificados de firma validados por la organización (OV) entre compañeros de equipo. Por favor lee Uso compartido en equipo para certificados de firma de código EV y documento eSigner para obtener instrucciones.
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.
- Haga clic en el Importa del botón.
- Haga clic en el Cargar archivos , navegue hasta los archivos de colección de API descomprimidos (
csc-api-prod.postman_collection.jsonydocument-signing-api-prod.postman_collection.json) y ábralos.
- Haga clic en el Importa 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:
Instrucciones del carteroInstrucciones de cURL
- Seleccione una solicitud de API de la colección de API de CSC.
- Seleccione la pestaña Autorización pestaña y seleccione OAuth 2.0 del desplegable Tipo .
- 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 - URL del token de acceso:
https://login.ssl.com/oauth2/token - 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 --solicitud POST "https://login.ssl.com/oauth2/token" \ --header "Tipo de contenido: aplicación/json" \ --data-raw '{
"client_id" : "TU-ID-CLIENTE",
"client_secret" : "TU-CLIENTE-SECRETO",
"grant_type": "contraseña",
"nombre de usuario": "TU NOMBRE DE 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.
Obtener información de CSC (opcional)
Instrucciones del carteroInstrucciones de cURL
- 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.
- 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 de CSC de SSL.com:
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.
Instrucciones del carteroInstrucciones de cURL
- Seleccione Lista de credenciales de CSC Y haga clic en el Autorización .
- Elija Token de portador del desplegable Tipo 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):
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.
Instrucciones del carteroInstrucciones de cURL
- Para utilizar esta solicitud, seleccione Información de credenciales de CSC de la colección y haga clic en el Autorización .
- Elija Token de portador del desplegable Tipo menú, luego pegue su token de acceso en el Token campo.
- Seleccione la pestaña Body pestaña, luego pegue su ID de credencial como el valor para
credentialID.
- Haga clic en el 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. Reemplazar
MY-ACCESS-TOKENyMY-CREDENTIAL-IDcon 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.
Instrucciones del carteroInstrucciones de cURL
- Comience seleccionando Autorización de credenciales de la colección y haciendo clic en el Autorización .
- Elija Token de portador del desplegable Tipo menú, luego pegue su token de acceso en el Token campo.
- Seleccione la pestaña Body lengüeta. Pegue su ID de credencial como
credentialIDvalor y un hash del documento que desea firmar como elhashvalor. 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-IDyMY-HASHcon 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.
Instrucciones del carteroInstrucciones de cURL
- Seleccione Signo hash de la colección, luego seleccione el Autorización .
- Elija Token de portador del desplegable Tipo menú, luego pegue su token de acceso en el Token campo.
- Seleccione la pestaña Body lengüeta. Pegue su ID de credencial como
credentialIDvalor, sus Datos de activación de firma como elSADvalor y un hash del documento que desea firmar como elhashvalor, 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-SADyMY-HASHcon 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
Instrucciones del carteroInstrucciones de cURL
- Seleccione la pestaña Cargar documento PDF solicitud y haga clic en el Autorización .
- Elija Token de portador del desplegable Tipo menú, luego pegue su token de acceso en el Token campo.
- Seleccione la pestaña Encabezados pestaña y pegue su ID de credencial en la Valor columna.
- Seleccione la pestaña Body ficha y haga clic en el × al lado de
hello.pdfpara eliminar este nombre de archivo de marcador de posición.
- Haga clic en el Seleccione Archivo , luego navegue hasta el archivo que desea cargar.
- Haga clic en el Enviar del botón.
- Seleccione y copie el
idvalor en la respuesta para usar en la próxima solicitud.
- Utilice el siguiente comando. Reemplazar
MY-CREDENTIAL-ID,MY-ACCESS-TOKENy/PATH/TO/FILE.pdfcon 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):
|
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.
No se requiere autorización de OTP cuando se firma con un certificado de firma de documento de esealing. Ignore todos los parámetros de OTP en la siguiente guía si utiliza un certificado de firma de documento de sellado.
Instrucciones del carteroInstrucciones de cURL
- Seleccione la pestaña Cargar documento PDF solicitud y haga clic en el Autorización .
- Elija Token de portador del desplegable Tipo menú, luego pegue su token de acceso en el Token campo.
- Seleccione la pestaña Cuerpo, pegue el
idvalor 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 del desplegable 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-IDyOUTPUT-FILENAMEcon 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.
