Firma remota de documentos con eSigner CSC API

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

Puede omitir esta sección si ya tiene un certificado de firma de documentos emitido. Si este es el caso, continúe con la siguiente sección que trata sobre cómo inscribir su certificado en eSigner.

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

Si desea omitir la creación de una cuenta de Sandbox y un pedido de prueba, también puede probar eSigner Sandbox con una cuenta de demostración y un certificado. Por favor lee Certificados y credenciales de demostración de eSigner para obtener credenciales e información de configuración.
  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 .
    Panel de pruebas
  2. Haga clic herramientas para desarrolladores.
    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 .
    enlace de detalles
  6. Haga clic 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.
    editar registrante
  7. Agregue la información del solicitante para el certificado de prueba, luego haga clic en el Siguiente >> del botón.
    información del aplicante
  8. Ingrese la información del destinatario, luego haga clic en el Siguiente >> del botón.
    recipiente de información
  9. Haga clic en el omitir para omitir la carga de documentos de validación para el certificado de prueba.
    Botón de salto
  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.
    Validación pendiente

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

  1. 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.
    Localizar orden
  2. Haga clic en el pedido detalles .
    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.
    Crear PIN
  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.
    Código QR
  5. 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.
    OTP en Authy
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.

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:

  1. Haga clic Mis Pedidos en el menú superior de su cuenta SSL.com. 
  2. Localice su certificado y haga clic en descarga / detalles .
  3. Haga clic en el 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.

  1. 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).
    Colecciones de cartero
  2. Descargue e instale el Cliente REST de cartero.
    Descarga del cliente Postman REST
  3. Inicie Postman, luego cree una nueva cuenta de Postman o inicie sesión en una existente.
    Cartero Iniciar sesión
  4. Haga clic en el Importa del botón.
    Botón Importar
  5. Haga clic en el Cargar archivos , navegue hasta los archivos de colección de API descomprimidos (csc-api-prod.postman_collection.json y document-signing-api-prod.postman_collection.json) y ábralos.
    Cargar archivos
  6. Haga clic en el Importa del botón.
    Haga clic en el botón de importación
  7. 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.
    Solicitudes API

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
  1. Seleccione una solicitud de API de la colección de API de CSC.
    seleccionar solicitud de API
  2. Seleccione la pestaña Autorización pestaña y seleccione OAuth 2.0 del desplegable Tipo de Propiedad .
    Pestaña de autorización
  3. 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.
    Obtener un nuevo token de acceso

  4. 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.
    Iniciar sesió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 las solicitudes de Postman, pero hemos descubierto que es más confiable copiar y pegar el token directamente en cada solicitud.
    El acceso de emergencia
  1. 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" }'
  2. 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.
    Recuperar token de acceso

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 debe utilizar el algoritmo SHA 256 para calcular el hash del documento PDF. 

  1. 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). 
  2. 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)

Instrucciones del carteroInstrucciones de cURL
  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.
    Enviar solicitud de información CSC
  2. La información sobre el servicio de firma en la nube aparecerá en un objeto JSON en Postman. Respuesta campo.
    Información CSC
  1. 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 "{}"
  2. Recibirás un objeto JSON con detalles sobre el servicio:
    Obtener información de CSC

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
  1. Seleccione Lista de credenciales de CSC Y haga clic en el Autorización .
    Pestaña de 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.
    Enviar solicitud de lista de credenciales
  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.
    ID de credenciales
  1. 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"}'
  2. 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.
    ID de credenciales

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
  1. Para utilizar esta solicitud, seleccione Información de credenciales de CSC de la colección y haga clic en el Autorización .
    pestaña de autorización
  2. Elige Token de portador del desplegable Tipo de Propiedad menú, luego pegue su token de acceso en el Token campo.
    Pegar token
  3. Seleccione la pestaña Cuerpo pestaña, luego pegue su ID de credencial como el valor para credentialID.
    Pegar ID de credencial
  4. Haga clic en el Enviar del botón.
    Enviar
  5. Un objeto JSON con su cadena de certificados de firma y otra información aparecerá en el Respuesta campo.
    Información de credenciales
  1. Ingrese el siguiente comando. Si está en el entorno de la caja de arena, use https://cs-try.ssl.com/csc/v0/credentials/info  Reemplaza MY-ACCESS-TOKEN y MY-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 }'
  2. Debería recibir un objeto JSON con su cadena de certificados de firma y otra información:
    Información de credenciales de CSC

Autorización de credenciales

El Autorización de credenciales request recuperará la autorización para firmar un hash.

Instrucciones del carteroInstrucciones de cURL
  1. Comience seleccionando Autorización de credenciales de la colección y haciendo clic en el Autorización .
    Pestaña de autorización
  2. Elige Token de portador del desplegable Tipo de Propiedad menú, luego pegue su token de acceso en el Token campo.
    pegar token
  3. Seleccione la pestaña 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 botón. Nota: No se requiere OTP para sellar certificados.
    Pestaña cuerpo
  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.
    SAD
  1. Utilice el siguiente comando. Reemplazar MY-ACCESS-TOKEN, MY-CREDENTIAL-IDy MY-HASH con su información real. Obtenga una contraseña de un solo uso de su aplicación 2FA y utilícela como valor para MY-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 "}'
  2. 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.
    Autorización de credenciales

Signo hash

Ahora está listo para firmar el hash del documento.

Instrucciones del carteroInstrucciones de cURL
  1. Seleccione Signo hash de la colección, luego seleccione el Autorización .
    Pestaña de autorización
  2. Elige Token de portador del desplegable Tipo de Propiedad menú, luego pegue su token de acceso en el Token campo.
    Pegar token
  3. Seleccione la pestaña 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.
    Pestaña cuerpo
  4. Un objeto JSON con su firma aparecerá en el Respuesta campo.
    Firma
  1. Ingrese el siguiente comando. Reemplazar MY-ACCESS-TOKENMY-CREDENTIAL-ID, MY-SADy MY-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" }'
  2. Debería recibir un objeto JSON que contenga su firma.
    Firmar hash

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

Colección de API de firma de documentos

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
  1. Seleccione la pestaña Cargar documento PDF solicitud y haga clic en el Autorización .
    Pestaña de autorización
  2. Elige Token de portador del desplegable Tipo de Propiedad menú, luego pegue su token de acceso en el Token campo.
    Pegar token
  3. Seleccione la pestaña Cabezales pestaña y pegue su ID de credencial en la Valor columna.
    Pestaña encabezados
  4. Seleccione la pestaña Cuerpo ficha y haga clic en el × al lado de hello.pdf para eliminar este nombre de archivo de marcador de posición.
    eliminar nombre de archivo de ejemplo
  5. Haga clic en el Seleccione Archivo , luego navegue hasta el archivo que desea cargar.
    Seleccione el archivo
  6. Haga clic en el Enviar del botón.
    Enviar
  7. Seleccione y copie el id valor en la respuesta para usar en la próxima solicitud.
    ID
  1. Utilice el siguiente comando. Reemplazar MY-CREDENTIAL-ID, MY-ACCESS-TOKENy /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 "
  2. Recibirás un objeto JSON con un valor de id. Copie este valor para usarlo en la siguiente solicitud.
    Subir PDF

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.

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
  1. Seleccione la pestaña Cargar documento PDF solicitud y haga clic en el Autorización .
       Autorización
  2. Elige Token de portador del desplegable Tipo de Propiedad menú, luego pegue su token de acceso en el Token campo.
    Pegar token
  3. 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.
    Enviar consulta
  4. 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.
    Guardar PDF en archivo
  5. Abra el archivo en Acrobat para confirmar que se ha firmado.
    Firma válida
  1. Ingrese el siguiente comando. Reemplazar MY-CREDENTIAL-ID, MY-FILE-IDy OUTPUT-FILENAME con su información real. Obtenga una contraseña de un solo uso (OTP) de su aplicación 2FA e introdúzcala como MY-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
  2. cURL descargará el archivo firmado y lo guardará con el nombre de archivo que especificó:
    Firmar PDF
  3. Abra el PDF en Acrobat o Acrobat Reader para verificar que la firma sea válida.
    Firma válida

Twitter
Facebook
Etiqueta LinkedIn
Reddit
Correo electrónico

Manténgase informado y seguro

SSL.com es líder mundial en ciberseguridad, PKI y certificados digitales. Regístrese para recibir las últimas noticias, consejos y anuncios de productos de la industria de SSL.com.

Nos encantaría recibir tus comentarios

Responda nuestra encuesta y háganos saber lo que piensa sobre su compra reciente.