Acuerdo de Interfaz Firma Centralizada

Control de versiones
Versión Descripción Fecha Modificado por

2.0 Envió de OTP por correo electrónico 09/07/2020 Camilo Molina

2.1 Servicio de estampado de pdf 26/08/2020 Camilo Molina

Página 1 de 25
Acuerdo de Interfaz Firma Centralizada

Tabla de Contenido

1. Objetivo .............................................................................................................................. 4
2. Operaciones del servicio ..................................................................................................... 4
2.1 Autenticación ................................................................................................................... 4
2.1.1 Parámetros............................................................................................................... 4
2.1.2 Ejemplo JSON de entrada ........................................................................................ 4
2.1.3 Respuesta ................................................................................................................ 5
2.1.4 Ejemplo JSON de salida........................................................................................... 5
2.1.5 Valores para el atributo de codigoRespuesta ........................................................... 6
2.2 Firma digital..................................................................................................................... 6
2.2.1 Parámetros de entrada ............................................................................................. 6
2.2.2 Ejemplo JSON de entrada ........................................................................................ 9
2.2.3 Respuesta ................................................................................................................ 9
2.2.4 Ejemplo JSON de respuesta ...................................................................................10
2.3 Firma electrónica ............................................................................................................10
2.3.1 Parámetros de entrada ............................................................................................11
2.3.2 Ejemplo JSON de entrada .......................................................................................13
2.3.3 Respuesta ...............................................................................................................13
2.3.4 Ejemplo JSON de respuesta ...................................................................................14
2.4 Firma hash .....................................................................................................................14
2.4.1 Parámetros de entrada ............................................................................................15
2.4.2 Ejemplo JSON de entrada .......................................................................................15
2.4.3 Respuesta ...............................................................................................................15
2.4.4 Ejemplo JSON de respuesta ...................................................................................16
2.5 Obtener Certificado ........................................................................................................16
2.5.1 Parámetros de entrada ............................................................................................17
2.5.2 Ejemplo JSON de entrada .......................................................................................17
2.5.3 Respuesta ...............................................................................................................17
2.5.4 Ejemplo JSON de respuesta ...................................................................................18
2.6 Generar OTP ..................................................................................................................19

Página 2 de 25
Acuerdo de Interfaz Firma Centralizada

2.6.1 Parámetros de entrada ............................................................................................19

2.6.2 Ejemplo JSON de entrada .......................................................................................19
2.6.3 Respuesta ...............................................................................................................20
2.6.4 Ejemplo JSON de respuesta ...................................................................................20
2.7 Validar OTP....................................................................................................................20
2.7.1 Parámetros de entrada ............................................................................................21
2.7.2 Ejemplo JSON de entrada .......................................................................................21
2.7.3 Respuesta ...............................................................................................................21
2.7.4 Ejemplo JSON de respuesta ...................................................................................22
2.8 Estampar documento .....................................................................................................22
2.8.1 Parámetros de entrada ............................................................................................22
2.8.2 Ejemplo JSON de entrada .......................................................................................23
2.8.3 Respuesta ...............................................................................................................23
2.8.4 Ejemplo JSON de respuesta ...................................................................................23
3. Tabla de tipos de documento .............................................................................................24
4. Valores de respuesta para atributo codigoRespuesta ........................................................24

Página 3 de 25
Acuerdo de Interfaz Firma Centralizada

1. Objetivo

Este documento pretende describir de manera técnica y detallada el consumo del servicio
web para firma digital centralizada.

2. Operaciones del servicio

A continuación, se detallan las operaciones disponibles expuestas en un servicio en el

servicio de firma centralizada.

2.1 Autenticación

Operación POST para realizar la autenticación y obtener un token para el consumo de

las operaciones de firma.

URL Pruebas:
https://8uw10ruhfj.execute-api.us-east-2.amazonaws.com/qa/authentication/api/Login

URL Producción:
https://hdko60xft2.execute-api.us-east-2.amazonaws.com/pro/authentication/api/Login

2.1.1 Parámetros

Objeto JSON que debe cumplir con los siguientes atributos

Nombre Tipo Tamaño Obligatorio Descripción

Usuario para
Usuario Cadena 30 Si
autenticación

Clave Cadena 30 Si Clave del usuario

2.1.2 Ejemplo JSON de entrada

Página 4 de 25
Acuerdo de Interfaz Firma Centralizada

2.1.3 Respuesta

Como respuesta de la operación de autenticación se obtiene un JSON con la siguiente

estructura:

Nombre Tipo Tamaño Obligatorio Descripción

Código del resultado
codigoRespuesta Alfanumérico 3 Si
de la transacción

Código http del

httpStatus Numérico Si estado de la
transacción

Descripción del
descripcionRespuesta Alfanumérico max Si código de la
transacción

Especificación de
Listado
detalleRespuesta No inconsistencias en
Alfanumérico
los parámetros

Token para
token Alfanumérico max No
autenticación

2.1.4 Ejemplo JSON de salida

Página 5 de 25
Acuerdo de Interfaz Firma Centralizada

2.1.5 Valores para el atributo de codigoRespuesta

Código Descripción
RS1 Transacción exitosa, usuario
autenticado.
RS2 La estructura de la petición no
corresponde con la requerida.
RS3 Las credenciales son invalidas.
RS4 El cliente se encuentra inactivo.
RS5 Lo sentimos, ha ocurrido un error
interno y no pudimos completar tu
solicitud.

2.2 Firma digital

Operación POST que permite realizar la firma digital de un documento pdf con el envío
de un objeto JSON. Como resultado del firmado se obtendrá un objeto en formato JSON
con la respuesta de la transacción.
El método de acceso se realiza mediante Bearer Authentication el cual es un esquema
de autenticación http que involucra tokens de seguridad (Bearer Token), generado por el
servicio de autenticación.

URL Pruebas:
https://8uw10ruhfj.execute-api.us-east-2.amazonaws.com/qa/signature/api/sign/pades

URL Producción:
https://hdko60xft2.execute-api.us-east-2.amazonaws.com/pro/signature/api/sign/pades
2.2.1 Parámetros de entrada

Objeto JSON que debe cumplir con los siguientes atributos

Nombre Tipo Tamaño Obligatorio Descripción

Identificador del
numeroDocumento Alfanumérico 20 Si
certificado digital

clave Alfanumérico 15 Si Clave del certificado

Página 6 de 25
Acuerdo de Interfaz Firma Centralizada

Documento pdf a
base64 Alfanumérico 5 MB Si firmar codificado en
base64

Usuario de la tsa, es
obligatorio cuando se
usuarioTSA Alfanumérico 20 No
desea agregar marca
de tiempo en la firma

Clave de la tsa, es
obligatorio cuando se
claveTSA Alfanumérico 20 No
desea agregar marca
de tiempo en la firma

Campo razón del

razon Alfanumérico 30 No
detalle de la firma

Campo Ubicación del

ubicacion Alfanumérico 30
detalle de la firma

Indica si de desea
conLTV boolean Si marcar la firma como
LTV

Indica se coloca una

conEstampa boolean Si marca de tiempo en el
documento

Indica si de desea
firmaVisible boolean Si colocar la firma visible
en el documento pdf

Especifica las
imagenFirma ImagenFirma Si propiedades de la
firma visible

Página 7 de 25
Acuerdo de Interfaz Firma Centralizada

Objeto de entrada ImagenFirma

Nombre Tipo Tamaño Obligatorio Descripción

Posicionamiento en el
x float Si
eje Y de la imagen.

Posicionamiento en el
y float Si
eje Y de la imagen.

ancho float Si Ancho de la imagen

alto float Si Alto de la imagen

Imagen codificada en
imagen Alfanumérico MAX Si
base64

Página en la que se va
pagina int Si a posicionar la imagen
de la firma

Página 8 de 25
Acuerdo de Interfaz Firma Centralizada

2.2.2 Ejemplo JSON de entrada

2.2.3 Respuesta

Como respuesta de la operación firma digital se va a devolver un JSON con la siguiente

estructura:

Nombre Tipo Tamaño Obligatorio Descripción

Código de respuesta
codigoRespuesta Alfanumérico 5 Si obtenido del proceso
de firma

Descripción de la
mensaje Alfanumérico Si
respuesta

Código http del estado

httpStatus Numérico Si
de la transacción

Documento firmado y
documentoFirmado Alfanumérico MAX No
codificado en base64
Página 9 de 25
Acuerdo de Interfaz Firma Centralizada

2.2.4 Ejemplo JSON de respuesta

El siguiente es un ejemplo JSON con el response de la petición

2.3 Firma electrónica

Operación POST que permite realizar la firma electrónica de un documento pdf con el
envío de un objeto JSON. Como resultado del firmado se obtendrá un objeto en formato
JSON con la respuesta de la transacción.

El método de acceso se realiza mediante Bearer Authentication el cual es un esquema

de autenticación http que involucra tokens de seguridad (Bearer Token), generado por el
servicio de autenticación.

URL Pruebas:
https://8uw10ruhfj.execute-api.us-east-2.amazonaws.com/qa/signature/api/sign/firmaelectronica

URL Producción:
https://hdko60xft2.execute-api.us-east-2.amazonaws.com/pro/signature/api/sign/firmaelectronica

Página 10 de 25
Acuerdo de Interfaz Firma Centralizada

2.3.1 Parámetros de entrada

Objeto JSON que debe cumplir con los siguientes atributos

Nombre Tipo Tamaño Obligatorio Descripción
Documento pdf a
base64 Alfanumérico 5MB Si firmar codificado en
base64

Usuario de la tsa, es
obligatorio cuando se
usuarioTSA Alfanumérico 20 No
desea agregar marca
de tiempo en la firma

Clave de la tsa, es
obligatorio cuando se
claveTSA Alfanumérico 20 No
desea agregar marca
de tiempo en la firma

Campo razón del

razon Alfanumérico 30 No
detalle de la firma

Campo Ubicación del

ubicacion Alfanumérico 30
detalle de la firma

Indica se coloca una

conEstampa boolean Si marca de tiempo en
el documento

Indica si de desea
colocar la firma
firmaVisible boolean Si
visible en el
documento pdf

firmante Firmante Si Datos del firmante

Especifica las
imagenFirma ImagenFirma Si propiedades de la
firma visible

Página 11 de 25
Acuerdo de Interfaz Firma Centralizada

Objeto de entrada ImagenFirma

Nombre Tipo Tamaño Obligatorio Descripción

Posicionamiento en el
x float Si
eje Y de la imagen.

Posicionamiento en el
y float Si
eje Y de la imagen.

ancho float Si Ancho de la imagen

alto float Si Alto de la imagen

Imagen codificada en
imagen Alfanumérico MAX Si
base64

Página en la que se va
pagina int Si a posicionar la imagen
de la firma

Objeto de entrada Firmante

Nombre Tipo Tamaño Obligatorio Descripción
Identificador del
numeroDocumento Alfanumérico 20 Si
firmante

Código del tipo

tipoDocumento Numérico Si
documento

nombres Alfanumérico 50 Si Nombres del firmante

apellidos Alfanumérico 50 Si Apellidos del firmante

Correo electrónico
email Alfanumérico 40 No
del firmante

Página 12 de 25
Acuerdo de Interfaz Firma Centralizada

2.3.2 Ejemplo JSON de entrada

2.3.3 Respuesta

Como respuesta de la operación firma digital se va a devolver un JSON con la siguiente

estructura:

Nombre Tipo Tamaño Obligatorio Descripción

Código de respuesta
codigoRespuesta Alfanumérico 5 Si obtenido del proceso
de firma

Descripción de la
mensaje Alfanumérico Si
respuesta

Código http del estado

httpStatus Numérico Si
de la transacción

Documento firmado y
documentoFirmado Alfanumérico MAX No
codificado en base64
Página 13 de 25
Acuerdo de Interfaz Firma Centralizada

2.3.4 Ejemplo JSON de respuesta

El siguiente es un ejemplo JSON con el response de la petición

2.4 Firma hash

Operación POST que permite realizar la firma digital de un hash con el envío de un objeto
JSON. Como resultado del firmado se obtendrá un objeto en formato JSON con la
respuesta de la transacción.

El método de acceso se realiza mediante Bearer Authentication el cual es un esquema

de autenticación http que involucra tokens de seguridad (Bearer Token), generado por el
servicio de autenticación.

URL Pruebas:
https://8uw10ruhfj.execute-api.us-east-2.amazonaws.com/qa/signature/api/sign/hash

URL Producción:
https://hdko60xft2.execute-api.us-east-2.amazonaws.com/pro/signature/api/sign/hash

Página 14 de 25
Acuerdo de Interfaz Firma Centralizada

2.4.1 Parámetros de entrada

Objeto JSON que debe cumplir con los siguientes atributos

Nombre Tipo Tamaño Obligatorio Descripción

Identificador del
numeroDocumento Alfanumérico 20 Si
certificado digital

clave Alfanumérico 15 Si Clave del certificado

Hash del documento

hash Alfanumérico MAX Si
a firmar en base64

2.4.2 Ejemplo JSON de entrada

2.4.3 Respuesta

Como respuesta de la operación firma hash se va a devolver un JSON con la siguiente

estructura:

Nombre Tipo Tamaño Obligatorio Descripción

Código de respuesta
codigoRespuesta Alfanumérico 5 Si obtenido del proceso
de firma

Descripción de la
mensaje Alfanumérico Si
respuesta

Código http del estado

httpStatus Numérico Si
de la transacción

Página 15 de 25
Acuerdo de Interfaz Firma Centralizada

hash firmado y
hashFirmado Alfanumérico MAX No
codificado en base64

2.4.4 Ejemplo JSON de respuesta

2.5 Obtener Certificado

Operación POST que permite obtener el certificado en formato X509 junto con la cadena
de certificación.

El método de acceso se realiza mediante Bearer Authentication el cual es un esquema

de autenticación http que involucra tokens de seguridad (Bearer Token), generado por el
servicio de autenticación.

URL Pruebas:
https://8uw10ruhfj.execute-api.us-east-2.amazonaws.com/qa/signature/api/sign/getcertificate

URL Producción:
https://hdko60xft2.execute-api.us-east-2.amazonaws.com/pro/signature/api/sign/getcertificate

Página 16 de 25
Acuerdo de Interfaz Firma Centralizada

2.5.1 Parámetros de entrada

Objeto JSON que debe cumplir con los siguientes atributos

Nombre Tipo Tamaño Obligatorio Descripción

Identificador del
numeroDocumento Alfanumérico 20 Si
certificado digital

clave Alfanumérico 15 Si Clave del certificado

2.5.2 Ejemplo JSON de entrada

2.5.3 Respuesta

Como respuesta de la operación se va a devolver un JSON con la siguiente estructura:

Nombre Tipo Tamaño Obligatorio Descripción

Código de respuesta
codigoRespuesta Alfanumérico 5 Si obtenido del proceso
de firma

Descripción de la
mensaje Alfanumérico Si
respuesta

Código http del estado

httpStatus Numérico Si
de la transacción

Certificado de la root
rootca Alfanumérico MAX No
en base64

Certificado de la
subca Alfanumérico MAX No subordinada en
base64
Página 17 de 25
Acuerdo de Interfaz Firma Centralizada

Listado de Certificados
certificados No
certificados disponibles

Objeto Certificado

Nombre Tipo Tamaño Obligatorio Descripción

Identificador del
keyStoreUuid Alfanumérico Si
certificado

Fecha de inicio de
validFrom Alfanumérico Si
validez del certificado

Fecha de fin de validez

validTo Alfanumérico Si
del certificado

x509Certificate Alfanumérico MAX Si Certificado en base64

2.5.4 Ejemplo JSON de respuesta

Página 18 de 25
Acuerdo de Interfaz Firma Centralizada

2.6 Generar OTP

Operación POST que permite enviar un código y enviarlo vía mensaje de texto y correo
electrónico.

El método de acceso se realiza mediante Bearer Authentication el cual es un esquema

de autenticación http que involucra tokens de seguridad (Bearer Token), generado por el
servicio de autenticación.

URL Pruebas:
https://8uw10ruhfj.execute-api.us-east-2.amazonaws.com/qa/otp/api/otpclient/generate

URL Producción:
https://hdko60xft2.execute-api.us-east-2.amazonaws.com/pro/otp/api/otpclient/generate

2.6.1 Parámetros de entrada

Objeto JSON que debe cumplir con los siguientes atributos

Nombre Tipo Tamaño Obligatorio Descripción

Número de celular al cual
celular Alfanumérico 10 Si
es enviado el mensaje

mensaje Alfanumérico 160 Si Contenido del mensaje

Correo electrónico al que

email Alfanumérico 30 No
se envía el mensaje

2.6.2 Ejemplo JSON de entrada

Página 19 de 25
Acuerdo de Interfaz Firma Centralizada

2.6.3 Respuesta

Como respuesta de la operación se va a devolver un JSON con la siguiente estructura:

Nombre Tipo Tamaño Obligatorio Descripción

Código http del estado
httpStatus Numérico Si
de la transacción

Resultado de la
codigo Numérico Si
transacción

Detalle de la
descripcion Alfanumérico MAX Si
transacción

2.6.4 Ejemplo JSON de respuesta

2.7 Validar OTP

Operación POST que permite validar un código OTP enviado.

El método de acceso se realiza mediante Bearer Authentication el cual es un esquema

de autenticación http que involucra tokens de seguridad (Bearer Token), generado por el
servicio de autenticación.

URL Pruebas:
https://8uw10ruhfj.execute-api.us-east-2.amazonaws.com/qa/otp/api/otpclient/validate

URL Producción:
https://hdko60xft2.execute-api.us-east-2.amazonaws.com/pro/otp/api/otpclient/validate
Página 20 de 25
Acuerdo de Interfaz Firma Centralizada

2.7.1 Parámetros de entrada

Objeto JSON que debe cumplir con los siguientes atributos

Nombre Tipo Tamaño Obligatorio Descripción

Número de celular al cual
celular Alfanumérico 10 Si
es envió el mensaje

codigo Alfanumérico 160 Si Código OTP enviado

2.7.2 Ejemplo JSON de entrada

2.7.3 Respuesta

Como respuesta de la operación se va a devolver un JSON con la siguiente estructura:

Nombre Tipo Tamaño Obligatorio Descripción

Código http del estado
httpStatus Numérico Si
de la transacción

Resultado de la
codigo Numérico Si
transacción

Detalle de la
descripcion Alfanumérico MAX Si
transacción

Página 21 de 25
Acuerdo de Interfaz Firma Centralizada

2.7.4 Ejemplo JSON de respuesta

2.8 Estampar documento

Operación POST que permite realizar la estampa de un documento pdf con el envío de
un objeto JSON. Como resultado del estampado se obtendrá un objeto en formato JSON
con la respuesta de la transacción.
El método de acceso se realiza mediante Bearer Authentication el cual es un esquema
de autenticación http que involucra tokens de seguridad (Bearer Token), generado por el
servicio de autenticación.

URL Pruebas:
https://8uw10ruhfj.execute-api.us-east-2.amazonaws.com/qa/signature/api/sign/stamp

URL Producción:
https://hdko60xft2.execute-api.us-east-2.amazonaws.com/pro/signature/api/sign/stamp

2.8.1 Parámetros de entrada

Objeto JSON que debe cumplir con los siguientes atributos

Nombre Tipo Tamaño Obligatorio Descripción

usuario Alfanumérico 50 Si Usuario de la tsa

clave Alfanumérico 100 Si Clave de la tsa

Documento pdf en formato

base64 Alfanumérico 5 MB SI
base64

Página 22 de 25
Acuerdo de Interfaz Firma Centralizada

2.8.2 Ejemplo JSON de entrada

2.8.3 Respuesta

Como respuesta de la operación estampado de documento se va a devolver un JSON

con la siguiente estructura:

Nombre Tipo Tamaño Obligatorio Descripción

Código de respuesta
codigoRespuesta Alfanumérico 5 Si obtenido del proceso
de firma

Descripción de la
mensaje Alfanumérico Si
respuesta

Código http del estado

httpStatus Numérico Si
de la transacción

Documento estampado
base64 Alfanumérico MAX No
y codificado en base64

2.8.4 Ejemplo JSON de respuesta

El siguiente es un ejemplo JSON con el response de la petición

Página 23 de 25
Acuerdo de Interfaz Firma Centralizada

3. Tabla de tipos de documento

Código Descripción
1 Tarjeta de identidad
2 Cédula de ciudadanía
3 Cédula de extranjería
4 Pasaporte
5 Número de Identificación Tributaria

4. Valores de respuesta para atributo codigoRespuesta

Código Descripción
RS1 Transacción exitosa.
RS2 El paquete no tiene cupo para la
operación
RS3 Firmante no registrado
RS4 Es necesario el usuario y la clave
de la tsa
RS5 Es necesario el objeto
ImagenFirma para la firma
RS6 Es necesario especificar el Alto y el
Ancho para la firma
RS7 Es necesario especificar la posición
de la imagen
RS8 Es necesario especificar la imagen
para la firma
RS9 Es necesario especificar la página
para la firma
RS10 Error al validar los datos
RS11 Ocurrió un error al firmar el
documento
RS12 Clave incorrecta
RS13 Documento invalido
RS14 Usuario o clave de tsa inválidos
RS15 Código OPT invalido
RS16 Es necesario el campo base64
Página 24 de 25
Acuerdo de Interfaz Firma Centralizada

RS17 No tiene certificados disponibles

RS18 Tipo de documento invalido
RS19 Es necesario el hash

Página 25 de 25