API de integración con otros desarrollos tecnológicos
- Daniel Giraldo Giraldo (Unlicensed)
- soporte - ggallego - dalzate
- SIG
VERSIONAMIENTO DEL DOCUMENTO
Fecha | Versión | Autor | Descripción |
2021-09-10 | 0.1 | Cristhian David Sandoval Pazu | Elaboración de la versión inicial. |
2021-10-22 | 1.1 | Cristhian David Sandoval Pazu | Ajuste "base64String": "Reemplazar por un string base 64 pdf " |
2022-06-13 | 1.2 | Erika Marcela Romero Gómez | Agrega tabla que describe los parámetros del objeto json requerido para la creación de un proceso y añade ejemplo para cada tipo de proceso. Agrega información referente a los estados de un proceso. |
2022-08-05 | 1.3 | Richard Barboza | Agrega documentación V2 API para processcreatefull con el nuevo campo balanceType. |
APROBACIONES DEL DOCUMENTO
Fecha | Versión | Aprobador | Dependencia / Cargo |
2021-09-10 | 1.0 | Cristhian Sandoval | Desarrollador líder I+D+I |
2021-09-10 | 1.0 | Danny Guarin | Director Desarrollo de Negocios |
2021-10-29 | 1.1 | Cristhian Sandoval | Desarrollador líder I+D+I |
2021-10-29 | 1.1 | Danny Guarin | Director Desarrollo de Negocios |
2022-06-13 | 1.2 | Daniel Giraldo | Analista de pruebas |
2022-08-07 | 1.3 | Daniel Giraldo | Analista de pruebas |
DOCUMENTACIÓN SERVICIO WEB FIRMA ELECTRÓNICA
Este documento establece la definición de los métodos y los valores establecidos como parámetros para el consumo del aplicativo Firma Electrónica API en sistemas externos o aplicaciones clientes.
También se evidencian consideraciones y prerrequisitos necesarios para realizar una integración con otras soluciones.
TÉRMINOS GENERALES
1.1 Proceso
Un proceso es el conjunto de firmantes que tienen como propósito firmar electrónicamente un documento pdf.
Estados de un proceso:
Borrador (1): El proceso ha sido creado pero aún no tiene asociado un documento o firmantes.
Creado (2): El proceso ha sido creado satisfactoriamente con su documento y firmantes respectivos.
En proceso (3): El documento del proceso se encuentra parcialmente firmado.
Exitoso (4): El proceso ha finalizado exitosamente, es decir, todos los signatarios han firmado el documento.
Declinado (5): El proceso ha sido cancelado o anulado, por tanto ya no posee validez. Solo pueden tener estado declinado aquellos procesos que no hayan culminado exitosamente.
1.2 Estrategia Polling
Es una de las estrategias propuesta por Firma electrónica API para consultar el estado de un proceso periódicamente y si el proceso está terminado exitosamente retorna el documento pdf firmado en base 64.
1.3 Estrategia CallBack
Es una de las estrategias propuestas por Firma electrónica API para devolver el documento pdf firmado en base 64, en este caso es necesario que el sistema cliente implemente un end point al cual Firma electrónica API responderá cuando el proceso esté terminado exitosamente.
CREAR UN PROCESO.
Diagrama de secuencia “Creación de proceso”
2.1 Ir a la URL de la API suministrada
2.2 Ir a la sección Auth
2.3 Ingresar el request /Sign In
{
"email": "csandoval@tredasolutions.com",
"password": "%AL1h45g6Jw0PChDKKSXRpcFnw"
}
2.4 Obtener response /Sign In
2.5 Ir a la sección Authorize
2.6 Ingresar el token
Nota: actualmente el token tiene un tiempo máximo a expirar de 1 mes.
2.7 Ir a la sección Process
2.8 Ejecutar el request ProcessCreateFull: Ejemplos
Tipo de proceso “Solo yo”: Único firmante
{
"processTypeId": 1,
"signatureMethodId": 2,
"deadlineDays": 11,
"signatures": [
{
"processId": 0,
"authenticationMethodId": 3,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3108783885"
},
"phoneId": 0,
"email": "jhon.doe@email.com",
"personId": 0,
"person": {
"firstName": "Jhon",
"secondName": null,
"firstLastName": "Doe",
"secondLastName": null,
"identification": "1012402467",
"identificationTypeId": 1,
"typePersonId": 1
}
}
}
],
"documents": {
"fileName": "contrato prueba",
"documentTypeId": 1,
"base64String": "Reemplazar por un string base64 pdf"
},
"callback": "",
"subjectEmail": "Prueba demo mi primera firma",
"messageEmail": "primera firma desde la api firmaelectrónica",
"copyEmails": "juan.perez@email.com, nina.tul@email.com"
}
Nota: Recordar que la persona que firma en el tipo de proceso “Solo yo” debe ser la misma que está autenticada en la api.
Tipo de proceso “Otros y yo”: Mínimo 2 firmantes, máximo 10
{
"processTypeId": 2,
"signatureMethodId": 1,
"deadlineDays": 23,
"signatures": [
{
"processId": 0,
"authenticationMethodId": 2,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3108783885"
},
"phoneId": 0,
"email": "jhon.doe@email.com",
"personId": 0,
"person": {
"firstName": "Jhon",
"secondName": null,
"firstLastName": "Doe",
"secondLastName": null,
"identification": "1012402467",
"identificationTypeId": 1,
"typePersonId": 1
}
}
},
{
"processId": 0,
"authenticationMethodId": 1,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3114567894"
},
"phoneId": 0,
"email": "juan.perez@email.com",
"personId": 0,
"person": {
"firstName": "Juan",
"secondName": "Manuel",
"firstLastName": "Perez",
"secondLastName": "Ortiz",
"identification": "45784415",
"identificationTypeId": 1,
"typePersonId": 1
}
}
}
],
"documents": {
"fileName": "contrato prueba",
"documentTypeId": 1,
"base64String": "Reemplazar por un string base64 pdf"
},
"callback": "",
"subjectEmail": "Prueba demo mi primera firma",
"messageEmail": "primera firma desde la api firmaelectrónica",
"copyEmails": ""
}
Nota: Recordar que las personas que firman en el tipo de proceso “Otros y yo” debe ser la misma que está autenticada en la api, quien hace el papel del YO y otras personas ajenas.
Tipo de proceso “Solo Otros”: Mínimo 1 firmante, máximo 10
{
"processTypeId": 3,
"signatureMethodId": 2,
"deadlineDays": 5,
"signatures": [
{
"processId": 0,
"authenticationMethodId": 2,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3108783885"
},
"phoneId": 0,
"email": "jhon.doe@email.com",
"personId": 0,
"person": {
"firstName": "Jhon",
"secondName": null,
"firstLastName": "Doe",
"secondLastName": null,
"identification": "1012402467",
"identificationTypeId": 1,
"typePersonId": 1
}
}
}
],
"documents": {
"fileName": "contrato prueba",
"documentTypeId": 1,
"base64String": "Reemplazar por un string base64 pdf"
},
"callback": "",
"subjectEmail": "Prueba demo mi primera firma",
"messageEmail": "primera firma desde la api firmaelectronica",
"copyEmails": "juan.perez@email.com, nina.tul@email.com"
}
Nota: Recordar que las personas que firman en el tipo de proceso “Solo otros” son otras personas ajenas a quien se encuentra autenticado.
2.9 Descripción de parámetros request ProcessCreateFull
Parámetro | Descripción | Tipo | Obligatorio |
processTypeId | Tipo de proceso a crear. Toma valores entre 1 y 3.
(Único firmante donde la persona que firma es la persona que se encuentra autenticada)
(Mínimo dos firmantes donde quienes firman son la persona que se encuentra autenticada y otras personas.)
(Solo firman personas ajenas a quien se encuentra autenticado) | Int | SI |
signatureMethodId | Método de firma con el cual se creará el proceso. Toma como valor 1 o 2.
| Int | SI |
deadlineDays | Plazo máximo en días para que todos los signatarios firmen el documento asociado al proceso. | Int | SI |
signatures[{...}] | Listado de firmantes vinculados al proceso. Este campo va sujeto a lo indicado en el “processTypeId”. -Si el tipo de proceso es 1 (Solo yo), se debe enviar los datos únicamente de la persona autenticada. -Si el tipo de proceso es 2 (Otros y yo), se debe enviar los datos de la persona autenticada, la cual representa el yo y los datos de las demás personas asociadas hasta un máximo de 10, siendo el mínimo 2 (incluyendo el yo). -Si el tipo de proceso es 3 (Solo otros), la persona autenticada NO debe hacer parte de este listado y se envían los datos de las personas asociadas hasta un máximo de 10, siendo el mínimo 2
Compuesto por los siguientes parámetros: processId, authenticationMethodId, contactInformation. | Array | SI |
processId (parámetro del array signatures) | Debe tener como valor 0 | Int | SI |
authenticationMethodId (parámetro del array signatures) | Método de autenticación OTP (One-Time Password) con el cual el firmante validará su proceso de firma. Toma un valor entre 1 y 3
(el código de único uso será enviado al usuario por medio de una llamada telefónica al número de celular especificado en el parámetro number)
(el código de único uso será enviado al usuario por medio de un mensaje de texto al número de celular especificado en el parámetro number)
(el código de único uso será enviado al usuario al correo electrónico especificado en el parámetro email) | Int | SI |
contactInformation{} (objeto del array signatures) | Objeto que contiene la información de contacto del firmante y asociado al proceso a crear.
Compuesto por los siguientes parámetros: phone, phoneId, email, personId, person. | Object | SI |
phone{} (objeto de contactInformation) | Objeto que contiene la información del número de celular asociado al firmante.
Compuesto por los siguientes parámetros: indicative, number. | Object | SI |
indicative (parámetro del objeto phone) | Indicativo de país asociado al número de celular del firmante. Ejemplo para Colombia: 57 | String | SI |
number (parámetro del objeto phone) | Número celular del firmante. Máximo de caracteres para Colombia: 10. Máximo de caracteres para números extranjeros: 20. | String | SI |
phoneId (parámetro de contactInformation) | Debe tener como valor 0. | Int | SI |
(parámetro de contactInformation) | Correo electrónico del firmante. Máximo: 100 caracteres | String | SI |
personId (parámetro de contactInformation) | Debe tener como valor 0 | Int | SI |
person{} (objeto de contactInformation) | Objeto que contiene información básica asociada al firmante.
Compuesto por los siguientes parámetros: firstName, secondName, firstLastName, secondLastName, identification, identificationTypeId, typePersonId | Int | SI |
firstName (parámetro de objeto person) | Primer nombre del firmante. Mínimo: 2 caracteres Máximo: 100 caracteres | String | SI |
secondName (parámetro de objeto person) | Segundo nombre del firmante. Mínimo: 2 caracteres Máximo: 100 caracteres
En caso de no enviarlo su valor debe ser null. | String | NO |
firstLastName (parámetro de objeto person) | Primer apellido del firmante. Mínimo: 2 caracteres Máximo: 100 caracteres | String | SI |
secondLastName (parámetro de objeto person) | Segundo apellido del firmante. Mínimo: 2 caracteres Máximo: 100 caracteres
En caso de no enviarlo su valor debe ser null. | String | NO |
identification (parámetro de objeto person) | Número de identificación del firmante.
Mínimo: 5 caracteres Máximo: 12 caracteres
Mínimo: 5 caracteres Máximo: 15 caracteres | String | SI |
identificationTypeId (parámetro de objeto person) | Tipo de identificación del firmante. Toma dos posibles valores:
| Int | SI |
typePersonId (parámetro de objeto person) | Tipo de persona del firmante. Toma dos posibles valores:
| Int | SI |
documents[{...}] | Objeto que contiene la información del documento a firmar.
Compuesto por los siguientes parámetros: filename, documentTypeId, base64String.. | Object | SI |
filename (parámetro de objeto documents) | Nombre del documento pdf Máximo: 100 caracteres | String | SI |
documentTypeId (parámetro de objeto documents) | Debe tener como valor 1 | Int | SI |
base64String (parámetro de objeto documents) | String con el documento pdf codificado en base64 | String | SI |
callback | Es la url donde se debe enviar el documento cuando el proceso se termine (sea firmado exitosamente por todos los involucrados). Esta url es un desarrollo de cada cliente
Este parámetro hace referencia a la estrategia callback mencionada en la sección 1.3 | String | NO |
subjectEmail | Asunto que se desea haga parte del correo electrónico con la solicitud de firma que se envía a los firmantes. En caso de no enviarse este parámetro, por defecto el asunto es solicitud de firma. Máximo: 150 caracteres | String | NO |
messageEmail | Mensaje que se desea haga parte del correo electrónico con la solicitud de firma que se envía a los firmantes. En caso de no enviarse este parámetro, no hay un mensaje por defecto. Máximo: 500 caracteres | String | NO |
copyEmails | Listado separado por comas de los correos electrónicos a los cuales se enviará una copia del documento una vez firmado por todos los involucrados. Aquí no se ingresa ningún correo que ya esté asociado a los firmantes. Máximo string: 255 caracteres Máximo de correos electrónicos permitidos: 10 | String | NO |
2.10 Obtener el response ProcessCreateFull
{
"uuid": "string"
}
OBTENER DOCUMENTO “ESTRATEGIA POLLING”.
Diagrama de secuencia obtener documento
Nota: el parámetro uuid enviado es el retornado en el response de processCreateFull.
3.1 Request Document
curl --location --request GET 'https://{dominio-api-entorno}/api/v1/Document/ByUUID/uuid' \
--header 'Authorization: Bearer Token'
3.2 Response Sign In
{
"documents": [Base64String],
"uuid": "string"
}
OBTENER DOCUMENTO “ESTRATEGIA CALLBACK”. (RECOMENDADO)
Diagrama de secuencia obtener documento
4.1 Implementar Callback Request Document
Los clientes deben implementar un api rest que contenga un método tipo post, y que reciba el siguiente request.
{
"uuid":"string",
"document":"Base64String"
}
Más información dirigirse a los procesos detallados en la wiki
Response Sign I
No aplica.
CREAR UN PROCESO CON LA V2 DE LA API
5.1 Ir a la parte superior y seleccionar la versión 2 de la API
5.2 Ir a la sección Process V2
5.3 Ejecutar el request ProcessCreateFull V2:
Para la V2 de la API se necesitará enviar al tipo de saldo(BalanceTypeId), 1 para saldo por firmas y 2 para saldo por documentos. Es necesario que los firmantes tengan el mismo método de autenticación cuando el tipo de saldo sea por documentos (BalanceTypeId igual a 2), por ejemplo por SMS(2) o Email(3). Nota: el tipo de autenticación por llamada(1) no está habilitado para saldos por documentos.
Ejemplos
Tipo de proceso “Solo yo” - Saldo por documentos: Único firmante
{
"processTypeId": 1,
"signatureMethodId": 2,
"deadlineDays": 11,
"balanceTypeId": 2,
"signatures": [
{
"processId": 0,
"authenticationMethodId": 3,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3108783885"
},
"phoneId": 0,
"email": "jhon.doe@email.com",
"personId": 0,
"person": {
"firstName": "Jhon",
"secondName": null,
"firstLastName": "Doe",
"secondLastName": null,
"identification": "1012402467",
"identificationTypeId": 1,
"typePersonId": 1
}
}
}
],
"documents": {
"fileName": "contrato prueba",
"documentTypeId": 1,
"base64String": "Reemplazar por un string base64 pdf"
},
"callback": "",
"subjectEmail": "Prueba demo mi primera firma",
"messageEmail": "primera firma desde la api firmaelectrónica",
"copyEmails": "juan.perez@email.com, nina.tul@email.com"
}
Nota: Recordar que la persona que firma en el tipo de proceso “Solo yo” debe ser la misma que está autenticada en la api, y con tipo de saldo por documentos - Email (Todos los firmantes deben de tener el mismo método de autenticación, en este caso de ejemplo, es el Email).
Tipo de proceso “Otros y yo” - Saldo por documentos: Mínimo 2 firmantes, máximo 10
{
"processTypeId": 2,
"signatureMethodId": 1,
"deadlineDays": 23,
"balanceTypeId": 2,
"signatures": [
{
"processId": 0,
"authenticationMethodId": 2,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3108783885"
},
"phoneId": 0,
"email": "jhon.doe@email.com",
"personId": 0,
"person": {
"firstName": "Jhon",
"secondName": null,
"firstLastName": "Doe",
"secondLastName": null,
"identification": "1012402467",
"identificationTypeId": 1,
"typePersonId": 1
}
}
},
{
"processId": 0,
"authenticationMethodId": 2,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3114567894"
},
"phoneId": 0,
"email": "juan.perez@email.com",
"personId": 0,
"person": {
"firstName": "Juan",
"secondName": "Manuel",
"firstLastName": "Perez",
"secondLastName": "Ortiz",
"identification": "45784415",
"identificationTypeId": 1,
"typePersonId": 1
}
}
}
],
"documents": {
"fileName": "contrato prueba",
"documentTypeId": 1,
"base64String": "Reemplazar por un string base64 pdf"
},
"callback": "",
"subjectEmail": "Prueba demo mi primera firma",
"messageEmail": "primera firma desde la api firmaelectrónica",
"copyEmails": ""
}
Nota: Recordar que las personas que firman en el tipo de proceso “Otros y yo” debe ser la misma que está autenticada en la api, quien hace el papel del YO y otras personas ajenas, además como es con tipo de saldo por documentos - SMS (Todos los firmantes deben de tener el mismo método de autenticación, en este caso SMS).
Tipo de proceso “Solo Otros”- Saldo por documentos: Mínimo 1 firmante, máximo 10
{
"processTypeId": 3,
"signatureMethodId": 2,
"balanceTypeId": 2,
"deadlineDays": 5,
"signatures": [
{
"processId": 0,
"authenticationMethodId": 2,
"contactInformation": {
"phone": {
"indicative": "57",
"number": "3108783885"
},
"phoneId": 0,
"email": "jhon.doe@email.com",
"personId": 0,
"person": {
"firstName": "Jhon",
"secondName": null,
"firstLastName": "Doe",
"secondLastName": null,
"identification": "1012402467",
"identificationTypeId": 1,
"typePersonId": 1
}
}
}
],
"documents": {
"fileName": "contrato prueba",
"documentTypeId": 1,
"base64String": "Reemplazar por un string base64 pdf"
},
"callback": "",
"subjectEmail": "Prueba demo mi primera firma",
"messageEmail": "primera firma desde la api firmaelectrónica",
"copyEmails": "juan.perez@email.com, nina.tul@email.com"
}
Nota: Recordar que las personas que firman en el tipo de proceso “Solo otros” son otras personas ajenas a quien se encuentra autenticado, con tipo de saldo por documentos - SMS (Todos los firmantes deben de tener el mismo método de autenticación, en este caso SMS).
5.4 Descripción de parámetros request ProcessCreateFull V2
Parámetro | Descripción | Tipo | Obligatorio |
balanceTypeId | Método de tipo de saldo con el cual se creará el proceso. Toma como valor 1 o 2.
| Int | SI |